互动白板

  • 互动白板 > API 文档 > Web

    Web

    最近更新时间: 2022-11-02 16:27:17

    创建实例对象

    const client = QNWhiteBoard.create();
    const instance = client.controller.createInstance(bucketId);
    

    API 概览

    房间关键方法

    以下方法均为 client.controller 暴露的方法

    方法名称 方法描述
    initConfig 初始化打开白板的参数
    join_room 进入房间
    leave_room 离开房间
    registerRoomEvent 注册房间事件回调
    createInstance 创建白板实例
    getRecord 获取回放数据并初始化回放模块
    offlineConfig 配置房间内断网离线支持
    enterOffline 进入离线模式
    exitOffline 退出离线模式

    房间内主动控制的方法

    以下方法均为 client.controller 暴露的方法,无返回值

    参数 描述
    rubber_undo 还原笔迹
    clear_recovery 清空笔迹回收站
    set_pen_style 设置白板输入模式样式
    set_input_mode 设置白板输入模式
    set_erase_size 设置橡皮参数
    set_geometry_mode 设置图形模式
    set_whiteboard_back 设置白板的背景色
    get_documents 获取当前白板页列表
    new_document 新建白板页
    cut_document 切换白板页
    insert_document 插入白板页
    delete_document 删除白板页
    clean_document 清空白板页
    upload_file 白板内上传文件
    delete_widget 删除白板内选择的文件
    preUpload 预上传文件
    loadPreUploadFile 加载预上传的文件

    房间相关方法详细描述

    • 以下方法都通过 client.controller 调用

    initConfig

    初始化打开白板所需的参数,params 包含以下属性

    client.controller.initConfig(params)
    
    参数 类型 描述
    path string 白板 iframe 的 src
    el string
    HTMLElement
    承载白板 iframe 的容器,传 DOM 元素 id 或元素本身,默认传递’iframeBox’
    playbackUrl string 回放模块请求地址

    join_room

    加入房间,参数均从服务端获取

    client.controller.join_room(appId, meetingId, userId, token)
    
    参数 类型 描述
    appId string 应用的 ID
    meetingId string 房间 ID
    userId string 用户 ID
    token string 认证信息

    leave_room

    离开房间

    client.controller.leave_room()
    

    registerRoomEvent

    注册事件回调

    client.controller.registerRoomEvent({
    	onJoinSuccess: (userlist) => console.log('onJoinSuccess', userlist),
    	onJoinFailed: () => console.log('onJoinFailed'),
    	onRoomStatusChanged: (code) => console.log('onRoomStatusChanged', code),
    	onUserJoin: (user) => console.log('onUserJoin', user),
    	onUserLeave: (user) => console.log('onUserLeave', user),
    	onDocumentListChanged: (documentList) =>
    		console.log('onDocumentListChanged', documentList),
    	onDocumentPageChanged: (documentId) =>
    		console.log('onDocumentPageChanged', documentId),
    	onEnterOffline: () => console.log('onEnterOffline'),
    	onWidgetActivity: (widget) => console.log('onWidgetActivity', widget),
    	webAssemblyOnReady: () => console.log('webAssemblyOnReady'),
    })
    
    事件名称 事件描述
    onJoinSuccess 加入房间成功
    onJoinFailed 加入房间失败
    onRoomStatusChanged 房间连接状态改变
    onUserJoin 有人加入房间
    onUserLeave 有人离开房间
    onDocumentListChanged 白板页列表发生了变化
    onDocumentPageChanged 白板页翻页
    onEnterOffline offlineConfig 设置 supportOffline 为 true 后,重连超时自动进入离线模式
    onWidgetActivity 点击白板时触发,返回被点击的资源信息

    其中 onRoomStatusChanged 回调为房间状态改变时触发,参数 code 对应以下状态

    状态码 描述
    0 未连接房间
    1 正在连接房间
    2 已链接房间
    3 连接失败

    其中 onJoinSuccess 参数 userlist 为房间内当前人员列表,列表内人员属性参考 onUserJoin 和 onUserLeave

    其中 onUserJoin 和 onUserLeave 回调为房间内有人加入或离开时触发,参数 user 为该人员的信息

    属性 描述
    headPic 用户头像 url
    nickName 用户昵称
    sessionId sessionId
    userId userId

    其中 onDocumentListChanged 回调为加入房间时以及白板页数量变动时触发,参数 documentList 为该房间内白板页列表,列表项包含属性如下

    属性 描述
    bgColor 白板页背景色
    documentId 白板页 Id
    documentNo 白板序列号

    其中 onDocumentPageChanged 回调为加入房间时以及白板翻页时触发,参数 documentId 为当前白板页 Id

    其中 onWidgetActivity 回调点击白板时触发,参数 widget 为被点击的资源,包含以下参数

    属性 描述
    isDelete 是否被删除
    md5 资源加密 md5 值
    name 上传时的资源名称
    objectName 服务器保存的资源名
    pageCount 资源总页数
    pageNo 资源当前页
    path 加密路径
    resourceId 资源 id
    type 类型 0 白板 1 文档 2 图片
    userId 上传用户的 userId
    widgetId 控件 id,删除文件等操作时使用

    其中 webAssemblyOnReady 回调为白板 wasm 资源准备就绪时触发

    createInstance

    创建一个白板实例,重复调用只返回当前白板实例

    client.controller.createInstance()
    

    getRecord

    获取回放数据并初始化回放模块,必须在房间关闭的状态下调用

    client.controller.getRecord(recordId)
    

    offlineConfig

    用于配置房间中发生断网后的离线支持,必须在加入房间前调用,否则只会在下次加入房间生效

    client.controller.offlineConfig(params)
    
    参数 类型 描述
    supportOffline boolean 是否支持离线状态。默认为 false。如果设为 true,则房间模式中如果发生网络中断并在自动重连超出指定次数后进入到房间离线状态。离线状态时房间状态处于 OFFLINE。此时可以继续使用白板的基础功能,但是不能插入文件。
    onlineAutoSync boolean 当房间从离线状态恢复到在线状态后是否自动同步离线状态时的操作记录到服务器。默认为 false。

    enterOffline

    进入离线模式。离线模式与房间模式和回放模式互斥,如过已经打开了房间或开始了回放,必须首先退出房间或关闭回放后才能进入离线模式

    client.controller.enterOffline()
    

    exitOffline

    退出离线模式

    client.controller.exitOffline()
    

    delete_widget

    删除白板内选择的文件(仅普通房间模式可用)

    client.controller.delete_widget(widgetId)
    
    参数 类型 描述
    widgetId string 选择的文件 widgetId,默认点击文件时会存储,可以不传

    preUpload

    预上传文件

    client.controller.preUpload(file, meetingId): Promise
    
    参数 类型 描述
    file File 需要上传的文件
    meetingId string 房间 Id

    loadPreUploadFile

    加载预上传的文件,参数除 top,left,width,height 外均从 preUpload 获取

    client.controller.loadPreUploadFile(params: Object): Promise
    
    参数 类型 描述
    fileGroupId string 文件组 ID
    resourceId string 资源 ID
    fileName string 文件名称
    objectName string 文件对象名称
    md5 string 文件 MD5
    fileSize number 文件大小
    fileType number 文件类型
    extension string 文件扩展名
    top number 文件渲染位置(左上角为原点)
    left number 文件渲染位置(左上角为原点)
    width number 文件渲染宽
    height number 文件渲染高

    rubber_undo

    还原笔迹

    client.controller.rubber_undo()
    

    clear_recovery

    清空笔迹回收站

    client.controller.clear_recovery()
    

    set_pen_style

    设置白板输入模式样式,set_input_mode 设置为 0 时有效

    client.controller.set_pen_style({type, color, size})
    
    参数 类型 描述
    type number 铅笔0
    马克笔1
    点2
    手3
    空心箭头4
    实心箭头5
    color string 16 进制颜色(只在 0 和 1 类型下生效,都不能为空)
    size number 尺寸(只在 0 和 1 类型下生效,都不能为空)

    set_input_mode

    设置白板输入模式

    client.controller.set_input_mode(mode)
    
    参数 类型 描述
    mode number 普通模式0
    橡皮模式1
    选择模式2
    图形模式3
    文字模式4

    set_erase_size

    设置橡皮参数

    client.controller.set_erase_size(size)
    
    参数 类型 描述
    size number 橡皮大小

    set_geometry_mode

    设置图形模式

    client.controller.set_geometry_mode(mode)
    
    参数 类型 描述
    mode number 矩形 0
    圆 1
    线条 3
    箭头 6

    set_whiteboard_back

    设置白板的背景色(仅普通房间模式可用)

    client.controller.set_whiteboard_back(theme)
    
    参数 类型 描述
    theme string 16 进制颜色

    get_documents

    获取当前白板页列表

    client.controller.get_documents()
    

    new_document

    新建白板页(仅普通房间模式可用)

    client.controller.new_document()
    

    cut_document

    切换白板页(仅普通房间模式可用)

    client.controller.cut_document(documentId)
    
    参数 类型 描述
    documentId string 白板页 ID

    insert_document

    插入白板页(仅普通房间模式可用)

    client.controller.insert_document(documentId)
    
    参数 类型 描述
    documentId string 白板页 ID

    delete_document

    删除白板页(仅普通房间模式可用)

    client.controller.delete_document(documentId)
    
    参数 类型 描述
    documentId string 白板页 ID

    clean_document

    清空白板页,pdf 模式下不用传 documentId

    client.controller.clean_document(documentId)
    
    参数 类型 描述
    documentId string 白板页 ID

    upload_file

    白板内上传文件,位置和大小相对 onWhiteBoardOpened 回调参数 size 的宽高

    client.controller.upload_file({file, left, top, width, height})
    
    参数 类型 描述
    file File 要上传的文件
    left number 文件在白板内距离左侧的距离
    top number 文件在白板内距离上方的距离
    width number 白板内显示文件的宽
    height number 白板内显示文件的高

    白板实例的方法

    实例由createInstance方法创建并返回

    const instance = client.controller.createInstance(bucketId, el)
    
    • 以下方法都通过实例调用
    方法名称 方法描述
    switchBucket 切换白板
    registerWhiteBoardEvent 注册白板事件回调
    registerPPTEvent 注册 PPT 事件回调
    registerPDFEvent 注册 PDF 事件回调
    sendMessage 发送用户自定义消息
    registerPlaybackEvent 注册回放事件回调

    白板实例中主动控制的方法

    参数 描述
    nextStep ppt 下一步
    preStep ppt 上一步
    jumpStep ppt 跳到指定步
    nextPage ppt / pdf 下一页
    prePage ppt / pdf 上一页
    jumpPage ppt / pdf 跳到指定页
    getFileState 获取当前文件状态
    getBucketId 获取白板 bucketId
    getBoardMode 获取白板模式
    setPDFOperationMode 设置 pdf 操作模式
    play 播放回放
    stop 停止回放
    pause 暂停回放
    seek 跳转回放
    calibrate 校准回放
    release 关闭回放
    getPosition 获取当前回放进度
    getDuration 获取回放总时长
    getStatus 获取当前回放状态
    getRecordId 获取当前回放 id
    getWhiteBoardSize 获取当前回放白板虚拟尺寸
    resize 设置白板大小

    白板相关方法详情

    switchBucket

    切换白板

    instance.switchBucket(bucketId)
    
    参数 描述
    bucketId 新白板的 bucketId

    registerWhiteBoardEvent

    注册白板事件回调

    instance.registerWhiteBoardEvent({
    	onWhiteBoardOpened: (size) => console.log('onWhiteBoardOpened', size),
    	onWhiteBoardOpenFailed: () => console.log('onWhiteBoardOpenFailed'),
    	onWhiteBoardClosed: () => console.log('onWhiteBoardClosed'),
    	onUserMessage: (content) => console.log('onUserMessage', content),
    	onFileFlipped: (fileState) => console.log('onFileFlipped', fileState),
    	onFileBeginUpload: (resourceId) =>
    		console.log('onFileBeginUpload', resourceId),
    	onFileUploaded: (resourceId) => console.log('onFileUploaded', resourceId),
    	onFileUploadFail: (resourceId) =>
    		console.log('onFileUploadFail', resourceId),
    	onFileBeginDownload: (resourceId) =>
    		console.log('onFileBeginDownload', resourceId),
    	onFileDownloaded: (resourceId) =>
    		console.log('onFileDownloaded', resourceId),
    	onFileDownloadFail: (resourceId) =>
    		console.log('onFileDownloadFail', resourceId),
    	onFileRendered: (resourceId) => console.log('onFileRendered', resourceId),
    	onFileRenderFail: (resourceId) =>
    		console.log('onFileRenderFail', resourceId),
    })
    
    事件名称 事件描述
    onWhiteBoardOpened 打开白板成功
    onWhiteBoardOpenFailed 打开白板失败
    onWhiteBoardClosed 关闭白板成功
    onUserMessage 接收用户自定义消息
    onFileFlipped 白板文件翻页
    onFileBeginUpload 白板文件开始上传
    onFileUploaded 白板文件上传成功
    onFileUploadFail 白板文件上传失败
    onFileBeginDownload 白板文件开始下载
    onFileDownloaded 白板文件下载成功
    onFileDownloadFail 白板文件下载失败
    onFileRendered 白板文件渲染成功
    onFileRenderFail 白板文件渲染失败

    onWhiteBoardOpened 回调为白板打开成功时触发,参数 size 为白板的虚拟宽高,无单位

    属性 类型 描述
    width number 白板的虚拟宽度
    height number 白板的虚拟高度

    onUserMessage 回调为调用 sendMessag e后,其他用户会触发的回调,参数 content

    属性 类型 描述
    content object 用户发送的自定义消息内容

    onFileFlipped 回调在白板内文件下载完成时以及文件翻页时触发,参数 fileState

    属性 类型 描述
    pageCount number 文化总页数
    pageNo number 文件当前页
    resourceId number 文件的 resourceId
    widgetId string 文件的 widgetId

    onFileBeginUpload; onFileUploaded; onFileUploadFail; onFileBeginDownload; onFileDownloaded; onFileDownloadFail; onFileRendered onFileRenderFail 回调参数

    属性 类型 描述
    resourceId string 文件的 resourceId

    registerPPTEvent

    注册 ppt 事件回调,以下回调只有在 ppt-play 模式才会触发

    instance.registerPPTEvent({
    	onFileLoadedSuccessful: () => console.log('onFileLoadedSuccessful'),
    	onFileLoadingFailed: (code) => console.log('onFileLoadingFailed', code),
    	onFileStateChanged: (data) => console.log('onFileStateChanged', data),
    })
    
    事件名称 事件描述
    onFileLoadedSuccessful ppt 加载成功
    onFileLoadingFailed ppt 加载失败
    onFileStateChanged ppt 文件状态改变

    其中 onFileStateChanged 回调为 ppt 翻页等操作时触发,参数 data 内包含以下参数

    名称 类型 描述
    no number 当前 ppt 页号
    step number 当前 ppt 动画位置索引
    pageCount number ppt 总页数
    stepCount number ppt 总动画数

    其中 onFileLoadingFailed 回调为 ppt 文档打开失败时触发,参数 code 对应以下描述

    错误码 描述
    501 幻灯片下载失败
    502 脚本下载失败

    registerPDFEvent

    注册 pdf 事件回调,以下回调只有在 pdf-play 模式才会触发

    instance.registerPDFEvent({
    	onFileLoadedSuccessful: () => console.log('onFileLoadedSuccessful'),
    	onFileLoadingFailed: (code) => console.log('onFileLoadingFailed', code),
    	onFileStateChanged: (data) => console.log('onFileStateChanged', data),
    })
    
    事件名称 事件描述
    onFileLoadedSuccessful pdf 加载成功
    onFileLoadingFailed pdf 加载失败
    onFileStateChanged pdf 文件状态改变

    其中 onFileStateChanged 回调为 pdf 翻页操作时触发,参数 data 内包含以下参数

    名称 类型 描述
    currentPage number 当前 pdf 页号
    pageCount number pdf 总页数

    其中 onFileLoadingFailed 回调为 pdf 文档打开失败时触发,参数 code 对应以下描述

    错误码 描述
    501 加载失败
    502 文件无效
    503 文件丢失
    504 意外的错误

    sendMessage

    发送用户自定义消息

    instance.sendMessage(command, content)
    
    参数 类型 描述
    command string 指令名,主动调用时固定填写 custom
    content Json 消息内容,必须 json 格式

    registerPlaybackEvent

    注册回放事件回调

    instance.registerPlaybackEvent({
    	onInitFinished: (totalTime) => console.log('onInitFinished', totalTime),
    	onError: (code) => console.log('onError', code),
    	onStatusChanged: (status) => console.log('onStatusChanged', status),
    	onProgress: (data) => console.log('onProgress', data),
    	onBoardSizeChanged: (size) => console.log('onBoardSizeChanged', size),
    	onFileLoadingFailed: (error) => console.log(error),
    })
    

    onInitFinished 回放模式初始化完成回调

    参数 类型 描述
    totalTime number 回放总时长,毫秒

    onError 回放模式错误回调,code 对应以下描述

    错误码 描述
    100 网络不可用
    101 服务器错误或繁忙
    500 未关闭房间,不可初始化回放
    501 下载回放记录文件失败
    502 回放记录不存在
    503 录制未结束

    onStatusChanged 回放状态改变回调 status 为当前状态

    参数 类型 描述
    status string IDLE空闲状态
    LOADING正在初始化数据
    PREPARED 已就绪
    PLAYING播放中
    PAUSED已暂停
    STOPPED已停止
    ERROR 错误
    DESTROYED对象已销毁

    onProgress 回放进度通知回调,播放中 200 毫秒触发一次,data 包含参数如下

    参数 类型 描述
    position number 当前进度,毫秒
    duration number 回放总时长,毫秒

    onBoardSizeChanged 白板尺寸改变回调,size 包含参数如下

    参数 类型 描述
    width number 白板虚拟宽
    height number 白板虚拟高

    onFileLoadingFailed 回放中的文件加载失败回调, error 包含参数如下

    参数 类型 描述
    bucketId string 白板 id
    mode string 白板类型 ppt_play pdf_scroll 两者之一
    extra string 文件对应的描述信息
    errorCode number 文件加载失败的错误码

    nextStep

    ppt 下一步,当该页没有动画或者当前已经是该页最后一步动画时调用,ppt 会翻到下一页

    instance.nextStep()
    

    preStep

    ppt 上一步,如果当前页动画全部未执行时调用翻到上一页,否则状态变更为当前页未执行动画的状态

    instance.preStep()
    

    jumpStep

    ppt 跳到指定步

    instance.jumpStep(step)
    
    参数 类型 描述
    step number ppt 目标步

    nextPage

    ppt / pdf 下一页

    instance.nextPage()
    

    prePage

    ppt / pdf 上一页

    instance.prePage()
    

    jumpPage

    跳到指定页

    instance.jumpPage(page)
    
    参数 类型 描述
    page int 目标页,当前页与目标页之间的页码不存在时会补齐其间的页

    getFileState

    获取当前文件状态,返回值参考下方 ppt/pdf 事件回调 onFileStateChanged 参数

    instance.getFileState()
    

    getBucketId

    获取白板 bucketId

    instance.getBucketId()
    

    getBoardMode

    获取白板模式

    instance.getBoardMode()
    

    setPDFOperationMode

    设置 pdf 操作模式

    instance.setPDFOperationMode(boolean)
    
    参数 类型 描述
    boolean boolean true 开启 pdf 操作模式, false 关闭。
    pdf 操作模式下:
    pc:↑↓ 箭头和滚轮 控制上下滚动,ctrl+滚轮控制缩放
    h5:双指缩放,单指滑动滚动

    play

    播放回放

    instance.play()
    

    stop

    停止回放

    instance.stop()
    

    pause

    暂停回放

    instance.pause()
    

    seek

    跳转回放

    instance.pause(position)
    
    参数 类型 描述
    position number 跳转回放的目标位置时间,[0,总时长] 区间,毫秒

    calibrate

    校准回放

    instance.calibrate(offset)
    
    参数 类型 描述
    offset number 校准的时间长度,[-5000,5000] 区间,毫秒

    release

    关闭回放

    instance.release()
    

    getPosition

    获取当前回放进度,毫秒

    instance.getPosition()
    

    getDuration

    获取回放总时长,毫秒

    instance.getDuration()
    

    getStatus

    获取当前回放状态,值参考 registerPlaybackEvent 中 onStatusChanged 回调参数

    instance.getStatus()
    

    getRecordId

    获取当前回放 id

    instance.getRecordId()
    

    getWhiteBoardSize

    获取当前回放白板虚拟尺寸,值参考 registerPlaybackEvent 中 onBoardSizeChanged 回调参数

    instance.getWhiteBoardSize()
    

    resize

    设置白板 canvas 元素的 width 和 height 属性,参数 number 类型无单位

    instance.resize(width, height)
    
    以上内容是否对您有帮助?
  • Qvm free helper
    Close