API 概览
ArWhiteBoard
ErrorCode

白板构造函数

最近更新时间：2023-07-14 08:47:02

事件回调
add-board
delete-board
goto-board
clear-board
reset-board
data-sync-completed
board-can-redo-status
board-can-undo-status
board-error
board-scale-change
board-ratio-change
board-warning
connection-state-change
board-background-color-change
board-image-status-changed
核心方法
constructor
destroy
涂鸦相关方法
clear
getBrushColor
getBrushThin
getBrushType
getEnable
getTextColor
getTextSize
resize
setBrushColor
setBrushThin
setBrushType
setEnable
setTextColor
setTextSize
白板页相关方法
addBoard
deleteBoard
getBoardList
getBoardScale
getBoardRatio
getBoardSnapshot
getCurrentBoardId
getCurrentFileId
getFileBoardList
getFileInfo
gotoBoard
nextBoard
prevBoard
reset
setBoardScale
setBoardRatio
背景相关
getBackgroundColor
getGlobalBackgroundColor
getBackgroundImage
getBackgroundImageFillMode
setBackgroundColor
setBackgroundImage
setGlobalBackgroundColor
撤销和重做相关
undo
redo
其他方法
getVersion

Web SDK 的入口。

SDK 会在全局导出一个 ArWhiteBoard 对象，可以通过 new 方法创建一个白板实例。一个白板实例代表一个白板客户端。

// 初始化配置
const initConfig = {
  id: '<DOM_ID>',
  appId: '<APP_ID>',
  userId: '<U_ID>',
  channel: '<CHANNEL_ID>',
  token: '<TOKEN>',
}
const Board = new ArWhiteBoard(initConfig)

事件回调

add-board

add-board(fileId: string, boardIds: string[]): void

添加白板页回调

/**
 * 添加白板页回调
 */
board.on('add-board', (fileId, boardIds) => {})

参数

  • fileId: string

    白板的文件 ID，默认为 #DEFAULT

  • boardIds: string[]

    白板页 ID 列表。

返回值 void

delete-board

delete-board(fileId: string, boardIds: string[]): void

当前白板页是否可重做回调

board.on('delete-board', (fileId, boardIds) => {})

参数

  • fileId: string

    白板的文件 ID，默认为 #DEFAULT

  • boardIds: string[]

    白板页 ID 列表。

返回值 void

goto-board

goto-board(fileId: string, boardId: string): void

白板页切换回调

board.on('goto-board', (fileId, boardId) => {})

参数

  • fileId: string

    白板的文件 ID，默认为 #DEFAULT

  • boardId: string

    跳转到的白板页 ID

返回值 void

clear-board

clear-board(fileId: string, boardId: string, clearBackground: boolean): void

清空画板回调

/**
 * 清空画板回调
 */
board.on('clear-board', (fileId, boardId, clearBackground) => {})

参数

  • fileId: string

    文件 ID。

  • boardId: string

    画板 ID。

  • clearBackground: boolean

    画板背景颜色或背景图片是否被清空。

返回值 void

reset-board

reset-board(): void

重置画板回调

/**
 * 重置画板回调
 */
board.on('reset-board', () => {})

返回值 void

data-sync-completed

data-sync-completed(): void

历史数据同步完成回调

/**
 * 历史数据同步完成回调
 */
board.on('data-sync-completed', () => {})

返回值 void

board-can-redo-status

board-can-redo-status(enable: boolean): void

当前白板页是否可重做回调

board.on('board-can-redo-status', (enable) => {})

参数

  • enable: boolean

    • true 则表示可以执行 redo 操作
    • false 则表示不可以执行 redo 操作。

返回值 void

board-can-undo-status

board-can-undo-status(enable: boolean): void

当前白板页是否可撤销回调

board.on('board-can-undo-status', (enable) => {})

参数

  • enable: boolean

    • true 则表示可以执行 undo 操作
    • false 则表示不可以执行 undo 操作。

返回值 void

board-error

board-error(errorCode: EBoardErrorCode, errorMessage: string): void

当前白板页是否可撤销回调

board.on('board-error', (errorCode, errorMessage) => {
  // console.log("board-error ", errorCode, errorMessage)
})

参数

白板错误码

  • errorMessage: string

白板错误提示

返回值 void

board-scale-change

board-scale-change(boardId: string, scale: number): void

白板页缩放比例变化的回调

board.on('board-scale-change', (boardId, scale) => {})

参数

  • boardId: string

    缩放变化的白板页 ID

  • scale: number

    缩放比例。

返回值 void

board-ratio-change

board-ratio-change(boardId: string, ratio: string): void

白板页宽高比例变化的回调

board.on('board-ratio-change', (boardId, ratio) => {})

参数

  • boardId: string

    改变宽高比例的白板页 ID

  • ratio: string

    宽高比例。

返回值 void

board-warning

board-warning(errorCode: EBoardWarningCode, errorMessage: string): void

白板警告回调

board.on('board-warning', (errorCode, errorMessage) => {
  // console.log("board-warning ", errorCode, errorMessage)
})

参数

  • errorCode: EBoardWarningCode

白板警告码

  • errorMessage: string

白板错误提示

返回值 void

connection-state-change

connection-state-change(authState: EBoardConnectionState, reason: string): void

网络状态回调。

board.on('connection-state-change', (authState, reason) => {})

参数

  • authState: EBoardConnectionState

    当前的网络连接状态。

  • reason: string

    触发当前网络连接状态的原因。

返回值 void

board-background-color-change

board-background-color-change(fileId: 'string', boardId: string, color: string): void

画板背景颜色改变回调

/**
 * 画板背景颜色改变回调
 */
board.on('board-background-color-change', (fileId, boardId, color) => {})

参数

  • fileId: string

    文件 ID。

  • boardId: string

    画板 ID。

  • color: string

    背景颜色。

返回值 void

board-image-status-changed

board-image-status-changed(fileId: string, boardId: string, status: BoardImageStatus, data: { imageFillMode: EBoardImageFillMode, imageUrl: string }): void

画板背景图片加载状态回调

/**
 * 画板背景颜色改变回调
 */
board.on('board-image-status-changed', (fileId, boardId, status, data) => {})

参数

  • fileId: string

    文件 ID。

  • boardId: string

    画板 ID。

  • status: BoardImageStatus

    设置背景图片后的图片加载状态。

  • data: object

    背景图片的相关信息

    • imageFillMode: EBoardImageFillMode

      背景图片填充方式

    • imageUrl: string

      背景图片地址

核心方法

constructor

constructor(initParams?: IArBoardInitParams): this

创建白板客户端（实例）。

示例：

<body>
  <div
    id="myBoard"
    style="width: 640px; height: 480px; background-color: #ffffff;"
  ></div>
</body>

// 初始化配置
const initConfig = {
  id: 'myBoard',
  appId: '<APP_ID>',
  userId: '<U_ID>',
  channel: '<CHANNEL_ID>',
  token: '<TOKEN>',
}
const Board = new ArWhiteBoard(initConfig)

参数

返回值 ArWhiteBoard

destroy

destroy(): Promise<void>

销毁白板客户端

返回值 Promise<void>

涂鸦相关方法

clear

clear(clearBackground?: boolean): void

清空当前白板页数据。

默认只清除当前白板页的涂鸦，如果 clearBackground 参数为 true，则同时清除涂鸦和背景。

参数

  • clearBackground: boolean

    是否需要清空背景标识。

    • true: 清空背景图片和背景颜色
    • false: （默认）只清除涂鸦。

返回值 void

getBrushColor

getBrushColor(): string

获取画笔颜色

返回值 Promise<void>

getBrushThin

getBrushThin(): number

获取画笔粗细

返回值 number

getBrushType

getBrushType(): EBoardToolType

获取画笔类型

返回值 EBoardToolType

getEnable

getEnable(): boolean

获取白板是否可涂鸦

返回值 boolean

getTextColor

getTextColor*): string

获取设置的文字颜色（十六进制）。例如：#FFFFFF、rgba(0, 0, 0, 1)。

返回值 string

getTextSize

getTextSize(): number

获取设置的文字大小

返回值 number

resize

resize(): void

重新计算白板大小，并渲染

返回值 void

setBrushColor

setBrushColor(color: string): void

设置画笔颜色。

参数

  • color: string

    十六进制的背景颜色。例如：#ffffff，不区分大小写，或者 rgba(0, 0, 0, 1)。

返回值 void

setBrushThin

setBrushThin(thin: number): void

设置画笔粗细。

参数

  • thin: number

    画笔的粗细。

返回值 void

setBrushType

setBrushType(type: EBoardToolType): void

设置画笔工具类型。

参数

示例代码

Board.setBrushType(0)

返回值 void

setEnable

setEnable(enable: boolean): boolean

获取白板是否可涂鸦。

参数

  • enable: boolean

    白板是否可涂鸦。

    • true: 可涂鸦
    • false: 不可涂鸦

返回值 void

setTextColor

setTextColor(color: string): void

设置的文字颜色。

参数

  • color: string

    十六进制的背景颜色。例如：#ffffff，不区分大小写，或者 rgba(0, 0, 0, 1)。

返回值 void

setTextSize

setTextSize(Size: number): void

设置文字的大小。

参数

  • Size: number

    字体大小。

返回值 void

白板页相关方法

addBoard

addBoard(): void

添加一页白板并切换到这一页

返回值 void

deleteBoard

deleteBoard(): void

删除当前白板页并切换到上一页

返回值 Promise<void>

getBoardList

getBoardList(): string[]

获取所有文件的白板列表

返回值 string[]

getBoardScale

getBoardScale(): number

获取当前白板页的缩放比例。

返回值 number

getBoardRatio

getBoardRatio(): number

获取当前白板页缩放比例。

返回值 string

getBoardSnapshot

getBoardSnapshot(): Promise<string>

获取当前白板页的快照。

返回值 Promise<string>

getCurrentBoardId

getCurrentBoardId(): string

获取当前白板页 ID。

返回值 string

getCurrentFileId

getCurrentFileId(): string

获取当前文件 ID

返回值 string

getFileBoardList

getFileBoardList(fileId: string): string[]

获取指定文件的白板 ID 列表

参数

  • fileId: string

    文件 ID。

返回值 string[]

getFileInfo

getFileInfo(fileId: string): IFileInfo

获取白板的基本信息。

参数

  • fileId: string

    文件 ID。

返回值 IFileInfo

gotoBoard

gotoBoard(boardId: string): void

切换到指定的白板页。

参数

  • boardId: string

    需要切换到指定页的白板 ID。

返回值 void

nextBoard

nextBoard(): void

切换到下一页白板。

返回值 void

prevBoard

prevBoard(): void

切换到上一页白板。

返回值 void

reset

reset(): void

重置白板

删除所有白板页和涂鸦。

返回值 void

setBoardScale

setBoardScale(scale: number): void

设置当前白板页的缩放比例。

参数

  • scale: number

    白板缩放的比例。比如：100 则为不缩放，范围在 [100 ~ 300] 之间。

返回值 void

setBoardRatio

setBoardRatio(ratio: string): void

设置当前白板页宽高比例。

为保证最佳的显示效果，各个端（iOS/Android/Web）在产品上应该保证统一的宽高比例。

参数

  • ratio: string

    白板页的宽高比例。例如，设置的横屏比例有：16:9、4:3；竖屏比例有 9:16、3:4。

返回值 void

背景相关

getBackgroundColor

getBackgroundColor(): string

获取当前白板页的背景颜色。

返回值 string

getGlobalBackgroundColor

getGlobalBackgroundColor(): string

获取全局设置的白板页背景颜色。

返回值 string

getBackgroundImage

getBackgroundImage(): string

获取当前白板页的背景图片。

返回值 string

getBackgroundImageFillMode

getBackgroundImageFillMode(): EBoardImageFillMode

获取当前白板页的背景图片填充模式。

返回值 EBoardImageFillMode

setBackgroundColor

setBackgroundColor(color: string): void

设置当前白板页的背景颜色。

参数

  • color: string

    十六进制的背景颜色。例如：#ffffff，不区分大小写,或者 rgba(0, 0, 0, 1)。

返回值 void

setBackgroundImage

setBackgroundImage(image: string, fillMode: EBoardImageFillMode): void

设置当前白板页的背景图片。

参数

  • image: string

    背景图片的 url 或者 base64 的图片地址。

    注意事项

    • url 必须是 https 链接
    • 资源必须允许跨域或者允许当前域

  • fillMode: EBoardImageFillMode

    默认 contain

返回值 void

setGlobalBackgroundColor

setGlobalBackgroundColor(color: string): void

全局设置白板页的背景颜色。

  • 后续创建的画板默认为现在设置的颜色
  • 现在存在的所有画板背景颜色全部更改为现在设置的颜色

参数

  • color: string

    十六进制的背景颜色。例如：#ffffff，不区分大小写，或者 rgba(0, 0, 0, 1)。

返回值 void

撤销和重做相关

undo

undo(): void

撤销当前白板页操作。

按从后往前的顺序取消白板页的操作，可撤销涂鸦的形状、画笔、以及形状的移动位置。

返回值 void

redo

redo(): void

重做当前白板页操作。

还原上一步被撤销的操作。

返回值 void

其他方法

getVersion

getVersion(): string

获取 SDK 版本。

返回值 string