DrawPlugin | 互动白板 v3.8.5

绘制模块

Hierarchy

DrawPlugin

Index

Methods

addBoard

addBoard(docName: string, pageCount: number): string

添加多页空白文档
example
```
const boardName = drawPlugin.addBoard('力学', 2)
```
Parameters
- docName: string
  
  文档显示名称
- pageCount: number
  
  文档页数
Returns string

返回文档的boardName

addDoc

addDoc(opt: { docName: string; params: IStaticDocParam | IStaticDocParamDeprecated[] }): string

添加静态文档。静态文档由多页图片组成。用户既可以传入多页静态图片作为参数，也可以传入云信静态文档转码结果作为参数

example

3.6.1以后（含3.6.1）使用template添加文档

addDoc({
 docName: '力学',
 params: {
     template: "https://nim.nosdn.127.net/408e9c59-cdc2-4979-b3e2-85d02d4f7ea3_1_{index}.jpg",
     width: 1920,
     height: 1080,
     offset: 1,
     pageCount: 2
 }
})

example

3.6.0之前（含）addDoc时，opt.params应该为数组。如果高版本白板sdk需要和3.6.0及之前的版本互通，需要opt.params为数组才能够互通

addDoc({
 docName: '力学',
 params: [
     {
         url: "https://nim.nosdn.127.net/408e9c59-cdc2-4979-b3e2-85d02d4f7ea3_1_1.jpg",
         width: 1920,
         height: 1080,
     },
     {
         url: "https://nim.nosdn.127.net/408e9c59-cdc2-4979-b3e2-85d02d4f7ea3_1_2.jpg",
         width: 1920,
         height: 1080
     }
])

Parameters

opt: { docName: string; params: IStaticDocParam | IStaticDocParamDeprecated[] }
- docName: string
  
  文档的显示名
- params: IStaticDocParam | IStaticDocParamDeprecated[]
  
  静态文档的参数

Returns string

返回文档的boardName

addImage

addImage(opt: { boardName?: string; height: number; pageIndex?: number; url: string; width: number }): void

添加图片至白板中

Parameters
- opt: { boardName?: string; height: number; pageIndex?: number; url: string; width: number }
  - Optional boardName?: string
    
    如果没有给boardName, 则默认添加图片至当前文档
  - height: number
    
    图片高度
  - Optional pageIndex?: number
    
    如果没有设置pageIndex，则默认添加图片至选定文档的当前页面
  - url: string
    
    图片URL地址。注意如果site部署在https协议上，图片也必须是https地址。
    
    另注：如果图片地址跨域，如果需要导出图片的话，或者进行白板转流，则必须保证图片服务允许跨域
  - width: number
    
    图片宽度
Returns void

addPage

addPage(opt: { insertAfter?: number; payload: any }): void

添加页面。

Parameters
- opt: { insertAfter?: number; payload: any }
  - Optional insertAfter?: number
    
    若提供，则在insertAfter索引代表的页面后插入。若不提供，则插入在最后一页
  - payload: any
    
    添加页面的自定义数据。开发者可以根据自定义数据进行页面检索或其他。
Returns void

addTransDoc

addTransDoc(opt: { docName: string; height: number; pageCount: number; url: string; width: number }): string

添加动态文档。云信动态文档只支持云信转码的动态文档结果

要展示动态文档，请确保页面中载入了pptRenderer.js

Parameters
- opt: { docName: string; height: number; pageCount: number; url: string; width: number }
  - docName: string
    
    文档显示名
  - height: number
    
    ppt文档的高度
  - pageCount: number
    
    文档总页面数，一般来说，该页面数应该和ppt文档的页面总数相等
  - url: string
    
    ppt文档转码的resultUrl地址
  - width: number
    
    ppt文档的宽度
Returns string

返回文档的boardName

addVideo

addVideo(opt: { boardName?: string; pageIndex?: number; sourceType: string; title?: string; url: string; width?: number }): void

添加视频

Parameters
- opt: { boardName?: string; pageIndex?: number; sourceType: string; title?: string; url: string; width?: number }
  - Optional boardName?: string
    
    如果没有给boardName, 则默认添加图片至当前文档
  - Optional pageIndex?: number
    
    如果没有设置pageIndex，则默认添加图片至选定文档的当前页面
  - sourceType: string
    
    视频格式。会用于设置video标签中source的type属性。目前支持mp4, quicktime
  - Optional title?: string
    
    视频标题
  - url: string
    
    视频资源的url地址
  - Optional width?: number
    
    视频容器初始占的宽度
Returns void

clear

clear(): void

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

Returns void

deleteBoard

deleteBoard(boardName: string): void

删除指定文档

Parameters
- boardName: string
  
  addDoc, addTransDoc, addBoard的返回值
Returns void

deletePage

deletePage(index: number): void

删除指定页面

Parameters
- index: number
  
  目标页面索引
Returns void

duplicate

duplicate(): void

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

Returns void

enableDraw

enableDraw(enable: boolean): void

是否允许本地编辑白板

Parameters
- enable: boolean
Returns void

exportAsBase64String

exportAsBase64String(opt?: { content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; type?: "jpeg" | "png" }): null | { content: string; height: number; width: number }

参数和DrawPlugin.exportAsImage一样

返回当前页面的base64编码，及其宽高

Parameters
- Optional opt: { content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; type?: "jpeg" | "png" }
  - Optional content?: "clip" | "fitToDoc" | "fitToContent"
    
    clip导出当前页显示的内容。导出图片分辨率和容器大小一样
    
    fitToDoc导出图片和页面中文档的宽高一样
    
    fitToContent导出图片和页面中内容的最大宽高一样。如果内容较小，会设置最小宽高为容器宽高
  - Optional customBg?: boolean
    
    导出图片时，是否包含自定义背景。默认为false
  - Optional omitSelection?: boolean
    
    是否绘制选择框。默认为false，即不忽略（绘制）
  - Optional quality?: number
    
    图片精度。有效范围为(0, 1]。只有当type为'png'时有效
  - Optional type?: "jpeg" | "png"
Returns null | { content: string; height: number; width: number }

exportAsImage

exportAsImage(opt?: { content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; type?: "jpeg" | "png" }): void

导出当前白板页面内容为图片。该函数会触发浏览器的下载事件
example
默认导出当前页面白板快照的png图片
```
drawPlugin.exportAsImage()
```
example
导出当前白板页面的全部内容（包括不在视角内的内容）。格式为jpeg, 精度为0.7
```
drawPlugin.exportAsImage({
   type: 'jpeg',
   quality: 0.7,
   content: 'wholePage',
   omitSelection: true,
   customBg: true
})
```
Parameters
- Optional opt: { content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; type?: "jpeg" | "png" }
  - Optional content?: "clip" | "fitToDoc" | "fitToContent"
    
    clip导出当前页显示的内容。导出图片分辨率和容器大小一样
    
    fitToDoc导出图片和页面中文档的宽高一样
    
    fitToContent导出图片和页面中内容的最大宽高一样。如果内容较小，会设置最小宽高为容器宽高
  - Optional customBg?: boolean
    
    导出图片时，是否包含自定义背景。默认为false
  - Optional omitSelection?: boolean
    
    是否绘制选择框。默认为false，即不忽略（绘制）
  - Optional quality?: number
    
    图片精度。有效范围为(0, 1]。只有当type为'png'时有效
  - Optional type?: "jpeg" | "png"
Returns void

exportBoardAsStr

exportBoardAsStr(opt: { boardName?: string; content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; resWait?: number; type?: "jpeg" | "png" }, callbacks: { onComplete: any; onError?: any; onImgProgress?: any; onResourceProgress?: any }): void

导出board内容为base64字符串

导出过程分为:

资源下载过程。在该过程中，会触发onResourceProgress回调
生成图片过程。在该过程中，会触发onImgProgress回调
生成图片完成时，会触发onComplete回调

若生成过程中有异常，则会触发onError回调。

注意, exportBoardAsStr尚不支持在移动端调用。且该过程时间可能较长，会造成页面少许卡顿。

example

drawPlugin.exportBoardAsStr(
     {
          content: 'fitToContent'
      }, 
      {
          onResourceProgress: (number) => {
              console.log('resource下载进度', number)
          },
          onImgProgress: (number) => {
              console.log('图片生成进度', number)
          },
          onComplete: (result) => {
              console.log('图片生成完毕')
              console.log(result)
          },
          onError: (err) => {
              console.error('error', err)
          }
      }
  )

example

下面是生成PDF的示例代码

//正在生成pdf过程中时，避免重复生成pdf
let isExportPdf = false

//点击按钮开始生成pdf
async function onIconClick() {
     if (isExportPdf) {
         console.log('正在导出pdf，当前请求忽略')
         return
     }

     WhiteBoardSDK.showToast({
        type: 'info',
        msg: '正在下载pdf依赖资源，请耐心等待',
        time: 10000
     })

     try {
         isExportPdf = true
         await exportPdf()
     } catch (err) {
         console.error('export pdf error', err)
     } finally {
         isExportPdf = false
     }
     WhiteBoardSDK.hideToast()
}

async function exportPdf() {
     return new Promise((res, rej) => {
         drawPlugin.exportBoardAsStr(
         {
             content: 'fitToContent',
             //一定程度上压缩，否则可能pdf过大
             quality: 0.7,
             type: 'jpeg',
             //文档依赖的图片等资源的最大等待时间: 90s
             resWait: 90000
         }, {
             onResourceProgress: (number) => {
                 WhiteBoardSDK.showToast({
                     type: 'info',
                     msg: `正在下载资源: ${Math.ceil(number * 100)}%`,
                     time: 10000
                 })
             },
             onImgProgress: (number) => {
                 WhiteBoardSDK.showToast({
                     type: 'info',
                     msg: `正在生成pdf: ${Math.ceil(number * 100)}%`,
                     time: 10000
                 })
             },
             onComplete: (result) => {
                 console.log('on complete')
                 generatePdf(result)
                 res()
             },
             onError: (err) => {
                 rej()
             }
         }
     )
 })
}


 function generatePdf(res) {
     WhiteBoardSDK.hideToast()

     const orientation = res.maxW > res.maxH ? 'l' : 'p'

     if (res.nullPages.length > 0) {
         console.log('导出失败的页面: ', res.nullPages.join(','))
     }

     if (res.contents.length > 0) {
         //依赖于：https://www.npmjs.com/package/jspdf

         const jsPDF = new window.jspdf.jsPDF({
             orientation,
             unit: 'px',
             hotfixes: ["px_scaling"],
             compress: true,
             format: [res.maxW, res.maxH]
         })

         //第一页
         jsPDF.addImage(
             res.contents[0],
             'JPEG',
             (res.maxW - res.sizes[0].w) / 2, (res.maxH - res.sizes[0].h) / 2,
             res.sizes[0].w, res.sizes[0].h,
             '',
             'FAST'
         )

         for (let i = 1; i < res.contents.length; i++) {
             jsPDF.addPage({
                 orientation,
                 unit: 'px',
                 hotfixes: ["px_scaling"],
                 format: [res.maxW, res.maxH]
             })

             //第二页到最后一页
             jsPDF.addImage(
                 res.contents[i],
                 'JPEG',
                 (res.maxW - res.sizes[i].w) / 2,
                 (res.maxH - res.sizes[i].h) / 2,
                 res.sizes[i].w,
                 res.sizes[i].h,
                 '',
                 'FAST'
             )
         }

         jsPDF.save('whiteboard.pdf')
     }
 }

Parameters

opt: { boardName?: string; content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; resWait?: number; type?: "jpeg" | "png" }
- Optional boardName?: string
  
  board名称。若不提供，则默认为当前board
- Optional content?: "clip" | "fitToDoc" | "fitToContent"
  
  clip导出当前页显示的内容。导出图片分辨率和容器大小一样
  
  fitToDoc导出图片和页面中文档的宽高一样
  
  fitToContent导出图片和页面中内容的最大宽高一样。如果内容较小，会设置最小宽高为容器宽高
- Optional customBg?: boolean
  
  导出图片时，是否包含自定义背景。默认为false
- Optional omitSelection?: boolean
  
  是否绘制选择框。默认为false，即不忽略（绘制）
- Optional quality?: number
  
  图片精度。有效范围为(0, 1]。只有当type为'png'时有效
- Optional resWait?: number
  
  导出board为图片前，会下载board依赖的资源。resWait指资源下载最长等待时间。默认值为90s。
  
  若超过resWait还没有下载下来全部依赖的资源，则会继续下一步直接渲染
- Optional type?: "jpeg" | "png"
callbacks: { onComplete: any; onError?: any; onImgProgress?: any; onResourceProgress?: any }
- onComplete: function
  - onComplete(res: { contents: string[]; maxH: number; maxW: number; nullPages: number[]; sizes: { h: number; w: number }[] }): void
  - 调用成功时的回调函数
    
    Parameters
    - res: { contents: string[]; maxH: number; maxW: number; nullPages: number[]; sizes: { h: number; w: number }[] }
      - contents: string[]
        
        每一页渲染结果的base64值
      - maxH: number
        
        所有图片的最大高度
      - maxW: number
        
        所有图片的最大宽度
      - nullPages: number[]
        
        导出失败的图片索引
      - sizes: { h: number; w: number }[]
        
        每一页图片的尺寸
    Returns void
- onError: function
  - onError(err: any): void
  - 抛出异常时的回调函数
    
    Parameters
    - err: any
    Returns void
- onImgProgress: function
  - onImgProgress(progress: number): void
  - 生成每一页base64值的过程的回调函数
    
    Parameters
    - progress: number
    Returns void
- onResourceProgress: function
  - onResourceProgress(progress: number): void
  - 资源加载过程中回调函数。注意，动态课件的资源加载过程不会触发该回调。
    
    Parameters
    - progress: number
    Returns void

Returns void

fitToContent

fitToContent(animate: boolean): void

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

Parameters
- animate: boolean
  
  是否通过动画过渡到目标位置
Returns void

fitToDoc

fitToDoc(animate: boolean): void

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

Parameters
- animate: boolean
  
  是否通过动画过渡到目标位置
Returns void

getAnimInfos

getAnimInfos(): null | { animIndex: number; animState: "start" | "end"; pageIndex: number }

获取当前文档的动画位置。如果当前文档不是动态ppt文档，或者当前为动态ppt文档中的新插入的白板页面，则返回null

Returns null | { animIndex: number; animState: "start" | "end"; pageIndex: number }

getBgRendererName

getBgRendererName(): string

获取当前自定义背景的名字。名字来源于setCustomBackground的第三个参数

Returns string

getBoardInfos

getBoardInfos(): IBoardInfos

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

Returns IBoardInfos

getColor

getColor(): string

获取当前画笔的颜色

Returns string

getCurrTool

getCurrTool(): string

获取当前教具名称

Returns string

getPageInfos

getPageInfos(boardName?: string): IPageInfos

获取指定文档的页面结构。若参数未设置，则返回当前文档的结构。

Parameters
- Optional boardName: string
Returns IPageInfos

getRedoCount

getRedoCount(): number

获取当前可以redo的次数

Returns number

getSelectedIds

getSelectedIds(): string[]

获取当前选中元素的id列表

Returns string[]

getStream

getStream(opt?: { keepDPI?: boolean; width?: number }): MediaStream

获取白板视频流。开发者可以使用函数的返回的视频流，通过rtc，或者其他的方式推出去。注意，每次调用时，都会关闭现有的track，并返回一个新的stream
example
获取白板视频流，并使用rtc推流
```
const stream = drawPlugin.getStream()
tracks = stream.getVideoTracks()
rtc.localStream.open({
    type: 'screen',
    screenVideoSource: tracks[0]
})
```
example
指定白板视频流的宽度。高度会随根据视频流宽度 * 白板的宽高比得到
```
const stream = drawPlugin.getStream({width: 1000})
```
example
视频流的宽度随着白板容器的宽度而变化。如果屏幕dpi为2，则下面推流的分辨率为容器宽度 * 2
```
const stream = drawPlugin.getStream({keepDPI: true})
```
example
如果推流时，希望分辨率不受dpi影响，则应该设置keepDPI为fals
```
const stream = drawPlugin.getStream({keepDPI: false})
```
Parameters
- Optional opt: { keepDPI?: boolean; width?: number }
  - Optional keepDPI?: boolean
    
    默认为true
    
    如果设置了width，则该参数无效如果未设置width，参数为true时，视频流的大小为容器宽度 * DPI
  - Optional width?: number
    
    视频流宽度。高度根据容器宽高比自动计算
    
    若不指定，则视频分辨率随容器宽度变化
Returns MediaStream

getStrokeWidth

getStrokeWidth(): number

获取当前画笔的粗细

Returns number

getUndoCount

getUndoCount(): number

获取当前可以undo的次数

Returns number

getVisibleElementInfos

getVisibleElementInfos(): { id: string; type: string }[]

获取当前页面中可见元素的id和类型

Returns { id: string; type: string }[]

getVisionState

getVisionState(): { broadcaster: undefined | string; broadcasterName: undefined | string; mode: "broadcaster" | "follower" | "freeObserver" }

获取当前客户端的视角相关的信息。

Returns { broadcaster: undefined | string; broadcasterName: undefined | string; mode: "broadcaster" | "follower" | "freeObserver" }
- broadcaster: undefined | string
  
  主播uid
- broadcasterName: undefined | string
  
  主播名称。优先使用昵称(nickname), 若初始化时未设置nickname，则为主播uid
- mode: "broadcaster" | "follower" | "freeObserver"
  
  broadcaster: 当前用户为主播，其他用户跟随当前用户视角
  
  follower: 当前用户跟随主播视角
  
  freeObserver：当前用户自由视角

getZoomFactor

getZoomFactor(): number

获取当前的缩放比例。1代表未缩放，即工具栏中的100%

Returns number

gotoAnim

gotoAnim(opt: { animIndex: number; animState: "start" | "end"; pageIndex: number }): void

跳转至指定页面的指定动画位置

注意，参数pageIndex为页面在原始ppt中的索引

如果当前文档不是动态ppt文档、或者索引为'pageIndex'的页面已经被删除，则无法跳转

Parameters
- opt: { animIndex: number; animState: "start" | "end"; pageIndex: number }
  - animIndex: number
  - animState: "start" | "end"
  - pageIndex: number
    
    原始ppt中的页面索引
Returns void

gotoBoard

gotoBoard(boardName: string): void

跳转至指定文档。

Parameters
- boardName: string
  
  addDoc, addTransDoc, addBoard的返回值
Returns void

gotoFirstPage

gotoFirstPage(): void

跳转至第一页

Returns void

gotoLastPage

gotoLastPage(): void

跳转至最后一页

Returns void

gotoNextPage

gotoNextPage(): void

gotoPage

gotoPage(index: number): void

跳转到指定页面

Parameters
- index: number
  
  目标页面索引
Returns void

gotoPrevPage

gotoPrevPage(): void

hasBackground

hasBackground(): boolean

当前页面是否有背景图

Returns boolean

hasTransDoc

hasTransDoc(): boolean

当前文档中是否有动态ppt

Returns boolean

isClearAvailable

isClearAvailable(): boolean

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

Returns boolean

isTextAreaFocus

isTextAreaFocus(): boolean

判断文本输入框是否聚焦

Returns boolean

lockCameraWithContent

lockCameraWithContent(opt: { height: number; width: number }): void

该函数主要用于标注场景中，保持白板和被标注物的相对位置不变。

假设标注物为一张图片，则该函数有以下限制：
1. 标注物的固有宽高不会变化
2. 标注物容器的大小、位置和白板的大小、位置始终保持一致
3. 标注物显示出来的宽高比例和其固有宽高比例一致
4. 标注物在水平、或者垂直方向上撑满容器，在另一个方向尺寸则小于等于容器尺寸
5. 在未撑满容器的方向上，标注物应该居中放置
在以上限制条件下，调用了此函数后，白板的位置将始终和标注物位置相对不变
Parameters
- opt: { height: number; width: number }
  - height: number
    
    标注物高度
  - width: number
    
    标注物宽度
Returns void

nextAnim

nextAnim(): void

跳转至下一动画。如果当前页动画播放完毕，则跳至下一页面。工具栏中对应的工具名称为nextAnim。

该动作仅在当前文档为动态ppt文档时才可以使用

Returns void

on

on(eventName: "event:appState:change", callback: (stateName: "renderColor", color: string) => void): void
on(eventName: "event:appState:change", callback: (stateName: "renderWidth", width: number) => void): void
on(eventName: "event:appState:change", callback: (stateName: "zoomFactor", scale: number) => void): void
on(eventName: "event:appState:change", callback: (stateName: "currTool", tool: string) => void): void
on(eventName: "event:appState:change", callback: (stateName: "clearAvailable", available: boolean) => void): void
on(eventName: "event:appState:change", callback: (stateName: "redoCount", count: number) => void): void
on(eventName: "event:appState:change", callback: (stateName: "undoCount", count: number) => void): void
on(eventName: "event:appState:change", callback: (stateName: "selectChange", oldSelectedOpIds: string[], currSelectedOpIds: string[], nonMediaSelectedOpIds: string[]) => void): void
on(eventName: "event:appState:change", callback: (stateName: "board", infos: IBoardInfos) => void): void
on(eventName: "event:appState:change", callback: (stateName: "page", infos: IPageInfos) => void): void
on(eventName: "event:appState:change", callback: (stateName: "vision", infos: { broadcaster: undefined | string; broadcasterName: undefined | string; mode: "broadcaster" | "follower" | "freeObserver" }) => void): void

注册回调监听颜色变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'renderColor') {
     console.log('color change to', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "renderColor", color: string) => void
  - - (stateName: "renderColor", color: string): void
    - Parameters
      - stateName: "renderColor"
      - color: string
      Returns void
Returns void
注册回调监听画笔粗细变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'renderWidth') {
     console.log('width change to', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "renderWidth", width: number) => void
  - - (stateName: "renderWidth", width: number): void
    - Parameters
      - stateName: "renderWidth"
      - width: number
      Returns void
Returns void
注册回调监听画笔缩放变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'zoomFactor') {
     console.log('scale change to', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "zoomFactor", scale: number) => void
  - - (stateName: "zoomFactor", scale: number): void
    - Parameters
      - stateName: "zoomFactor"
      - scale: number
      Returns void
Returns void
注册回调监听教具变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'currTool') {
     console.log('currTool change to', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "currTool", tool: string) => void
  - - (stateName: "currTool", tool: string): void
    - Parameters
      - stateName: "currTool"
      - tool: string
      Returns void
Returns void
注册回调监听是否可以清空的状态变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'clearAvailable') {
     console.log('is clearAvailable', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "clearAvailable", available: boolean) => void
  - - (stateName: "clearAvailable", available: boolean): void
    - Parameters
      - stateName: "clearAvailable"
      - available: boolean
      Returns void
Returns void
注册回调监听redo可用次数变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'redoCount') {
     console.log('redoCount', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "redoCount", count: number) => void
  - - (stateName: "redoCount", count: number): void
    - Parameters
      - stateName: "redoCount"
      - count: number
      Returns void
Returns void
注册回调监听undo可用次数变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'undoCount') {
     console.log('undoCount', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "undoCount", count: number) => void
  - - (stateName: "undoCount", count: number): void
    - Parameters
      - stateName: "undoCount"
      - count: number
      Returns void
Returns void
注册回调监听选中元素的变化
example
```
drawPlugin.on('event:appState:change', (stateName, oldSelectedOpIds, currSelectedOpIds, nonMediaSelectedOpIds) => {
 if (stateName === 'selectChange') {
     console.log('过去选中元素', oldSelectedOpIds)
     console.log('将要选中元素', currSelectedOpIds)
     console.log('将要选中的非音视频元素', nonMediaSelectedOpIds)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "selectChange", oldSelectedOpIds: string[], currSelectedOpIds: string[], nonMediaSelectedOpIds: string[]) => void
  - - (stateName: "selectChange", oldSelectedOpIds: string[], currSelectedOpIds: string[], nonMediaSelectedOpIds: string[]): void
    - Parameters
      - stateName: "selectChange"
      - oldSelectedOpIds: string[]
      - currSelectedOpIds: string[]
      - nonMediaSelectedOpIds: string[]
      Returns void
Returns void
注册回调监听文档新增，删除，切换
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'board') {
     console.log('board infos', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "board", infos: IBoardInfos) => void
  - - (stateName: "board", infos: IBoardInfos): void
    - Parameters
      - stateName: "board"
      - infos: IBoardInfos
      Returns void
Returns void
注册回调监听页面新增，删除，切换
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'page') {
     console.log('page infos', value)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "page", infos: IPageInfos) => void
  - - (stateName: "page", infos: IPageInfos): void
    - Parameters
      - stateName: "page"
      - infos: IPageInfos
      Returns void
Returns void
注册回调监听视角状态的变化
example
```
drawPlugin.on('event:appState:change', (stateName, value) => {
 if (stateName === 'vision') {
     console.log('当前视角模式', value.mode)
     console.log('是否存在用户在广播', value.broadcaster !== undefined)
 }
})
```
Parameters
- eventName: "event:appState:change"
- callback: (stateName: "vision", infos: { broadcaster: undefined | string; broadcasterName: undefined | string; mode: "broadcaster" | "follower" | "freeObserver" }) => void
  - - (stateName: "vision", infos: { broadcaster: undefined | string; broadcasterName: undefined | string; mode: "broadcaster" | "follower" | "freeObserver" }): void
    - Parameters
      - stateName: "vision"
      - infos: { broadcaster: undefined | string; broadcasterName: undefined | string; mode: "broadcaster" | "follower" | "freeObserver" }
        
        broadcaster: undefined | string
        
        主播uid
        
        broadcasterName: undefined | string
        
        主播名称。优先使用昵称(nickname), 若初始化时未设置nickname，则为主播uid
        
        mode: "broadcaster" | "follower" | "freeObserver"
        
        broadcaster: 当前用户为主播，其他用户跟随当前用户视角 follower: 当前用户跟随主播视角 freeObserver：当前用户自由视角
      Returns void
Returns void

prevAnim

prevAnim(): void

跳转至上一动画。如果已经跳转到当前页第一个动画，则跳转至上一页面的最后一个动画结束状态。工具栏中对应的工具名称为prevAnim。

该动作仅在当前文档为动态ppt文档时才可以使用

Returns void

redo

redo(): void

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

Returns void

resetCamera

resetCamera(animate: boolean): void

重置白板位置

Parameters
- animate: boolean
  
  是否通过动画过渡到目标位置
Returns void

rotateElement

rotateElement(opt: { angle: number; id: string }): void

旋转当前画布上面的元素。注意angle的范围应该为[0, Math.PI * 2] 画布上面的元素可以使用DrawPlugin.getVisibleElementInfos获取
example
顺时针旋转当前画布上元素90度
```
const eles = drawPlugin.getVisibleElementInfos().filter(ele => ele.type === 'image')
if (eles.length > 0) {
     for (let ele of eles) {
          drawPlugin.rotateElement({id: ele.id, Math.PI/2})
     }
 }
```
Parameters
- opt: { angle: number; id: string }
  - angle: number
  - id: string
Returns void

setAppConfig

setAppConfig(opt: Partial<IAppConfig>): void

设置一些应用属性。这些属性只对当前客户端有影响。
example
设置白板背景色。注意若sdk版本小于3.6.0，请使用canvas_bg_color设置白板背景颜色
```
setAppConfig({
 canvasBgColor: 'rgb(255, 255, 255)'
})
```
Parameters
- opt: Partial<IAppConfig>
Returns void

setCameraBound

setCameraBound(bound: ICameraBound, animate: boolean): void

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

Parameters
- bound: ICameraBound
  
  目标坐标位置
- animate: boolean
  
  是否通过动画过渡到目标位置
Returns void

setColor

setColor(color: string): void

设置画笔颜色

example

默认工具栏调色盘中的颜色为：

[
    '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)'
]

Parameters

color: string

Returns void

setCustomBackground

setCustomBackground(coodinate: "world", customFn: (opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; rect: { centerX: number; centerY: number; height: number; width: number }; width: number; zoom: number }) => string | void, bgName: string): void
setCustomBackground(coodinate: "container", customFn: (opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; width: number; zoom: number }) => string | void, bgName: string): void

设置自定义背景绘制。用户可以使用此函数添加网格线、网格点等背景。

注意设置只对本地有效。不同客户端可以独立设置自己的背景图

coodinate为world时，绘制时的ctx已经转换为白板坐标系。容器的四个角落可以根据参数中的rect确定

下面是设置相对网格线的代码

example

下面是工具栏中相对网格线背景图的绘制方法


//
//寻找网格线的最佳gap
//最好的gap应该不太大，也不太小。最后需要满足： base  < gap < worldStressGap * base
//如果base为30，worldStressGap为5， 则 30 < gap < 150
//当gap逐渐变小，直至快小于base时，小网格将消失，大网格变为基线gap
//当gap逐渐变大，直至大于base * worldStressGap时，大网格中生出小网格
//
function findBestGap(opt: any, base: number, worldStressGap: number) {
     const {width, rect} = opt
     let gapInWorld = base
     let lineCount, gapInContainer: number
     
     while (true) {
         lineCount = rect.width / gapInWorld
         gapInContainer = width / lineCount
         if (gapInContainer < base) {
             gapInWorld *= worldStressGap
         } else if (gapInContainer > base * worldStressGap) {
             gapInWorld /= worldStressGap
         } else {
             break
         }
     }
     return {
         gapInWorld,
         gapInContainer
     }
 }

//找到起始的sx，sy
//即屏幕左上角第一个sx，sy的位置
//注意，需要从0，0开始找，这样不管白板如何缩放平移，只要gap按base的倍数变化，网格线的位置始终不会变
function findSxy(opt: any, gap: number) {
     const {rect} = opt
     let sx = 0
     let sy = 0
     let rectSx = rect.centerX - rect.width/2
     let rectSy = rect.centerY - rect.height/2
     while (true) {
         if (sx > rectSx) {
             sx -= gap
         } else if (sx + 2 * gap < rectSx) {
             sx += gap
         } else {
             break
         }
     }
     
     while (true) {
         if (sy > rectSy) {
             sy -= gap
         } else if (sy + 2 * gap < rectSy) {
             sy += gap
         } else {
             break
         }
     }
     
     return {sx, sy}
}


 drawPlugin.setCustomBackground('world', (opt) => {
     const rect = opt.rect
     const ctx = opt.ctx
     const worldGapBase = 35
     const worldStressGap = 5
     const maxAlpha = 0.2

     let {gapInWorld, gapInContainer} = findBestGap(opt, worldGapBase, worldStressGap)
      
     //gap *= worldStressGap是为了固定粗网格线的位置
     const {sx, sy} = findSxy(opt, gapInWorld * worldStressGap)
     ctx.beginPath()

     //
     // 先绘制小网格线
     //
     let count = -1
     for (let i = 0; sx + i < rect.centerX + rect.width/2; i+= gapInWorld) {
         count++
         if (count % worldStressGap === 0) continue  //每5个网格线使用透明度低的线条绘制
         ctx.moveTo(sx + i, sy)
         ctx.lineTo(sx + i, rect.centerY + rect.height/2)
     }
     count = -1
     for (let j = 0; sy + j < rect.centerY + rect.height/2; j+= gapInWorld) {
         count++
         if (count % worldStressGap === 0) continue  //每5个网格线使用透明度低的线条绘制
         ctx.moveTo(sx, sy + j)
         ctx.lineTo(rect.centerX + rect.width/2, sy + j)
     }
     ctx.lineWidth = 1/opt.zoom

     //网格越接近，alpha越小
     const alpha = Math.sqrt(Math.min((gapInContainer - worldGapBase) / (worldGapBase * (worldStressGap - 1)), 1)) * maxAlpha
     ctx.strokeStyle = `rgba(120, 120, 120, ${alpha})`
     ctx.stroke()

     //
     // 再绘制在5 * gap上面的大网格
     //
     ctx.beginPath()
     for (let i = 0; sx + i < rect.centerX + rect.width/2; i+= worldStressGap * gapInWorld) {
         ctx.moveTo(sx + i, sy)
         ctx.lineTo(sx + i, rect.centerY + rect.height/2)
     }
     for (let j = 0; sy + j < rect.centerY + rect.height/2; j+= worldStressGap * gapInWorld) {
         ctx.moveTo(sx, sy + j)
         ctx.lineTo(rect.centerX + rect.width/2, sy + j)
     }
     ctx.lineWidth = 1/opt.zoom
     ctx.strokeStyle = `rgba(120, 120, 120, ${maxAlpha})`
     ctx.stroke()
}, 'line-world')

Parameters

coodinate: "world"

背景图类型
customFn: (opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; rect: { centerX: number; centerY: number; height: number; width: number }; width: number; zoom: number }) => string | void

自定义背景绘制函数。如果类型为string，则会先使用eval函数提取函数
- - (opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; rect: { centerX: number; centerY: number; height: number; width: number }; width: number; zoom: number }): string | void
  - Parameters
    - opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; rect: { centerX: number; centerY: number; height: number; width: number }; width: number; zoom: number }
      - DPI: number
        
        devicePixelRatio。
      - ctx: CanvasRenderingContext2D
        
        绘制的canvas的句柄
      - height: number
        
        容器高度 = DPI * 容器css height
      - rect: { centerX: number; centerY: number; height: number; width: number }
        
        容器在白板坐标系中的范围
        
        centerX: number
        
        容器当前白板坐标系的中点x
        
        centerY: number
        
        容器当前白板坐标系的中点y
        
        height: number
        
        容器在白板坐标系中的高度
        
        width: number
        
        容器在白板坐标系中的宽度
      - width: number
        
        容器宽度 = DPI * 容器css width
      - zoom: number
        
        白板当前的缩放量
    Returns string | void
bgName: string

自定义背景名字。使用getBgRendererName可以返回该字段。可以用这个字段判断当前的自定义背景类型

Returns void

设置自定义背景绘制。用户可以使用此函数添加网格线、网格点等背景。

注意设置只对本地有效。不同客户端可以独立设置自己的背景图

coodinate为container时，绘制时的ctx使用容器坐标系。容器的位置为(0, 0)到(DPI * width, DPI * height)

下面是设置绝对网格线的代码
example
下面是工具栏中绝对网格线背景图的绘制方法
```
drawPlugin.setCustomBackground('container', (opt) => {
     const w = opt.width * opt.DPI
     const h = opt.height * opt.DPI
     const DPI = opt.DPI
     const ctx = opt.ctx

     //乘以DPI保证在不同机器上的显示效果一样
     const gap = 90 * DPI
     ctx.beginPath()
     for (let i = 0; i < w; i+= gap) {
         ctx.moveTo(i, 0)
         ctx.lineTo(i, h)
     }
     for (let i = 0; i < h; i+= gap) {
         ctx.moveTo(0, i)
         ctx.lineTo(w, i)
     }
     ctx.strokeStyle = `rgba(0, 0, 0, 0.15)`
     ctx.stroke()
}, 'line-container')
```
Parameters
- coodinate: "container"
  
  背景图类型
- customFn: (opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; width: number; zoom: number }) => string | void
  
  自定义背景绘制函数。如果类型为string，则会先使用eval函数提取函数
  - - (opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; width: number; zoom: number }): string | void
    - Parameters
      - opt: { DPI: number; ctx: CanvasRenderingContext2D; height: number; width: number; zoom: number }
        
        DPI: number
        
        devicePixelRatio。
        
        ctx: CanvasRenderingContext2D
        
        绘制的canvas的句柄
        
        height: number
        
        容器高度 = DPI * 容器css height
        
        width: number
        
        容器宽度 = DPI * 容器css width
        
        zoom: number
        
        白板当前的缩放量
      Returns string | void
- bgName: string
  
  自定义背景名字。使用getBgRendererName可以返回该字段。可以用这个字段判断当前的自定义背景类型
Returns void

setFontFamily

setFontFamily(opt: { fontFace?: { format?: string; url: string }[] | { format?: string; url: string }; fontFamily?: string }): void

设置文本的字体。最佳实践为设置一个常用的fontFamily, 同时设置fontFace, 作为这个fontFamily的备选的下载地址。
example
```
setFontFamily({
    fontFamily: "Helvetica",
    fontFace: [
        {
            url: '/assets/font/Helvetica.ttf',
            format: 'truetype'
        },
        {
            url: '/assets/font/Helvetica.woff',
            format: 'woff'
        },
        {
            url: '/assets/font/Helvetica.woff2',
            format: 'woff2'
        }
    ]
})
```
Parameters
- opt: { fontFace?: { format?: string; url: string }[] | { format?: string; url: string }; fontFamily?: string }
  - Optional fontFace?: { format?: string; url: string }[] | { format?: string; url: string }
    
    如果未提供fontFamily, 或者浏览器不支持该字体，则会使用fontFace提供的字体
    
    format支持: ['embedded-opentype', 'woff', 'truetype', 'svg', 'opentype', 'woff2']
  - Optional fontFamily?: string
    
    通用字体名称
Returns void

setOpacity

setOpacity(opacity: number): void

设置画笔透明度

Parameters
- opacity: number
  
  画笔透明度。范围为(0, 1]
Returns void

setPageBackground

setPageBackground(opt: { height: number; url: string; width: number }): void

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

注意静态文档是以背景图方式加载的。如果在静态文档页设置背景图，则静态文档页的静态图片会被替换
example
```
setPageBackground({
 url: 'xxxx',
 width: 1000,
 height: 1000
})
```
Parameters
- opt: { height: number; url: string; width: number }
  - height: number
  - url: string
    
    背景图URL
  - width: number
Returns void

setSelfAsBroadcaster

setSelfAsBroadcaster(): void

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

Returns void

setSelfAsFollower

setSelfAsFollower(): void

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

Returns void

setSelfAsFreeObserver

setSelfAsFreeObserver(): void

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

Returns void

setShowCursor

setShowCursor(value: boolean): void

设置是否广播当前用户的鼠标轨迹给其他用户

Parameters
- value: boolean
Returns void

setStrokeWidth

setStrokeWidth(width: number): void

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

Parameters
- width: number
Returns void

setTool

setTool(toolName: string): void

设置教具。教具为工具栏中支持的，非一次性动作的工具栏图标

Parameters
- toolName: string
  
  目前支持的教具有：select, pen, pen-arrow, line, line-arrow, rect, ellipse, laser, text, element-eraser, pan
Returns void

stopStream

stopStream(): void

关闭白板视频流。

如果停止了白板直播，可以调用该函数销毁白板推流的相关对象，防止无谓的性能消耗。WhiteboardSDK.destroy时会自动调用该函数

Returns void

undo

undo(): void

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

Returns void

unlockCameraWithContent

unlockCameraWithContent(): void

解除相机与标注物之间的对齐关系

Returns void

unsetCustomBackground

unsetCustomBackground(): void

删除自定义背景绘制。设置后再次调用getBgRendererName时，会返回undefined

Returns void

unsetSelfAsBroadcaster

unsetSelfAsBroadcaster(): void

停止视角同步

Returns void

updateContainerAfterResize

updateContainerAfterResize(): void

白板容器的宽高变化后，可以使用该函数刷新容器的显示。白板本身设置了mutationObserver处理容器变化。但是有时候该事件可能会失效。这时候，开发者可以主动更新容器的属性。

Returns void

updateStream

updateStream(opt?: { keepDPI?: boolean; width?: number }): MediaStream

更新现有的stream。如果当前不存在stream，则返回一个新的stream。如果存在stream，则直接更新现有stream的分辨率

Parameters
- Optional opt: { keepDPI?: boolean; width?: number }
  - Optional keepDPI?: boolean
    
    默认为true
    
    如果设置了width，则该参数无效如果未设置width，参数为true时，视频流的大小为容器宽度 * DPI
  - Optional width?: number
    
    视频流宽度。高度根据容器宽高比自动计算
    
    若不指定，则视频分辨率随容器宽度变化
Returns MediaStream

zoomIn

zoomIn(): void

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

Returns void

zoomOut

zoomOut(): void

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

Returns void

zoomTo

zoomTo(scale: number, animate: boolean): void

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

Parameters
- scale: number
  
  1表示缩放至100%
- animate: boolean
  
  是否通过动画过渡到目标位置
Returns void

Hierarchy

Index

Methods

Methods

addBoard

Parameters

docName: string

pageCount: number

Returns string

addDoc

Parameters

opt: { docName: string; params: IStaticDocParam | IStaticDocParamDeprecated[] }

docName: string

params: IStaticDocParam | IStaticDocParamDeprecated[]

Returns string

addImage

Parameters

opt: { boardName?: string; height: number; pageIndex?: number; url: string; width: number }

Optional boardName?: string

height: number

Optional pageIndex?: number

url: string

width: number

Returns void

addPage

Parameters

opt: { insertAfter?: number; payload: any }

Optional insertAfter?: number

payload: any

Returns void

addTransDoc

Parameters

opt: { docName: string; height: number; pageCount: number; url: string; width: number }

docName: string

height: number

pageCount: number

url: string

width: number

Returns string

addVideo

Parameters

opt: { boardName?: string; pageIndex?: number; sourceType: string; title?: string; url: string; width?: number }

Optional boardName?: string

Optional pageIndex?: number

sourceType: string

Optional title?: string

url: string

Optional width?: number

Returns void

clear

Returns void

deleteBoard

Parameters

boardName: string

Returns void

deletePage

Parameters

index: number

Returns void

duplicate

Returns void

enableDraw

Parameters

enable: boolean

Returns void

exportAsBase64String

Parameters

Optional opt: { content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; type?: "jpeg" | "png" }

Optional content?: "clip" | "fitToDoc" | "fitToContent"

Optional customBg?: boolean

Optional omitSelection?: boolean

Optional quality?: number

Optional type?: "jpeg" | "png"

Returns null | { content: string; height: number; width: number }

exportAsImage

Parameters

Optional opt: { content?: "clip" | "fitToDoc" | "fitToContent"; customBg?: boolean; omitSelection?: boolean; quality?: number; type?: "jpeg" | "png" }

Optional content?: "clip" | "fitToDoc" | "fitToContent"

Optional customBg?: boolean

Optional omitSelection?: boolean