工具栏配置

更新时间: 2024/07/24 13:59:48

工具栏

互动白板的功能非常的丰富,既包含画笔,图形,选择,拖动等教具,又包括撤销,重做,清空,复制等基本操作,还包括视角管理,页面控制,切换等扩展功能。面对如此丰富的功能,在接入互动白板时,工具栏的开发也是一个小挑战。

首先,工具栏的布局方式有很多可能性。有些产品可能会将所有的工具放在底部,或者左侧。有些产品会按照功能模块,将不同的功能模块放在容器的不同位置。在桌面端和移动端,由于屏幕尺寸的不同,工具栏的布局风格也会有很大差异。其次,客户端运行在不同终端时,需要考虑屏幕尺寸的差异。在不同屏幕尺寸下,工具栏大小需要自动缩放,避免明显的重叠,超出界面等问题。最后,工具栏的状态需要和应用绑定,这需要开发者对于sdk的接口比较熟悉。

针对这些问题,云信互动白板提供ToolCollection工具栏组件。它能够帮助用户快速的根据设计稿的布局定制工具栏。且它会计算工具栏容器之间的大小和位置,避免工具栏超出范围,或者相互重叠。

初始化

启动工具栏仅需两步:

  1. ToolCollection.getInstance:初始化工具栏实例。绑定容器和白板实例
  2. toolCollection.show: 显示工具栏
jstoolCollection = ToolCollection.getInstance({
    container: HTMLDivElement,      //工具栏容器。大部分场景下,该容器和whiteboardSDK.getInstance绑定的容器相同
    handler: drawPlugin,            //whiteboardSDK.joinRoom之后返回的绘制实例
    options: {
        platform: IPlatform,        //web,ios,android,pc,mac,pad。  web,pc,mac共享一套默认的工具栏,android,ios, pad共享另一套
    }
})

toolCollection.show()

配置工具栏

通过toolCollection.setContainerOptions,可以修改工具栏的具体配置。containerOptions是一个数组。数组内每个元素代表一个容器。以云信互动白板demo为例,它包含了四个容器,容器的position分别为left, bottomLeft, bottomRight, topRight

toolCollection_position

jstoolCollection.setContainerOptions(containerOptions: Array<{
    position: 'leftBottom'| 'left'| 'leftTop'| 'topLeft'| 'top'| 'topRight'| 'rightTop'| 'right'| 'rightBottom'| 'bottomRight'| 'bottom'| 'bottomLeft'
    marginLeft?: number      //单位为px
    marginRight?: number
    marginTop?: number
    marginBottom?: number
    items: Array<IUnitOption>
}>)

通过marginLeft, marginRight, marginTop, marginBottom可以调节容器和边框,以及相互之间的最小间隔。单位默认为px。这些参数为可选参数,默认值为16px

通过items设置容器内包含哪些子功能。云信互动白板提供了约30个子功能,用户可以自由将其组合在不同的容器中。

items

每个item代表一个子功能。子功能之间的公共属性如下。

js    tool: string        //组件的名字。每个名字和一个具体的功能绑定。下面的文档会介绍有哪些可用的工具
    /**
     * size默认为1
     * size表示元素占据几个位置
     * 常规元素占据一格位置。翻页工具会占据约5-6格位置
     */
    size?: number
    /**
     * 按钮图片。添加此属性可以覆盖默认图片
     */
    backgroundImage?: string
    /**
     * 鼠标悬浮在按钮上时的提示文本
     */
    hint?: string

部分按钮有额外的属性,详情请参考SDK接口文档

显示/隐藏部分工具

显示/隐藏工具栏中的容器,子组件。可用于开启,关闭编辑时,设置工具栏的可见性。

jstoolCollection.setVisibility(setting: {
    [position: string]: {
        visible: boolean,
        exclude?: Array<string>
    }
})

上述代码中的position即为containerOptions中每个元素的position属性。

若传入空对象,则所有元素设置为可见。通过position指定特定的工具栏。visible控制该位置的工具栏是否可见。

visible为false,则exclude清单内的子元素可见。 若visible为true,则exclude清单内的子元素不可见。

调整工具栏配置

添加工具

addOrSetTool可以指定工具栏容器,添加一个按钮,或者替换一个已有按钮。

jstoolCollection.addOrSetTool(opt: {position: IPosition, item: IUnitOption, insertAfterTool?: string})

/**
 * 添加上传视频按钮
 */
toolCollection.addOrSetTool({
    position: isMobile ? 'bottomRight' : 'left',
    item: {
        tool: 'docUpload'
    },
    insertAfterTool: 'opacity'
})

移除工具

removeTool可以移除指定工具。

jstoolCollection.removeTool:(opt: {position?: IPosition, name: string})
/**
 * 移除资源上传按钮 
 */
toolCollection.removeTool({name: 'docUpload'})
/**
 * 移除左侧工具栏的资源上传按钮(如果有)
 */
toolCollection.removeTool({position: 'left', name: 'docUpload'})

添加子工具

addOrSetSubItem在指定的工具集合中添加子工具。目前支持添加子工具的按钮有:shapeSelect, multiInOne

jstoolCollection.addOrSetSubItem: (opt: {position?: IPosition, baseTool: string, subItem: IUnitOption, insertAfterTool?: string})

/**
 * 在图形集合中,添加自定义图形:triangle
 */
toolCollection.addOrSetSubItem({
    baseTool: 'shapeSelect',
    subItem: {
        tool: 'triangle',
        hint: '等腰三角形',
        backgroundImage: triangleSVG
    }, 
    insertAfterTool: 'ellipse-fill'
})

移除子工具

removeSubItem移除子工具

jstoolCollection.removeSubItem:(opt: {position?: IPosition, baseTool: string, subItemName: string})
/**
 *
 */
toolCollection.removeSubItem:({
    baseTool: 'shapeSelect', 
    subItemName: 'triangle'
})

自定义按钮

custom-xxx命名的按钮为自定义按钮。通过toolCollection.on能够监听按钮的点击事件。注意3.6.0版本之前,需要使用addToolEventListener监听自定义按钮的点击事件

jsitems: [
    ...otherIcons,
    {
        tool: 'custom-toggle',
        hint: '自定义按钮',
        backgroundImage: toggleImageUrl
    },
]

toolCollection.on('iconClick', (toolName) => {
    if (toolName === 'custom-toggle') {
        console.log('toggle')
    }
})

自定义弹窗按钮

custom-popup-xxx命名的按钮为自定义弹窗按钮。点击该按钮,按钮的位置会新增一个弹窗。用户点击其它工具栏按钮,或者页面其它空白位置时,弹窗会消失。弹窗的位置需要用户设置样式进行调整。

以下是实现自定义弹窗按钮的示例代码:

jstoolCollection.addOrSetTool({
    position: 'left',
    item: {
        tool: 'custom-popup-macro',
        hint: '图章',
        backgroundImage: Stamp,
        //渲染弹窗内容
        onMount: (container) => {
            ReactDOM.render(
                <MacroPopup
                drawPlugin={app}
                />, 
                container
            )
        }
    }
})

MacroPopup是一个React组件,其render函数为:

jsrender() {
    return (
        <div className='stamp-popup'>
            <div className='section'>
            <div className='stamp-header'>
                图章
            </div>
        </div>
    )
}

以下是设置弹窗位置的示例代码:

css.stamp-popup {
    position: absolute;
    left: 50px;
    padding: 8px;
    background: white;
    width: 180px;
    transform: translateY(-50%);
}

自定义状态按钮

custom-state-xxx命名的按钮为自定义状态按钮。通过toolCollection.on能够监听按钮的点击事件。注意3.6.0版本之前,需要使用addToolEventListener监听自定义按钮的点击事件

jsitems: [
    ...otherIcons,
    {
        tool: 'custom-state-toggle-editable',
        hint: '切换编辑',
        clickCb: (currState) => {
            if (currState === 'editable') return 'non-editable'
            else return 'editable'
        },
        defaultState: 'editable',
        backgroundImageByState: {
            'editable': 'url_of_editable_state_icon',
            'non_editable': 'url_of_non_editable_state_icon'
        }
    }
]

toolCollection.on('iconClick', (toolName: string, opt: {
    //点击前的state
    state: string,
    //点击后的state
    newState: string
}) => {
    if (toolName === 'custom-state-toggle-editable') {
        if (opt.newState === 'editable') {
            drawPlugin.enableDraw(true)
        } else {
            drawPlugin.enableDraw(false)
        }
    }
})

具体工具配置

完整的工具栏组件配置请参考:工具栏组件

调色盘

3.1.2版本开始, 支持用户自己设置调色盘颜色。如果用户不传入colorArray, 则会使用默认的12个配色。border属性为颜色圆形按钮的边框颜色。如果颜色颜色偏浅,可以设置border,避免该颜色的圆形按钮无法看清。

js{
    tool: 'platte',
    hint: '调色盘',
    colorArray?: Array<{
        color: string,
        border?: string
    }>
}

画笔粗细

3.1.2版本开始,支持用户配置最大最小画笔粗细,以及画笔粗细的最小间隔。默认最小为1,最大为30,最小间隔为1。配置方法为:

js{
    tool: 'widthResize',
    hint: '画笔粗细',
    min?: number,
    max?: number,
    step?: number
}

预览工具

预览工具支持设置从页面左侧还是右侧滑出预览弹窗

js{
    tool: 'preview',
    hint: '预览',
    previewSlidePoisition: 'left' | 'right'   //从左侧还是右侧滑出弹窗
}

3.6.1版本后,在board为文档时,预览工具还可以选择是白板模式还是文档模式白板模式会在预览图中最大化当前白板容器内的视角。文档模式则会在预览图中最大化文档显示。设置方法如下:

jsdrawPlugin.setAppConfig({
    previewMode: 'fitDoc' | 'fitContainer'
})

收纳工具

移动端的屏幕尺寸较小,如果要将所有工具放在屏幕上,会让页面显得十分的臃肿。可以使用multiInOne工具避免这个问题。multiInOne将子功能收藏在二级菜单之中,只有点击时才会显示出来。

js{
    tool: 'multiInOne',
    hint: '更多',
    /**
     * 二级菜单一行显示多少个元素。默认为4
     */
    itemPerRow: 4,
    /**
     * subItems的配置规则和containerOptions中容器内items配置规则一样
     */
    subItems: [
        {
            tool: 'element-eraser'
        },
        {
            tool: 'clear'
        },
        {
            tool: 'undo'
        },
        {
            tool: 'redo'
        },
        {
            tool: 'image'
        },
        {
            tool: 'exportImage'
        }
    ]
}

multiInOne

文档弹窗

文档弹窗可以配置是否支持动态文档转码或者静态文件转码。其中supportPptToH5设置是否支持动态转码,默认配置为falsesupportDocToPic设置是否支持静态转码,默认配置为truesupportUploadMedia设置是否支持上传音视频文件。supportTransMedia支持是否上传音视频文件并转码。

js{
    tool: 'docUpload',
    hint: '上传资源',
    supportPptToH5: true,
    supportDocToPic: true,
    supportUploadMedia: true,
    supportTransMedia: true
}

默认工具栏配置

ToolCollection.getInstance时,以及setContainerOptions时未传入工具栏配置,则会根据ToolCollection.getInstance时传入的platform来设置默认的工具栏配置。下面分别是桌面端(web, pc, mac)和移动端默认的工具栏配置项(ios, android, pad)

桌面端

js[
    {
        position: 'left',
        items: [
            {
                tool: 'select',
                hint: '选择'
            },
            {
                tool: 'pen',
                hint: '涂鸦'
            },
            {
                tool: 'shapeSelect',
                hint: '图形选择'
            },
            {
                tool: 'text',
                hint: '文本'
            },
            {
                tool: 'laser',
                hint: '激光笔'
            },
            {
                tool: 'element-eraser',
                hint: '橡皮擦'
            },
            {
                tool: 'clear',
                hint: '清空'
            },
            {
                tool: 'undo',
                hint: '撤销'
            },
            {
                tool: 'redo',
                hint: '重做'
            },
            {
                tool: 'pan',
                hint: '平移'
            },
            {
                tool: 'image',
                hint: '图片'
            },
            {
                tool: 'uploadCenter',
                hint: '文档、音视频上传'
                supportPptToH5: true,
                supportDocToPic: true,
                supportUploadMedia: true,
                supportTransMedia: true
            },
            {
                tool: 'exportImage',
                hint: '导出图片'
            },
            {
                tool: 'uploadLog',
                hint: '上传日志'
            }
        ]
    },
    {
        position: 'bottomLeft',
        items: [
            {
                tool: 'fitToContentDoc'
            },
            {
                tool: 'zoomOut',
                hint: '缩小'
            },
            {
                tool: 'zoomLevel'
            },
            {
                tool: 'zoomIn',
                hint: '放大'
            },
            {
                tool: 'visionControl',
                hint: '视角同步'
            },
            {
                tool: 'visionLock',
                hint: '视角模式切换'
            }
        ]
    },
    {
        position: 'bottomRight',
        items: [
            {
                tool: 'firstPage',
                hint: '第一页'
            },
            {
                tool: 'prevPage',
                hint: '上一页'
            },
            {
                tool: 'pageInfo'
            },
            {
                tool: 'nextPage',
                hint: '下一页'
            },
            {
                tool: 'lastPage',
                hint: '最后一页'
            },
            {
                tool: 'preview',
                hint: '预览',
                previewSliderPosition: 'right'                    
            }
        ]
    },
    {
        position: 'topRight',
        items: [
            {
                tool: 'docSelect'
            }
        ]
    }
]

移动端

js[
    {
        position: 'bottomRight',
        items: [
            {
                tool: 'select',
                hint: '选择'
            },
            {
                tool: 'pen',
                hint: '涂鸦',
                stack: 'horizontal'
            },
            {
                tool: 'shapeSelect',
                hint: '图形选择'
            },
            {
                tool: 'multiInOne',
                hint: '更多'
                subItems: [
                    {
                        tool: 'element-eraser'
                    },
                    {
                        tool: 'clear'
                    },
                    {
                        tool: 'undo'
                    },
                    {
                        tool: 'redo'
                    },
                    {
                        tool: 'image'
                    },
                    {
                        tool: 'exportImage'
                    }
                ]
            }
        ]
    },
    {
        position: 'topRight',
        items: [
            {
                tool: 'multiInOne',
                hint: '更多',
                subItems: [
                    {
                        tool: 'uploadCenter',
                        hint: '文档、音视频上传'
                        supportPptToH5: true,
                        supportDocToPic: true,
                        supportUploadMedia: true,
                        supportTransMedia: true
                    },
                    {
                        tool: 'fitToContent'
                    },
                    {
                        tool: 'fitToDoc'
                    },
                    {
                        tool: 'pan'
                    },
                    {
                        tool: 'zoomIn'
                    },
                    {
                        tool: 'zoomOut'
                    },
                    {
                        tool: 'visionControl'
                    },
                    {
                        tool: 'visionLock'
                    },
                    {
                        tool: 'uploadLog',
                        hint: '日志上传'
                    }
                ]
            },
            {
                tool: 'zoomLevel',
                size: 2
            }
        ]
    },
    {
        position: 'topLeft',
        items: [
            {
                tool: 'pageBoardInfo'
            },
            {
                tool: 'preview',
                hint: '预览'
                previewSliderPosition: 'right' 
            }
        ]
    }
]
此文档是否对你有帮助?
有帮助
去反馈
  • 工具栏
  • 初始化
  • 配置工具栏
  • items
  • 显示/隐藏部分工具
  • 调整工具栏配置
  • 添加工具
  • 移除工具
  • 添加子工具
  • 移除子工具
  • 自定义按钮
  • 自定义弹窗按钮
  • 自定义状态按钮
  • 具体工具配置
  • 调色盘
  • 画笔粗细
  • 预览工具
  • 收纳工具
  • 文档弹窗
  • 默认工具栏配置
  • 桌面端
  • 移动端