需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

WhiteboardController class 参考

  • HarmonyOS

更新时间不可用

详细描述

适用版本：@shengwang/whiteboard 0.2.11。

房间操作控制器；由 Whiteboard 组件绑定，在 onRoomReady 后调用房间方法。

可从 @shengwang/whiteboard 直接导入 WhiteboardController。

类型结构（源码声明）

下方源码文件的 export 声明不等同于 SDK 包入口导出；业务导入方式以上方说明为准。

Text
export class WhiteboardController
setInitialWritablesetInitialWritable(writable: boolean) : void
attachWhiteboardattachWhiteboard = (whiteboard: DsBridge) => boolean
detachWhiteboarddetachWhiteboard = (whiteboard: DsBridge) => void
setWritablesetWritable(writable: boolean) : Promise<boolean>
getWritablegetWritable() : boolean
setAppliancesetAppliance(appliance: Appliance, shapeType?: ShapeType) : void
setStrokeColorsetStrokeColor(color: ResourceColor) : void
setStrokeWidthsetStrokeWidth(width: number) : void
setTextSizesetTextSize(size: number) : void
setTextColorsetTextColor(color: ResourceColor) : void
setMemberStatesetMemberState(state: MemberState) : void
copycopy() : void
pastepaste() : void
duplicateduplicate() : void
deleteOperationdeleteOperation() : void
disableSerializationdisableSerialization(disable: boolean) : void
redoredo() : void
undoundo() : void
setViewModesetViewMode(viewMode: ViewMode) : void
disconnectdisconnect() : Promise<object>
insertImageinsertImage(info: ImageInformation) : void
getRoomStategetRoomState() : Promise<RoomState>
getRoomPhasegetRoomPhase() : Promise<RoomPhase>
getRoomMembersgetRoomMembers() : Promise<RoomMember[]>
getMemberStategetMemberState() : Promise<MemberState>
getGlobalStategetGlobalState() : Promise<GlobalState>
getBroadcastStategetBroadcastState() : Promise<BroadcastState>
getSceneStategetSceneState() : Promise<SceneState>
getEntireScenesgetEntireScenes() : Promise<Record<string, Scene[]>>
setScenePathsetScenePath(path: string) : Promise<boolean>
setSceneIndexsetSceneIndex(index: number) : Promise<boolean>
putScenesputScenes(dir: string, scenes: Scene[], index: number) : void
moveScenemoveScene(srcPath: string, dstPath: string) : void
removeScenesremoveScenes(dirOrPath: string) : void
cleanScenecleanScene(retainPpt?: boolean) : void
refreshViewSizerefreshViewSize() : void
scalePptToFitscalePptToFit(mode?: AnimationMode) : void
disableCameraTransformdisableCameraTransform(disable: boolean) : void
disableDeviceInputsdisableDeviceInputs(disable: boolean) : void
disableWindowOperationdisableWindowOperation(disable: boolean) : void
setContainerSizeRatiosetContainerSizeRatio(ratio: number) : void
setPrefersColorSchemesetPrefersColorScheme(colorScheme: WindowPrefersColorScheme) : void
addAppaddApp(appParam: WindowAppParam) : Promise<string>
fitOriginSizeAndCamerafitOriginSizeAndCamera() : void
closeAppcloseApp(appId: string) : Promise<boolean>
focusAppfocusApp(appId: string) : Promise<boolean>
queryAppqueryApp(appId: string) : Promise<WindowAppSyncAttrs>
queryAllAppsqueryAllApps() : Promise<Record<string, WindowAppSyncAttrs>>
addPageaddPage(param: AddPageParam = {}) : void
removePageremovePage(param: RemovePageParam = {}) : void
insertTextinsertText(x: number, y: number, text: string) : Promise<string>
updateTextupdateText(identifier: string, text: string) : void
dispatchDocsEventdispatchDocsEvent(event: WindowDocsEvent) : Promise<DispatchDocsEventResult>
getPageStategetPageState(options?: WindowPageStateOptions) : Promise<UnifiedPageState>
setSyncModesetSyncMode(useSyncMode: boolean) : void
nextPagenextPage() : Promise<boolean>
prevPageprevPage() : Promise<boolean>
getLocalLogStategetLocalLogState() : Promise<object>
collectLocalLogscollectLocalLogs() : Promise<object>
flushLocalLogsflushLocalLogs() : Promise<object>
uploadLocalLogsuploadLocalLogs() : Promise<object>
reloadBackgroundImagereloadBackgroundImage(params: ReloadBackgroundImageParams) : Promise<ReloadBackgroundImageResult>
hasBackgroundImagehasBackgroundImage(params: HasBackgroundImageParams) : Promise<boolean>
leaveRoomleaveRoom(): Promise<object>
表格内容超出当前宽度，可横向滚动查看更多列。

函数说明

setInitialWritable

Text
setInitialWritable(writable: boolean) : void

组件内部生命周期接口；由 Whiteboard 组件管理，不作为业务入房或销毁入口。

attachWhiteboard

Text
attachWhiteboard = (whiteboard: DsBridge) => boolean

组件内部生命周期接口；由 Whiteboard 组件管理，不作为业务入房或销毁入口。

供 Whiteboard 组件绑定控制器；返回 boolean（当前实现为 true），不代表业务入房成功。房间方法等待 onRoomReady 后使用。

detachWhiteboard

Text
detachWhiteboard = (whiteboard: DsBridge) => void

组件内部生命周期接口；由 Whiteboard 组件管理，不作为业务入房或销毁入口。

组件解绑不等于所属房间退出完成；清理所有权仍由 SDK 保留，可继续通过 leaveRoom 等待所属 Room 清理。业务不应直接调用此内部绑定接口。

setWritable

Text
setWritable(writable: boolean) : Promise<boolean>

设置用户在房间中是否为互动模式。

参数

名称描述
writable用户在房间中是否为互动模式： - true：互动模式，即具有读写权限。 - false：订阅模式，即具有只读权限。
表格内容超出当前宽度，可横向滚动查看更多列。

@returns Promise 如果方法调用成功，则返回用户在房间中的读写状态（true 或 false）。 如果方法调用失败，则返回错误信息。

getWritable

Text
getWritable() : boolean

getWritable：WhiteboardController 的公开成员。参数和返回类型见下方签名。

setAppliance

Text
setAppliance(appliance: Appliance, shapeType?: ShapeType) : void

设置教具类型

参数

名称描述
appliance教具类型
shapeType形状
表格内容超出当前宽度，可横向滚动查看更多列。

setStrokeColor

Text
setStrokeColor(color: ResourceColor) : void

设置画笔颜色

参数

名称描述
color
表格内容超出当前宽度，可横向滚动查看更多列。

setStrokeWidth

Text
setStrokeWidth(width: number) : void

设置画笔粗细

参数

名称描述
width
表格内容超出当前宽度，可横向滚动查看更多列。

setTextSize

Text
setTextSize(size: number) : void

设置字大小

参数

名称描述
size
表格内容超出当前宽度，可横向滚动查看更多列。

setTextColor

Text
setTextColor(color: ResourceColor) : void

设置字颜色

参数

名称描述
color
表格内容超出当前宽度，可横向滚动查看更多列。

@remarks 默认状态下，文字的颜色和画笔颜色保持一致

setMemberState

Text
setMemberState(state: MemberState) : void

修改房间内的白板工具状态。

copy

Text
copy() : void

复制选中内容。

paste

Text
paste() : void

粘贴复制的内容。

duplicate

Text
duplicate() : void

复制并粘贴选中的内容。

deleteOperation

Text
deleteOperation() : void

删除选中的内容。

disableSerialization

Text
disableSerialization(disable: boolean) : void

开启/禁止本地序列化。

设置 disableSerialization(true) 后，undo redo 计数不生效、以下方法将不生效：

  • redo
  • undo

参数

名称描述
disable默认为 true
表格内容超出当前宽度，可横向滚动查看更多列。

redo

Text
redo() : void

重做，即回退撤销操作。

@note 该方法仅当 disableSerialization 设为 false 时生效。

undo

Text
undo() : void

撤销上一步操作。

@note 该方法仅当 disableSerialization 设为 false 时生效。

setViewMode

Text
setViewMode(viewMode: ViewMode) : void

切换视角模式。

disconnect

Text
disconnect() : Promise<object>

主动断开与互动白板实时房间实例的连接。

兼容入口，委托 leaveRoom() 的异步清理；等待 Promise 成功后再复用或销毁。失败时暂停下一次入房。

insertImage

Text
insertImage(info: ImageInformation) : void

插入图片显示区域。

getRoomState

Text
getRoomState() : Promise<RoomState>

获取房间的所有状态。

getRoomPhase

Text
getRoomPhase() : Promise<RoomPhase>

获取房间的连接状态。

getRoomMembers

Text
getRoomMembers() : Promise<RoomMember[]>

获取房间的用户列表。

@remarks 房间的用户列表仅包含互动模式（具有读写权限）的用户，不包含订阅模式（只读权限）的用户。

@return 用户列表

getMemberState

Text
getMemberState() : Promise<MemberState>

获取房间内白板工具状态。

getGlobalState

Text
getGlobalState() : Promise<GlobalState>

获取房间公共全局状态。

getBroadcastState

Text
getBroadcastState() : Promise<BroadcastState>

获取当前房间视角状态。

getSceneState

Text
getSceneState() : Promise<SceneState>

获取房间当前场景组下的场景状态。

参数

名称描述
promisePromise&lt;SceneState&gt; 接口实例，详见 Promise。你可以通过该接口获取 getSceneState 的调用结果： - 如果方法调用成功，则返回场景状态，详见 SceneState。 - 如果方法调用失败，则返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

@note - 该方法为异步调用。 - 调用以下方法修改或新增场景后，你可以通过 getSceneState 立即获取最新的场景状态。 - setScenePath[1/2] - setScenePath[2/2] - int)

getEntireScenes

Text
getEntireScenes() : Promise<Record<string, Scene[]>>

获取当前房间内所有场景的信息。

参数

名称描述
promisePromise&lt;Map&lt;String, Scene[]&gt;&gt; 接口实例，详见 Promise。你可以通过该接口获取 getEntireScenes 方法的调用结果： - 如果方法调用成功，将返回当前房间内所有场景的信息。 - 如果方法调用失败，将返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

setScenePath

Text
setScenePath(path: string) : Promise<boolean>

切换至指定的场景。 方法调用成功后，房间内的所有用户看到的白板都会切换到指定场景。

setSceneIndex

Text
setSceneIndex(index: number) : Promise<boolean>

切换至当前场景组下的指定场景。

方法调用成功后，房间内的所有用户看到的白板都会切换到指定场景。 指定的场景必须在当前场景组中，否则方法调用会失败。

参数

名称描述
index- 目标场景在当前场景组下的索引号。
表格内容超出当前宽度，可横向滚动查看更多列。

@returns 一个 Promise&lt;boolean&gt;，用于获取 setSceneIndex 的调用结果： - 如果方法调用成功，则返回 true。 - 如果方法调用失败，则抛出错误信息。

putScenes

Text
putScenes(dir: string, scenes: Scene[], index: number) : void

在指定场景组下插入多个场景。

参数

名称描述
dir- 场景组名称，必须以 / 开头。不能为场景路径。
scenes- 由多个场景构成的数组。单个场景的字段详见 Scene。
index- 待插入的多个场景中，第一个场景在该场景组的索引号。 - 如果传入的索引号大于该场景组已有场景总数，新插入的场景会排在现有场景的最后。 - 场景的索引号从 0 开始。
表格内容超出当前宽度，可横向滚动查看更多列。

@remarks 调用该方法插入多个场景后不会切换到新插入的场景。如果要切换至新插入的场景，需要调用 setScenePath。

moveScene

Text
moveScene(srcPath: string, dstPath: string) : void

移动场景。

成功移动场景后，场景路径也会改变。

参数

名称描述
sourcePath- 需要移动的场景原路径。必须为场景路径，不能是场景组的路径。
targetDirOrPath- 目标场景组路径或目标场景路径： - 当 targetDirOrPath 设置为目标场景组路径时，表示将指定场景移至其他场景组中，场景路径会发生改变，但是场景名称不变。 - 当 targetDirOrPath 设置为目标场景路径时，表示改变指定场景在当前场景组的位置，场景路径和场景名称都会发生改变。
表格内容超出当前宽度，可横向滚动查看更多列。

@remarks - 该方法只能移动场景，不能移动场景组，即 sourcePath 只能是场景路径，不能是场景组路径。 - 该方法支持改变指定场景在当前所属场景组下的位置，也支持将指定场景移至其他场景组。

removeScenes

Text
removeScenes(dirOrPath: string) : void

removeScenes：WhiteboardController 的公开成员。参数和返回类型见下方签名。

cleanScene

Text
cleanScene(retainPpt?: boolean) : void

清除当前场景的所有内容。

参数

名称描述
retainPpt是否保留 PPT 内容： - true：保留 PPT。 - false：连 PPT 一起清空。
表格内容超出当前宽度，可横向滚动查看更多列。

refreshViewSize

Text
refreshViewSize() : void

刷新白板的界面。 <p> 当 WhiteboardView 出现改变时，需要手动调用该方法刷新白板的界面。

scalePptToFit

Text
scalePptToFit(mode?: AnimationMode) : void

根据指定的动画模式调整视角，以保证完整显示 PPT 的内容。

参数

名称描述
mode视角调整时的动画模式。
表格内容超出当前宽度，可横向滚动查看更多列。

disableCameraTransform

Text
disableCameraTransform(disable: boolean) : void

禁止/允许用户调整视角。

该方法用于禁止或允许用户通过触屏手势移动或缩放视角。

参数

名称描述
disable是否禁止用户调整视角： - true: 禁止用户调整视角。 - false: (默认) 允许用户调整视角。
表格内容超出当前宽度，可横向滚动查看更多列。

disableDeviceInputs

Text
disableDeviceInputs(disable: boolean) : void

禁止/允许用户操作白板工具。

参数

名称描述
disable是否禁止用户操作白板工具： - true：禁止用户操作白板工具操作。 - false：（默认）允许用户操作白板工具输入操作。
表格内容超出当前宽度，可横向滚动查看更多列。

disableWindowOperation

Text
disableWindowOperation(disable: boolean) : void

多窗口模式下，禁止/允许窗口操作。

参数

名称描述
disable- 是否禁止窗口操作： - true：禁止窗口操作。 - false：（默认）允许窗口操作。
表格内容超出当前宽度，可横向滚动查看更多列。

setContainerSizeRatio

Text
setContainerSizeRatio(ratio: number) : void

设置多窗口显示比例

参数

名称描述
ratio高与宽比例, 初始化默认值 9:16
表格内容超出当前宽度，可横向滚动查看更多列。

setPrefersColorScheme

Text
setPrefersColorScheme(colorScheme: WindowPrefersColorScheme) : void

设置设置暗色模式

参数

名称描述
colorScheme
表格内容超出当前宽度，可横向滚动查看更多列。

addApp

Text
addApp(appParam: WindowAppParam) : Promise<string>

在多窗口模式添加 App，成功返回 appId；创建失败或焦点未提交时 Promise 拒绝。0.2.8 开始等待 setup 并清理半初始化窗口；0.2.9 的 lazy 模式还按焦点协调 setup。成功返回不表示所有资源已渲染完成。originSize 序列化到 attributes.originSize。

fitOriginSizeAndCamera

Text
fitOriginSizeAndCamera() : void

启用 MainView originSize 模式后恢复 MainView 参考尺寸和初始相机状态，不修改 Slide/Presentation 的 App 参考尺寸。

closeApp

Text
closeApp(appId: string) : Promise<boolean>

等待内嵌 Window Manager 完成关闭和后继焦点交接后回调。当前 Native 层收到完成回调后固定返回 true，不提供可靠的 false 业务失败结果；需要结合查询和房间状态处理未收到完成的情况。

focusApp

Text
focusApp(appId: string) : Promise<boolean>

切换 App 焦点。Promise<boolean> 表示房间共享 focus、本地 Box 焦点及 zIndex 是否已提交；false 表示请求被取代或未提交。setup 失败或超时只记录日志，不能用 true 判断课件首帧已就绪。

queryApp

Text
queryApp(appId: string) : Promise<WindowAppSyncAttrs>

查询窗口信息

参数

名称描述
appId
表格内容超出当前宽度，可横向滚动查看更多列。

queryAllApps

Text
queryAllApps() : Promise<Record<string, WindowAppSyncAttrs>>

查询所有窗口信息

addPage

Text
addPage(param: AddPageParam = {}) : void

添加新页面

添加页面之后不自动切换，需要调用setSceneIndex或者 nextPage 切换页面

removePage

Text
removePage(param: RemovePageParam = {}) : void

删除当前场景集指定页面，多窗口下限定为主白板场景集下页面

insertText

Text
insertText(x: number, y: number, text: string) : Promise<string>

在指定位置插入文字。

updateText

Text
updateText(identifier: string, text: string) : void

更新指定文字内容。

dispatchDocsEvent

Text
dispatchDocsEvent(event: WindowDocsEvent) : Promise<DispatchDocsEventResult>

统一控制 MainView、DocsViewer、Slide、Presentation。target 可为 mainView 或具体 appId，省略时跟随焦点；page 从 1 开始，scale=1 表示适配尺寸。返回 DispatchDocsEventResult：accepted=true 仅表示命令接收，不保证画面完成；accepted=false 包含 reason/message。DocsViewer 不支持 scalePage。传输/执行异常进入异步错误路径，实际状态通过统一页状态回调观察。

getPageState

Text
getPageState(options?: WindowPageStateOptions) : Promise<UnifiedPageState>

查询统一页面状态，返回 target、可选 appId、1-based page/pageCount 和可选相对 scale。查询目标用 mainView 或 appId；状态 target 返回 mainView/DocsViewer/Slide/Presentation。

setSyncMode

Text
setSyncMode(useSyncMode: boolean) : void

设置同步模式。

nextPage

Text
nextPage() : Promise<boolean>

切换到下一个页面

prevPage

Text
prevPage() : Promise<boolean>

切换到上一个页面

getLocalLogState

Text
getLocalLogState() : Promise<object>

查询 WebView 内本地日志运行状态，异步返回 JSON 对象。

collectLocalLogs

Text
collectLocalLogs() : Promise<object>

收集本地诊断日志，异步返回 JSON 对象；需要初始化时显式开启本地日志。

flushLocalLogs

Text
flushLocalLogs() : Promise<object>

将 WebView 内本地日志刷新到持久化存储，异步返回 JSON 对象。

uploadLocalLogs

Text
uploadLocalLogs() : Promise<object>

触发本地日志上传；enabled 与 enabledUpload 均需启用，结果通过异步 JSON 和日志状态事件观察。

reloadBackgroundImage

Text
reloadBackgroundImage(params: ReloadBackgroundImageParams) : Promise<ReloadBackgroundImageResult>

重新加载当前聚焦场景此前失败的 Appliance Plugin 背景图。参数包含 source="appliance"、viewId 和可选 scenePath/url；返回 accepted/reloadedCount/可选 reason，accepted 不表示图片已加载成功。需要同时开启 useMultiViews 和 enableAppliancePlugin。

hasBackgroundImage

Text
hasBackgroundImage(params: HasBackgroundImageParams) : Promise<boolean>

按 viewId、scenePath、imageUrl 及 sources 查询 Appliance Plugin 管理的背景图，sources 填写 ["appliance"]，返回布尔值。需要同时开启 useMultiViews 和 enableAppliancePlugin。

公开成员函数

leaveRoom

Text
leaveRoom(): Promise<object>

等待所属 Room 完成清理，重复退出复用清理结果。disconnect() 为兼容入口并委托相同流程；组件绑定/解绑不能替代业务退房完成通知。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利