工具栏

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

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

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'
        }
    ]
}

文档弹窗

文档弹窗可以配置是否支持动态文档转码或者静态文件转码。其中supportPptToH5设置是否支持动态转码，默认配置为false。supportDocToPic设置是否支持静态转码，默认配置为true。supportUploadMedia设置是否支持上传音视频文件。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' 
            }
        ]
    }
]