文档反馈
文档反馈

工具栏

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

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

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

初始化

启动工具栏仅需两步:

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

toolCollection.show()

配置工具栏

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

toolCollection_position

toolCollection.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代表一个子功能。子功能之间的公共属性如下。

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

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

显示/隐藏部分工具

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

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

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

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

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

调整工具栏配置

添加工具

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

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

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

移除工具

removeTool可以移除指定工具。

toolCollection.removeTool:(opt: {position?: IPosition, name: string})
/**
 * 移除视频
 */
toolCollection.removeTool({name: 'video'})
/**
 * 移除左侧工具栏的视频(如果有)
 */
toolCollection.removeTool({position: 'left', name: 'video'})

添加子工具

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

toolCollection.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移除子工具

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

自定义按钮

以'custom-xxx'命名的按钮为自定义按钮。通过toolCollection.addToolEventListener能够监听按钮的点击事件

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

toolCollection.addToolEventListener('custom-toggle', () => {
    console.log('toggle')
})

具体工具配置

调色盘

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

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

画笔粗细

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

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

预览工具

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

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

收纳工具

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

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

multiInOne

×

反馈成功

非常感谢您的反馈,我们会继续努力做得更好。