You need to enable JavaScript to run this app.
导航

API 详情

最近更新时间2024.01.10 20:20:25

首次发布时间2022.11.21 13:14:37

IWhiteBoardRoomManager

类型: interface

getSdkVersion

获得当前 SDK 版本号。

类型

() => string

返回值

类型: string 版本号。

init

白板 SDK 初始化。

注意

在开始使用白板服务前,应调用本接口初始化白板。

类型

(params: IInitParams) => void

参数

IInitParams

类型: <code>[IInitParams](131863#iinitparams)</code>

初始化参数

joinRoom

创建白板实例并加入白板房间。

注意

如果白板房间在服务端不存在,则服务端按照传入参数创建房间,并触发 onCreateWhiteBoard

  • 进房成功后,可以调用 leaveRoom 离开房间。
  • 如果房间内所有用户都已结束互动,你可以调用 destroyRoom 关闭房间。

类型

(params: IJoinRoomParams) => Promise<IWhiteBoardRoom>

参数

params

类型: <code>[IJoinRoomParams](131863#ijoinroomparams)</code>

进入白板房间参数

返回值

类型: Promise<IWhiteBoardRoom> 白板房间实例

destroy

销毁 IWhiteBoardRoomManager 对象,释放资源。

类型

() => void

IWhiteBoardRoom

类型: interface

getRoomId

获得当前白板房间 ID。

注意

当本端用户已经进入白板房间后,你可以调用本接口查询当前房间 ID。

类型

() => string

返回值

类型: string 白板房间 ID

getRoomStatus

获取房间状态。

类型

() => Promise<StatusType>

返回值

类型: Promise<StatusType> 房间状态

leaveRoom

退出白板房间。

注意

  • 互动白板按照用户在房间内的时长进行计费,你应在当前用户结束白板使用时调用本接口退出房间。
  • 用户退出房间后,可以调用 joinRoom 再次加入该房间。
  • 如果房间内所有用户都已结束互动,你可以调用 destroyRoom 关闭房间。

类型

() => Promise<void>

返回值

类型: Promise<void>

destroyRoom

关闭房间内所有白板,重进房间后无法进行写画。

注意

  • 如果你希望在下次进房时仍可以继续进行白板互动,应调用 leaveRoom 退房,此后调用 joinRoom 进房,可以继续此前的白板操作。
  • 如果已经在控制台开通和配置了白板录制,白板创建后自动录制。只有当调用本接口关闭白板之后,才可以开始播放录像。

类型

() => Promise<DestroyRoomResult>

返回值

类型: Promise<DestroyRoomResult> 关闭白板提示

switchWhiteBoard

指定当前白板。在对白板进行编辑等操作前,需要将该白板设置为当前白板。

注意

调用后将触发 onCurrentWhiteBoardChanged

类型

(boarId: number) => Promise<SwitchBoardResult>

参数

boarId

类型: <code>number</code>

白板Id

返回值

类型: Promise<SwitchBoardResult>

removeWhiteBoard

关闭指定白板。

注意

调用后将触发 onRemoveWhiteBoard

类型

(boardId: number) => Promise<RemoveWhiteBoardResult>

参数

boarId

类型: <code>number</code>

白板 ID

返回值

类型: Promise<RemoveWhiteBoardResult>

getCurrentWhiteBoard

获取当前的白板实例。

注意

  • 调用 joinRoom 加入房间后,调用本接口获取当前白板。如果返回 null,则调用 createWhiteBoard 创建一个白板。

类型

() => Promise<IWhiteBoard | null>

返回值

类型: Promise<IWhiteBoard | null> + 当前的白板实例

  • 当前房间内没有白板,返回 null

getCurrentWhiteBoardId

获取当前的白板 ID。

类型

() => Promise<number>

返回值

类型: Promise<number> 当前白板 ID

getAllWhiteBoardInfo

获取房间内所有白板的信息。

类型

() => Promise<WebBoardInfo[]>

返回值

类型: Promise<WebBoardInfo[]> 房间内所有白板的信息

createWhiteBoard

在房间内创建一个白板。

注意

  • 调用 joinRoom 加入房间后,你可以调用本接口创建白板。
  • 调用成功后,房间内所有用户都将收到 onCreateWhiteBoard 回调。
  • 如果当前房间已有白板,你应该调用 getCurrentWhiteBoard 获取当前白板。
  • 你可以传入不同的白板参数,在同一个房间内创建多个白板。

类型

(createBoardOptions?: CreateWhiteBoardInfo) => Promise<CreateWhiteBoardResult>

参数

createBoardOptions

类型: <code>[CreateWhiteBoardInfo](131863#createwhiteboardinfo) | undefined</code>

白板初始化参数

返回值

类型: Promise<CreateWhiteBoardResult>

createFileWhiteBoard

在房间内创建 PPT 白板

注意

调用本接口前,应先调用 createTranscodeTask,传入 PPT 的 URL 地址,并获取到 fileId。
调用成功后房间内所有用户将收到 onCurrentWhiteBoardChanged

类型

(createBoardOptions?: CreateFileWhiteBoardInfo) => Promise<CreateWhiteBoardResult>

参数

createBoardOptions

类型: <code>[CreateFileWhiteBoardInfo](131863#createfilewhiteboardinfo) | undefined</code>

创建 PPT 白板的初始项目

返回值

类型: Promise<CreateWhiteBoardResult>

getWhiteBoardInfo

通过白板 ID 获取白板信息。

类型

(boardId: number) => Promise<WebBoardInfo | undefined>

参数

boardId

类型: <code>number</code>

白板 ID

返回值

类型: Promise<WebBoardInfo | undefined> 白板信息。
获取失败时,返回 null。例如,传入的 boardID 有误。

createTranscodeTask

创建一个转码任务。

注意

转码成功后,调用 createFileWhiteBoard,并传入获取到的 fileId,得到可以交互的 PPT 白板。

类型

(params: IDocsCreateTranscodeTask) => Promise<IDocsTranscodeResult>

参数

params

类型: <code>[IDocsCreateTranscodeTask](131863#idocscreatetranscodetask)</code>

转码任务配置

返回值

类型: Promise<IDocsTranscodeResult> 转码任务结果。

startPlayback

开始播放白板录像。

注意

  • 调用后将触发 onPlaybackStateChanged
  • 使用录像和回放时,需要在控制台开通和配置白板录制功能。
  • 调用时机:房间中至少有一个用户 destroyRoom 关闭白板,之后,所有用户在重新进房后,即调用 leaveRoom 退房,再调用 joinRoom 重新进房后,才可以调用本接口开始播放录像。

类型

() => Promise<void>

返回值

类型: Promise<void>

pausePlayback

暂停播放录像。

注意

类型

() => void

stopPlayback

停止播放录像。

注意

类型

() => void

setPlaybackProgress

设置白板回放进度。

注意

类型

(progress: number) => Promise<void>

参数

progress

类型: <code>number</code>

播放位置相当于录像时长的占比。范围 [0,1]。

返回值

类型: Promise<void>

IWhiteBoard

类型: interface

setViewMode

设置白板视图跟随模式。

注意

  • 设置为跟随模式时,无需手动调用 zoomInzoomOutzoomTo,SDK 将自动同步为控制方的视图设置。

类型

(viewMode: ViewMode) => ViewMode

参数

viewMode

类型: <code>[ViewMode](131863#viewmode)</code>

视角同步模式。默认为跟随模式。

返回值

类型: ViewMode 当前视角同步模式

getViewMode

获取视图模式。

类型

() => ViewMode

返回值

类型: ViewMode 视图跟随模式

removePages

按照指定的索引号,删除白板页。

注意

调用本接口成功后,白板 SDK 将按原顺序给剩下的页面重新编号。被删除页面之后的页面索引号会发生改变,房间中所有用户将收到 onPageIndexChanged 回调。

类型

(pageIdList: string[], flipPageIndex?: number) => Promise<RemovePagesResult>

参数

pageIdList

类型: <code>string[]</code>

需要删除的页面的 PageId 列表。

flipPageIndex

类型: <code>number | undefined</code>

删除页面后,跳转到指定索引号页面。参数为空时的表现:
  • 当前页未被删除时,不翻页。
  • 删除包含当前页在内的不连续多页时:翻到第一个被删除的页面的下一页。
  • 删除当前页或包含当前页在内的连续多页时:翻到下一页,如果删除的页面为最末页,则翻到前一页。

返回值

类型: Promise<RemovePagesResult> + Resolve: 成功。成功调用后,房间中所有用户将收到 onRemovePagesonPageCountChanged 回调。

  • Reject: 失败。频繁调用,小于 500 ms;或传入的参数为空。

zoomIn

以当前视图中心为中心点放大白板视图。

注意

  • 当多个用户同时进行缩放设置时,发起较晚的用户设置失败。
  • 如果需要用户通过手势进行缩放可以通过 setEditType 设置为 ZOOM。

类型

(scale: number) => boolean

参数

scale

类型: <code>number</code>

缩放系数增量。每次调用后,缩放系数增加 `scale`。

当缩放系数超过范围时,将置为临界点。缩放系数的范围 [1, 20]。1 表示原始大小。放大系数上限默认为 20,以调用 setMaxZoom 设置的为准。

返回值

类型: boolean 调用结果

  • true: 成功
  • false: 失败。当前用户的视图设置为跟随模式 kFollow = 1

zoomOut

以当前视图中心为中心点缩小白板视图。

注意

  • 当多个用户同时进行缩放设置时,发起较晚的用户设置失败。
  • 如果需要用户通过手势进行缩放可以通过 setEditType 设置为 ZOOM。

类型

(scale: number) => boolean

参数

scale

类型: <code>number</code>

缩放系数减量。每次调用后,缩放系数减少 `scale`。

当缩放系数超过范围时,将置为临界点。缩放系数的范围 [1, 20]。1 表示原始大小。放大系数上限默认为 20,以调用 setMaxZoom 设置的为准。

返回值

类型: boolean 调用结果

  • true: 成功
  • false: 失败。当前用户的视图设置为跟随模式 kFollow = 1

zoomTo

按照指定中心点和缩放系数缩放白板视图。

注意

  • 缩放中心点为当前视图中心。
  • 当多个用户同时进行缩放设置时,将按服务端收到指令的时间顺序应用设置。
  • 如果需要用户通过手势进行缩放可以通过 setEditType 设置为 ZOOM。

类型

(scale: number, offsetX?: number, offsetY?: number) => boolean

参数

scale

类型: <code>number</code>

缩放系数,范围 [1, 20]。1 表示原始大小。放大系数上限默认为 20,以调用 [setMaxZoom](#setmaxzoom) 设置的为准。

offsetX

类型: <code>number | undefined</code>

缩放中心点 X 坐标,默认为 0

offsetY

类型: <code>number | undefined</code>

缩放中心点 Y 坐标,默认为 0

返回值

类型: boolean 调用结果

  • true: 成功
  • false: 失败。例如缩放系数错误超过合法范围。

resetZoom

恢复默认缩放视图。还原到原始大小,视图中心点恢复为白板中心点。

类型

() => boolean

返回值

类型: boolean 调用结果

  • true: 成功
  • false: 失败。

getZoomFactor

获取当前白板视图缩放系数。

类型

() => number

返回值

类型: number 当前白板视图缩放系数。范围 [1, 20]。1 表示原始大小。放大系数上限默认为 20,以调用 setMaxZoom 设置的为准。

setMaxZoom

设置白板视图最大放大系数。

注意

设置成功后,将改变调用以下 API 的参数上限: zoomInzoomOutzoomTo

类型

(maxScale: number) => void

参数

maxScale

类型: <code>number</code>

白板视图最大放大系数,范围 [1, 20]。默认为 20。

exportSnapshot

将当前白板中指定页面保存为一张本地图片

注意

  • 短时间内多次调用本 API 时,等待获取结果回调时间可能增加。
  • PPT 白板页导出的快照仅包含预加载状态的图片。

类型

(params?: ExportSnapshotOptions) => Promise<string | undefined>

参数

params

类型: <code>[ExportSnapshotOptions](131863#exportsnapshotoptions) | undefined</code>

快照选项

返回值

类型: Promise<string | undefined> Resolve 返回图片,格式为经过 Base 64 编码的字符串。

getWhiteBoardId

获取当前的白板 ID。

类型

() => number

返回值

类型: number 白板 ID

getWhiteBoardRoomId

获取当前白板所在的房间 ID。

类型

() => string

返回值

类型: string 白板房间 ID

setWritable

设置当前白板是否可以编辑。

类型

(writeable: boolean) => void

参数

writeable

类型: <code>boolean</code>

是否可以编辑

getWritable

获取当前白板是否可以编辑。

类型

() => boolean

返回值

类型: boolean

setEditType

设置编辑动作类型。

注意

如果默认的光标图形无法满足你的需求,调用 setCursorStyle,为不同工具过指定光标图形和样式。

类型

(key: EditType) => void

参数

key

类型: <code>[EditType](131863#edittype)</code>

编辑动作类型。

getEditType

获取当前编辑动作类型。

注意

如果默认的光标图形无法满足你的需求,调用 setCursorStyle,为不同工具过指定光标图形和样式。

类型

() => EditType

返回值

类型: EditType 编辑动作类型

setBoardBackground

修改当前白板的背景设置,例如背景图片颜色等。

注意

类型

(params: WebBackgroundInfo) => Promise<SetBoardBackgroundResult>

参数

params

类型: <code>[WebBackgroundInfo](131863#webbackgroundinfo)</code>

背景信息

返回值

类型: Promise<SetBoardBackgroundResult> + Resolve:成功

  • Reject: 失败原因

addImage

在当前页面中添加图片。

类型

(url: string, options?: AddImageOptions) => Promise<void>

参数

url

类型: <code>string</code>

图片的 url。

options

类型: <code>[AddImageOptions](131863#addimageoptions) | undefined</code>

图片的位置和尺寸,单位为画布宽度的万分之一。

选填。默认居中放置,如果图片尺寸比白板页面小,不缩放;如果图片尺寸比白板页面大,按原始尺寸的比例缩小后居中放置。

返回值

类型: Promise<void>

addVideo

在当前页面中添加视频,只支持 mp4 格式。

注意

  • 你可以在普通白板页和 PPT 白板页添加视频。
  • 每个页面最多只能插入 1 个视频文件和 1 个音频文件。
  • 播放器默认居中放置。
  • 当 EditType 为 Pointer 时,用户可以对视频文件进行控制,包括播放、暂停和进度跳转等。也可以移动、缩放、全屏和删除播放器。这些操作都将实时同步到远端。音量控制只在本端生效。
  • 画笔等笔迹工具不支持在播放器上进行绘制。

类型

(url: string, options?: AddMediaOptions) => Promise<void>

参数

url

类型: <code>string</code>

视频的 url。建议视频文件的大小不超过 1 GB。你需要将用户的视频文件上传到对象存储服务空间中,并获取访问链接。

options

类型: <code>[AddMediaOptions](131863#addmediaoptions) | undefined</code>

文件名称。选填。默认为 URL 中解析出的文件名。

返回值

类型: Promise<void>

addAudio

在当前页面中添加音频,只支持 mp3 格式。

注意

  • 你可以在普通白板页和 PPT 白板页添加音频。
  • 每个页面最多只能插入 1 个视频文件和 1 个音频文件。
  • 默认居中放置。用户可以使用鼠标移动文件位置。
  • 当 EditType 为 Pointer 时,用户可以对音频文件进行控制,包括播放、暂停和进度跳转等。也可以移动、缩放和删除播放器。这些操作都将实时同步到远端。音量控制只在本端生效。
  • 画笔等笔迹工具不支持在播放器上进行绘制。

类型

(url: string, options?: AddMediaOptions) => Promise<void>

参数

url

类型: <code>string</code>

音频的 url。建议音频文件的大小不超过 50 MB。你需要将用户的音频文件上传到对象存储服务空间中,并获取访问链接。

options

类型: <code>[AddMediaOptions](131863#addmediaoptions) | undefined</code>

文件名称。选填。默认为 URL 中解析出的文件名。

返回值

类型: Promise<void>

setSelectionBoxStyle

设置选择框样式。如果默认的选择框样式无法满足你的需求,调用本接口,并传入需要修改的属性。

类型

(shapeStyle: ShapeStyle) => void

参数

shapeStyle

类型: <code>[ShapeStyle](131863#shapestyle)</code>

选择框样式。

setShapeSize

设置图形线条尺寸。

类型

(thickness: number) => void

参数

thickness

类型: <code>number</code>

图形线条尺寸,[1, 10000]。单位为画布宽度的万分之一

setShapeColor

设置图形颜色。

类型

(color: string) => void

参数

color

类型: <code>string</code>

图形的颜色,例如 rgba(0,0,0,255)。

setPenSize

设置画笔尺寸。

类型

(thickness: number) => void

参数

thickness

类型: <code>number</code>

笔尖尺寸。[1, 10000]。单位为画布宽度的万分之一

setPenColor

设置画笔颜色。

类型

(color: string) => void

参数

color

类型: <code>string</code>

画笔的颜色,例如 rgba(0,0,0,255)。

setTextColor

设置文字颜色。

类型

(color: string) => void

参数

color

类型: <code>string</code>

文字的颜色,例如 rgba(0,0,0,255)。

setTextFontSize

设置文本字号大小。

类型

(thickness: number) => void

参数

thickness

类型: <code>number</code>

文本字号大小,[1, 10000]。单位为画布高的万分之一

redo

重做本端对白板的编辑操作。

类型

() => number | false

返回值

类型: number | false + >0:成功。数字为剩余的可重做次数。当前用户将收到 onRecordUpdated 回调。

  • False:失败

undo

撤销本端对白板的编辑操作。

类型

() => number | false

返回值

类型: number | false + >0:剩余的可撤回次数。当前用户将收到 onRecordUpdated 回调。

  • False:失败

createPages

创建多个白板页面。在使用文档转码功能后,可以调用本接口,将生成的多个图片批量插入到多个新的白板页面中。

类型

(pageConfigs: WebPageCreateInfo[], options?: CreatePageOptions) => Promise<CreatePageProgressResult>

参数

pageConfigs

类型: <code>[WebPageCreateInfo](131863#webpagecreateinfo)[]</code>

页面信息数组。

options

类型: <code>[CreatePageOptions](131863#createpageoptions) | undefined</code>

创建页面选项

返回值

类型: Promise<CreatePageProgressResult> + Resolve:调用成功后,本端和远端都将收到 onCreatePagesProgress 回调,提示页面创建进度。

  • Reject:失败原因。

clearPage

清空白板。删除当前白板页面上所有的笔迹元素和已插入的图片。

注意

  • 调用成功后,房间内所有用户都将收到 onClearPage 回调。
  • 如果你需要删除白板上的部分笔迹或形状等元素,可以引导用户在使用选择工具选择元素后,再按下 键删除选中元素。

类型

() => void

setPageBackground

修改当前白板页面的背景设置,例如背景图片颜色等。

注意

  • 调用本回调后会在本端和远端触发 onPageBackgroundChanged
  • 调用本接口传入不同的页面配置可以更新背景设置。
  • 调用 setBoardBackground 可以设置白板背景。页面背景显示优先级高于白板背景,与调用顺序无关。

类型

(params: WebBackgroundInfo) => Promise<SetPageBackgroundResult>

参数

params

类型: <code>[WebBackgroundInfo](131863#webbackgroundinfo)</code>

当前白板页面的背景设置

返回值

类型: Promise<SetPageBackgroundResult> + Resolve:成功

  • Reject: 失败原因

flipPage

白板翻页。

类型

(pageIndex: number) => Promise<FlipPageResult>

参数

pageIndex

类型: <code>number</code>

目标页 Index。

返回值

类型: Promise<FlipPageResult> + Resolve: 成功。返回当前页 Index。并在房间内所有客户端触发 onPageIndexChanged

  • Reject: 失败。频繁调用,小于 500 ms;或传入的参数为空。

flipNextPage

白板翻到下一页。

类型

() => Promise<FlipPageResult>

返回值

类型: Promise<FlipPageResult> + true: 成功。返回当前页 Index。并在房间内所有客户端触发 onPageIndexChanged

  • false: 失败。频繁调用,小于 500 ms;或传入的参数为空。

flipPrevPage

白板翻到上一页。

类型

() => Promise<FlipPageResult>

返回值

类型: Promise<FlipPageResult> + true: 成功。返回当前页 Index。并在房间内所有客户端触发 onPageIndexChanged

  • false: 失败。频繁调用,小于 500 ms;或传入的参数为空。

getAllPageInfo

获取所有页面信息。

类型

() => WebPageInfo[]

返回值

类型: WebPageInfo[] 白板页信息。

getCurrentPageId

获取当前页面的 PageId。

类型

() => string

返回值

类型: string 页面 ID

getCurrentPageInfo

获取当前页面信息。

类型

() => WebPageInfo | undefined

返回值

类型: WebPageInfo | undefined 白板页信息

getCurrentPageIndex

获取当前页面索引。

类型

() => number

返回值

类型: number 索引, -1 表示没有找到索引

getPageCount

获取当前页面总数。

类型

() => number

返回值

类型: number 页面总数

getPageInfoByIndex

通过索引号获取白板页信息。

类型

(index: number) => WebPageInfo | undefined

参数

index

类型: <code>number</code>

索引

返回值

类型: WebPageInfo | undefined 白板信息

enableCursorSync

开启光标同步。开启后,房间中其他用户可以看到当前用户光标的实时移动轨迹。默认关闭。

类型

(enabled: boolean) => void

参数

enabled

类型: <code>boolean</code>

同步状态:
  • true: 开启
  • false: 关闭

setCursorStyle

自定义不同的工具光标样式。如果默认的光标图形无法满足你的需求,调用本接口,为不同工具过指定光标图形和样式。

类型

(params: Partial<CursorMap>) => void

参数

params

类型: <code>Partial<T\></code>

自定义光标样式。

getPptInfo

获取当前 PPT 信息

注意

调用 createFileWhiteBoard 可以创建一个 PPT 白板。

类型

() => PptInfo | undefined

返回值

类型: PptInfo | undefined 当前 PPT 信息。非 PPT 白板调用无效

pptNextStep

下一个 PPT 动画,如果是最后一个动画,翻到下一页

注意

类型

() => Promise<void>

返回值

类型: Promise<void> 非 PPT 白板调用无效

pptPrevStep

上一个 PPT 动画,如果是第一个动画,翻到上一页

注意

类型

() => Promise<void>

返回值

类型: Promise<void> 非 PPT 白板调用无效