文档反馈
文档反馈

SDK API接口说明

云信提供的SDK包括 白板(WhiteBoard)、绘制(drawPlugin)、工具(ToolCollection)和回放(RecordPlayer)四大模块,各模块API接口详细说明如下:

WhiteBoardSDK

WhiteBoardSDK.getInstance

获取whiteboardSDK实例。该实例主要用于管理房间状态。

const sdk = WhiteBoardSDK.getInstance({
    appKey: string
    account: string  
    nickname: string            //非必须, 会用于显示鼠标坐标以及选择框          
    token: string               
    record: boolean             //是否开启录制
    container: HTMLDivElement   //白板绑定的Dom容器
    platform: IPlatform,        //web,ios,android,pc,mac,pad
})

joinRoom

加入房间。详情请参考房间状态管理

sdk
    .joinRoom(
        {
            channel: '871239'       //房间名字
            createRoom: true        //是否先创建房间,建议设置为true
        },
        {
            ondisconnected: (err) => {}
            onwillreconnect: () => {}
            onconnected: () => {}
        }
    )
    .then(drawPlugin => {
        /**
         * 初始化设置白板和工具栏
         */
    })
    .catch(err => {
        /**
         * 加入房间失败。根据err排查错误原因
         */
    })

destroy

断开连接。注意房间需要在每个客户端均调用此方法,或者所有用户均以关闭tab,或者断开连接超过1分钟,服务器中的房间才会被销毁。

sdk.destroy()

getUid

返回当前用户的uid。可用于获取录像文件

whiteboardSDK.getUid()

getChannelId

返回当前房间的cid。可用于获取录像文件

whiteboardSDK.getChannelId()

drawPlugin

drawPlugin是白板绘制的核心模块。开发者可以调用drawPlugin提供的接口实现各种功能。ToolCollection组件的各种功能就是基于drawPlugin开放的接口完成的。

getStrokeWidth

获取当前画笔粗细

const width = drawPlugin.getStrokeWidth()

getColor

获取当前画笔颜色

const width = drawPlugin.getColor()

getCurrTool

获取当前教具名称

const tool = drawPlugin.getCurrTool()

getRedoCount

获取当前可以redo的次数

const count = drawPlugin.getRedoCount()

getUndoCount

获取当前可以undo的次数

const count = drawPlugin.getUndoCount()

isClearAvailable

白板中是否存在元素,可以执行清空操作

const canClear = drawPlugin.isClearAvailable()

getSelectedIds

获取白板中被选中的元素的id数组。可用于判断是否能执行复制操作

const selectedIds = drawPlugin.getSelectedIds()

getZoomFactor

获取当前缩放比例。可用于显示缩放百分比

const zoomFactor = drawPlugin.getZoomFactor()

hasBackground

判断当前页面是否有背景图

const pageHasBackground = drawPlugin.hasBackground()

getPageInfos

获取当前文档的页面结构。包含每个页面的内部索引组成的数组。以及当前页面的内部索引

const pageInfos = drawPlugin.getPageInfos()
// {
//     pageNames: Array<string>  //这里的string都是数字
//     currPage: number
// }

getBoardInfos

获取当前房间的文档结构。包含文档名字列表,以及当前展示的文档

const boardInfos = drawPlugin.getBoardInfos()
// {
//     boardNames: Array<string>
//     currBoard: string
// }

getPreviewsOfBoard

获取文档的所有页面的预览图。返回值为base64字符串组成的数组。若预览图未准备好,数组中对应的位置会返回空字符串。

const previews = drawPlugin.getPreviewsOfBoard()

setAppConfig

设置白板配置。目前仅开放设置白板的背景色。后续将陆续开放更多的接口。

drawPlugin.setAppConfig({
    canvas_bg_color: 'rgba(0,0,0,0)'    //设置背景色为透明
})

enableDraw

是否允许编辑

drawPlugin.enableDraw(enable: boolean)

addImage

添加图片。图片默认添加至白板中心位置。

drawPlugin.addImage({
    url: string,
    width: number,
    height: number
})

setPageBackground

设置页面背景图片。图片默认添加在白板的世界坐标系的中心位置,即白板未进行缩放平移时的中心位置。

drawPlugin.setPageBackground({
    url: string,
    width: number,
    height: number
})

addDoc

添加文档。开发者可以通过addDoc传入自己转码得到的文档。ToolCollection支持快速配置文档转码功能。目前文档转码,以及添加文档只支持多页图片组成的文档。带动画的ppt文档正在开发中。

drawPlugin.addDoc({
    docName: string,
    params: Array<{
        url: string,
        width: number,
        height: number
    }>
})

setTool

设置当前教具

/**
 * 目前默认的教具包含:
 * select, pen, pen-arrow, line, line-arrow, rect, ellipse, laser, text
*  element-eraser, pan
 */
drawPlugin.setTool(toolName: IToolName)

setColor

设置画笔颜色。目前ToolCollection中调色盘中固有颜色列表如下。建议用户设置颜色时选择其中之一。

[
    'rgb(0,0,0)',
    'rgb(255,255,255)',
    'rgb(224,32,32)',
    'rgb(250,100,0)',
    'rgb(247,181,0)',
    'rgb(109,212,0)',
    'rgb(68,215,182)',
    'rgb(50,197,255)',
    'rgb(0,145,255)',
    'rgb(98,54,255)',
    'rgb(182,32,224)',
    'rgb(109,114,120)'
]
drawPlugin.setColor(color: string)

setShapeFill

选中rect或者ellipse时,设置是否填充图形

drawPlugin.setShapeFill(isFill: boolean, target: 'rect' | 'ellipse' | undefined)

setStrokeWidth

设置画笔粗细。默认工具栏中支持画笔粗细从1到30连续变化。默认画笔粗细为5

drawPlugin.setStrokeWidth(width: number)

setShowCursor

是否显示鼠标位置,默认为否。

drawPlugin.setShowCursor(value: boolean)

resetCamera

重置白板位置

/**
 * animate: 是否通过动画过渡到重置后的位置
 */
drawPlugin.resetCamera(animate: boolean)

fitToContent

适配白板窗口至包含全部内容

/**
 * animate: 是否通过动画过渡到重置后的位置
 */
drawPlugin.fitToContent(animate: boolean)

fitToDoc

适配白板窗口至包含背景图(通过addDoc或者setPageBackground添加的图片)

/**
 * animate: 是否通过动画过渡到重置后的位置
 */
drawPlugin.fitToDoc(animate: boolean)

setCameraBound

设置当前白板容器对应的世界坐标系。由于容器宽高和设置的宽高可能不同,因此实际上会保证设置的世界坐标系完全显示在白板容器上,并且宽,或者高完全撑住容器。

drawPlugin.setCameraBound(bound: {
    centerX: number,
    centerY: number,
    width: number,
    height: number
}, animate: boolean)

zoomIn

以当前白板视角中心为瞄点缩放

drawPlugin.zoomIn()

zoomOut

以当前白板视角中心为瞄点缩放

drawPlugin.zoomOut()

zoomTo

以当前白板视角中心为瞄点缩放。可以指定最终的缩放大小

drawPlugin.zoomTo(scale: number, animate: boolean)

undo

撤销。若drawPlugin.getUndoCount()为0,则无法撤销

drawPlugin.undo()

redo

重做。若drawPlugin.getRedoCount()为0,则无法重做

drawPlugin.redo()

clear

清空画布。若drawPlugin.isClearAvailable()false,则无法清空

drawPlugin.clear()

duplicate

复制选中的元素。若drawPlugin.getSelectedIds()返回空数组,则无法复制

drawPlugin.duplicate()

addPage

添加页面。默认添加在当前文档的最后一页。若insertAfter为K,则新添加文档位于第K份文档之后

drawPlugin.addPage(insertAfter?: number)

gotoPage

跳转到指定页面

drawPlugin.gotoPage(index: number)

gotoFirstPage

跳转至第一页

drawPlugin.gotoFirstPage()

gotoPrevPage

跳转至上一页

drawPlugin.gotoPrevPage()

gotoNextPage

跳转至下一页

drawPlugin.gotoNextPage()

gotoLastPage

跳转至最后一页

drawPlugin.gotoLastPage()

deletePage

删除指定页面

drawPlugin.deletePage(index: number)

gotoBoard

跳转至指定文档。

drawPlugin.gotoBoard(boardName: string)

deleteBoard

删除指定文档

drawPlugin.deleteBoard(boardName: string)

setSelfAsBroadcaster

设置当前用户为主播。其他用户将与当前用户保持视角同步。

drawPlugin.setSelfAsBroadcaster()

unsetSelfAsBroadcaster

停止视角同步

drawPlugin.unsetSelfAsBroadcaster()

setSelfAsFollower

当页面中存在主播时,可以在自由观看和跟随模式中切换。若处于自由模式,可以调用setSelfAsFollower切换回跟随模式

drawPlugin.setSelfAsFollower()

setSelfAsFreeObserver

当页面中存在主播时,可以在自由观看和跟随模式中切换。若处于跟随模式,可以调用setSelfAsFreeObserver切换回自由模式

drawPlugin.setSelfAsFreeObserver()

exportAsImage

导出当前白板页面内容为图片。实际会生成一个临时的<a>,并调用

drawPlugin.exportAsImage()

events

通过events监听drawPlugin内部状态变化。

appState

监听应用内部状态变化。这些状态都可以通过上面的接口函数拿到。也可以通过下面的方式监听状态的变化, 然后实时作出处理。

drawPlugin.on('event:appState:change', handler: (stateName: string, value1: any, value2?: any) => {
    //处理函数
})

stateName包括:renderColor, renderWidth, zoomFactor, vision, currTool, board, page, clearAvailable, redoCount, undoCount, selectChange, preview

ToolCollection

通过SDK集成时,需要开发者初始化ToolCollection。通过webview集成时,会自动初始化ToolCollection。若用户需要自定义工具栏,也可以不初始化ToolCollection

ToolCollection.getInstance

返回工具栏实例。用户可在此配置工具栏中包含哪些功能,每个功能对应的图标,以及每个功能在工具栏中的位置

ToolCollection.getInstance({
    container: HTMLDivElement,  //工具栏绑定的容器,应该和白板为同一个
    handler: drawPlugin,
    options: {
        platform: IPlatform,        //web,ios,android,pc,mac,pad。  web,pc,mac共享一套默认的工具栏,android,ios, pac共享另一套
        containerOptions: Array<{
            position: 'leftBottom'| 'left'| 'leftTop'| 'topLeft'| 'top'| 'topRight'| 'rightTop'| 'right'| 'rightBottom'| 'bottomRight'| 'bottom'| 'bottomLeft'
            marginLeft?: number
            marginRight?: number
            marginTop?: number
            marginBottom?: number
            hidden?: boolean
            items: Array<IUnitOption>
        }>  //工具栏配置
    }
})

下面详细解释下containerOptions配置。工具栏可以看成由多个容器组成,每个容器内有若干个子功能按钮,以云信互动白板demo为例,他的容器和按钮的结构关系为:

- container1:
    - position: 'left'
    - items: 
        - select
        - pen
        - shape
        - element-eraser
- container2:
    - position: 'bottomLeft'
    - items:
        - fitToContent
        - fitToDoc
        - zoomIn
        - zoomFactor
        - zoomOut

容器的位置可以由position属性配置。若positionleft,则该工具栏容器位于白板的左侧。leftToptopLeft的区别在于leftTop是左侧靠上的垂直容器,topLeft为上侧靠左的水平容器。其他位置的含义也可以此类推。

容器内子组件通过items设置。每个items有如下公共属性:

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

下面逐个介绍目前支持的工具子组件

select

选择按钮。点击后教具切换为选择

pen

点击后切换为涂鸦。具体又包含涂鸦,箭头涂鸦,线段,箭头线段四个子功能。后续将开放插件形式,允许客户插入自定义的涂鸦方式

shape

点击后切换为图形。具体包含矩形,椭圆形。后续将开放插件形式,允许客户插入自定义的图形

text

点击后切换教具为文本

laser

点击后切换教具为激光笔

element-eraser

点击后切换教具为元素擦除工具

duplicate

点击复制选中元素。不可用时会置灰

clear

点击清空当前白板页。不可用时会置灰

undo

点击撤销。不可用时会置灰

redo

点击重做。不可用时会置灰

pan

点击切换教具为拖动

image

点击弹出图片选择弹窗。客户端需要做适配才能支持此功能

exportImage

点击导出图片。客户端需要适配才能支持此功能

zoomIn

点击缩放

zoomOut

点击缩放

zoomLevel

显示当前缩放比例。点击会缩放至100%。再次点击会回到之前的百分比

visionControl

点击切换为主播。再次点击取消视角同步

visionLock

点击在跟随模式和自由模式之间切换

fitToContent

点击适配内容

fitToDoc

点击适配文档

firstPage

点击跳转至第一页。不可用时会置灰

prevPage

点击跳转至上一页。不可用时会置灰

nextPage

点击跳转至下一页。不可用时会置灰

lastPage

点击跳转至最后一页。不可用时会置灰

pageInfo

展示当前页码,以及共有多少页。如: 1/10

preview

预览按钮。点击弹出当前文档的预览滑窗。

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

docSelect

文档选择下拉框

docUpload

点击弹出文档上传弹窗。目前支持ppt, pptx, word, pdf的文档转码。

pageBoardInfo

展示当前文档名字,以及当前页面名。

multiInOne

可以包含多个子组件。点击后展示包含的具体子组件。使用方式如下。其中subItemscontainerOptions.items中的组件是一样的。

{
    tool: 'multiInOne',
    hint: '更多',
    subItems: [
        {
            tool: 'element-eraser'
        },
        {
            tool: 'clear'
        },
        {
            tool: 'undo'
        },
        {
            tool: 'redo'
        },
        {
            tool: 'image'
        },
        {
            tool: 'exportImage'
        }
    ]
}

show

显示工具栏

hide

隐藏工具栏

setContainerOptions

重新设置工具栏。参数和ToolCollection.getInstance中的options.containerOptions一样

toolCollection.setContainerOptions(containerOptions)

setVisibility

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

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

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

桌面端默认工具栏配置

[
    {
        position: 'left',
        items: [
            {
                tool: 'select',
                hint: '选择'
            },
            {
                tool: 'pen',
                hint: '画笔',
                stack: 'vertical'
            },
            {
                tool: 'shape',
                hint: '图形',
                stack: 'vertical'
            },
            {
                tool: 'text',
                hint: '文本'
            },
            {
                tool: 'laser',
                hint: '激光笔'
            },
            {
                tool: 'element-eraser',
                hint: '橡皮擦'
            },
            {
                tool: 'duplicate',
                hint: '复制'
            },
            {
                tool: 'clear',
                hint: '清空'
            },
            {
                tool: 'undo',
                hint: '撤销'
            },
            {
                tool: 'redo',
                hint: '重做'
            },
            {
                tool: 'pan',
                hint: '整体平移'
            },
            {
                tool: 'image',
                hint: '图片上传'
            },
            {
                tool: 'exportImage',
                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'
            },
            {
                tool: 'docUpload',
                hint: '文档上传'
            }
        ]
    }
]

移动端默认配置

[
    {
        position: 'bottomRight',
        items: [
            {
                tool: 'select',
                hint: '选择'
            },
            {
                tool: 'pen',
                hint: '画笔',
                stack: 'horizontal'
            },
            {
                tool: 'shape',
                hint: '图形',
                stack: 'horizontal'
            },
            {
                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: 'docUpload'
                    },
                    {
                        tool: 'fitToContent'
                    },
                    {
                        tool: 'fitToDoc'
                    },
                    {
                        tool: 'pan'
                    },
                    {
                        tool: 'zoomIn'
                    },
                    {
                        tool: 'zoomOut'
                    },
                    {
                        tool: 'visionControl'
                    },
                    {
                        tool: 'visionLock'
                    }
                ]
            },
            {
                tool: 'zoomLevel'
            }
        ]
    },
    {
        position: 'topLeft',
        items: [
            {
                tool: 'pageBoardInfo'
            },
            {
                tool: 'preview',
                hint: '预览',
                previewSliderPosition: 'right' 
            }
        ]
    }
]

RecordPlayer

RecordPlayer.getInstance

录像实例初始化。SDK会解析url,并根据url获取录像的时间戳。如果需要和其他录像对齐,可以传入timestamp调整时间戳。

RecordPlayer.getInstance(opt: {
    whiteboardParams: {
        urlArr: Array<string>,
        timestamp?: number,
        container: HTMLDivElement
    }
    videoParams?: Array<{
        url: string,
        timestamp?: number,
        container: HTMLDivElement
    }>
    version?: '1.0' | '2.0' | '3.0'   //默认为3.0. 若录像文件来自于老版本,需要指定版本号
})
.then({
  player: RecordPlayer, 
  params: {
    beginTimeStamp: number,
    endTimeStamp: number,
    duration: number,
    /**
     * 本次白板会话的参与者列表
     */
    viewerArr: string[]
  }
} => {

})
.catch(err => {

})

bindControlContainer

加载播放控制条。

player.bindControlContainer(document.getElementById('xxx'))

setPlaySpeed

设置播放倍速。速度限制为大于0.1,小于100

player.setPlaySpeed(speed: number)

setViewer

设置以谁的视角来观看录像。默认视角为录像文件中第一个动作的发出者。RecordPlayer.getInstancethen回调中,会返回这次会话的所有参与者列表。开发者可以根据此信息渲染可以选择的视角列表

player.setViewer(viewer: string)

play

播放录像

player.play()

pause

暂停播放

player.pause()

seekTo

跳转至给定时间。参数为相对于录像起始时间的偏移量

player.seekTo(time: number)

destroy

停止播放,并销毁录像实例

player.destroy()

events

visibleChange

当录像开始播放,或者停止播放时,会抛出visibleChange事件,开发者可以根据此事件设置容器的可见性。

    player.on('visibleChange', (type: 'show' | 'hide', option: any) => {
      if (option.type === 'mp4' && type === 'show') {
        option.container.style.display = 'block'
      } else if (option.type === 'mp4' && type === 'hide') {
        option.container.style.display = 'none'
      }
    })

play

回放开始播放时触发

pause

回放暂停时触发

finished

回放播放结束

tick

回放内部时钟更新时触发。开发者可以监听此事件,使得内外部应用的状态根据时间对齐

×

反馈成功

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