WhiteboardController class 参考

适用版本：@shengwang/whiteboard 0.2.11。

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

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

类型结构（源码声明）

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

export class WhiteboardController

setInitialWritable	setInitialWritable(writable: boolean) : void
attachWhiteboard	attachWhiteboard = (whiteboard: DsBridge) => boolean
detachWhiteboard	detachWhiteboard = (whiteboard: DsBridge) => void
setWritable	setWritable(writable: boolean) : Promise<boolean>
getWritable	getWritable() : boolean
setAppliance	setAppliance(appliance: Appliance, shapeType?: ShapeType) : void
setStrokeColor	setStrokeColor(color: ResourceColor) : void
setStrokeWidth	setStrokeWidth(width: number) : void
setTextSize	setTextSize(size: number) : void
setTextColor	setTextColor(color: ResourceColor) : void
setMemberState	setMemberState(state: MemberState) : void
copy	copy() : void
paste	paste() : void
duplicate	duplicate() : void
deleteOperation	deleteOperation() : void
disableSerialization	disableSerialization(disable: boolean) : void
redo	redo() : void
undo	undo() : void
setViewMode	setViewMode(viewMode: ViewMode) : void
disconnect	disconnect() : Promise<object>
insertImage	insertImage(info: ImageInformation) : void
getRoomState	getRoomState() : Promise<RoomState>
getRoomPhase	getRoomPhase() : Promise<RoomPhase>
getRoomMembers	getRoomMembers() : Promise<RoomMember[]>
getMemberState	getMemberState() : Promise<MemberState>
getGlobalState	getGlobalState() : Promise<GlobalState>
getBroadcastState	getBroadcastState() : Promise<BroadcastState>
getSceneState	getSceneState() : Promise<SceneState>
getEntireScenes	getEntireScenes() : Promise<Record<string, Scene[]>>
setScenePath	setScenePath(path: string) : Promise<boolean>
setSceneIndex	setSceneIndex(index: number) : Promise<boolean>
putScenes	putScenes(dir: string, scenes: Scene[], index: number) : void
moveScene	moveScene(srcPath: string, dstPath: string) : void
removeScenes	removeScenes(dirOrPath: string) : void
cleanScene	cleanScene(retainPpt?: boolean) : void
refreshViewSize	refreshViewSize() : void
scalePptToFit	scalePptToFit(mode?: AnimationMode) : void
disableCameraTransform	disableCameraTransform(disable: boolean) : void
disableDeviceInputs	disableDeviceInputs(disable: boolean) : void
disableWindowOperation	disableWindowOperation(disable: boolean) : void
setContainerSizeRatio	setContainerSizeRatio(ratio: number) : void
setPrefersColorScheme	setPrefersColorScheme(colorScheme: WindowPrefersColorScheme) : void
addApp	addApp(appParam: WindowAppParam) : Promise<string>
fitOriginSizeAndCamera	fitOriginSizeAndCamera() : void
closeApp	closeApp(appId: string) : Promise<boolean>
focusApp	focusApp(appId: string) : Promise<boolean>
queryApp	queryApp(appId: string) : Promise<WindowAppSyncAttrs>
queryAllApps	queryAllApps() : Promise<Record<string, WindowAppSyncAttrs>>
addPage	addPage(param: AddPageParam = {}) : void
removePage	removePage(param: RemovePageParam = {}) : void
insertText	insertText(x: number, y: number, text: string) : Promise<string>
updateText	updateText(identifier: string, text: string) : void
dispatchDocsEvent	dispatchDocsEvent(event: WindowDocsEvent) : Promise<DispatchDocsEventResult>
getPageState	getPageState(options?: WindowPageStateOptions) : Promise<UnifiedPageState>
setSyncMode	setSyncMode(useSyncMode: boolean) : void
nextPage	nextPage() : Promise<boolean>
prevPage	prevPage() : Promise<boolean>
getLocalLogState	getLocalLogState() : Promise<object>
collectLocalLogs	collectLocalLogs() : Promise<object>
flushLocalLogs	flushLocalLogs() : Promise<object>
uploadLocalLogs	uploadLocalLogs() : Promise<object>
reloadBackgroundImage	reloadBackgroundImage(params: ReloadBackgroundImageParams) : Promise<ReloadBackgroundImageResult>
hasBackgroundImage	hasBackgroundImage(params: HasBackgroundImageParams) : Promise<boolean>
leaveRoom	leaveRoom(): Promise<object>

函数说明

setInitialWritable

setInitialWritable(writable: boolean) : void

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

attachWhiteboard

attachWhiteboard = (whiteboard: DsBridge) => boolean

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

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

detachWhiteboard

detachWhiteboard = (whiteboard: DsBridge) => void

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

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

setWritable

setWritable(writable: boolean) : Promise<boolean>

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

参数

名称	描述
writable	用户在房间中是否为互动模式： - true：互动模式，即具有读写权限。 - false：订阅模式，即具有只读权限。

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

getWritable

getWritable() : boolean

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

setAppliance

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

设置教具类型

参数

名称	描述
appliance	教具类型
shapeType	形状

setStrokeColor

setStrokeColor(color: ResourceColor) : void

设置画笔颜色

参数

名称	描述
color

setStrokeWidth

setStrokeWidth(width: number) : void

设置画笔粗细

参数

名称	描述
width

setTextSize

setTextSize(size: number) : void

设置字大小

参数

名称	描述
size

setTextColor

setTextColor(color: ResourceColor) : void

设置字颜色

参数

名称	描述
color

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

setMemberState

setMemberState(state: MemberState) : void

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

copy

copy() : void

复制选中内容。

paste

paste() : void

粘贴复制的内容。

duplicate

duplicate() : void

复制并粘贴选中的内容。

deleteOperation

deleteOperation() : void

删除选中的内容。

disableSerialization

disableSerialization(disable: boolean) : void

开启/禁止本地序列化。

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

参数

名称	描述
disable	默认为 true

redo

redo() : void

重做，即回退撤销操作。

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

undo

undo() : void

撤销上一步操作。

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

setViewMode

setViewMode(viewMode: ViewMode) : void

切换视角模式。

disconnect

disconnect() : Promise<object>

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

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

insertImage

insertImage(info: ImageInformation) : void

插入图片显示区域。

getRoomState

getRoomState() : Promise<RoomState>

获取房间的所有状态。

getRoomPhase

getRoomPhase() : Promise<RoomPhase>

获取房间的连接状态。

getRoomMembers

getRoomMembers() : Promise<RoomMember[]>

获取房间的用户列表。

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

@return 用户列表

getMemberState

getMemberState() : Promise<MemberState>

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

getGlobalState

getGlobalState() : Promise<GlobalState>

获取房间公共全局状态。

getBroadcastState

getBroadcastState() : Promise<BroadcastState>

获取当前房间视角状态。

getSceneState

getSceneState() : Promise<SceneState>

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

参数

名称	描述
promise	Promise<SceneState> 接口实例，详见 Promise。你可以通过该接口获取 getSceneState 的调用结果： - 如果方法调用成功，则返回场景状态，详见 SceneState。 - 如果方法调用失败，则返回错误信息。

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

getEntireScenes

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

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

参数

名称	描述
promise	Promise<Map<String, Scene[]>> 接口实例，详见 Promise。你可以通过该接口获取 getEntireScenes 方法的调用结果： - 如果方法调用成功，将返回当前房间内所有场景的信息。 - 如果方法调用失败，将返回错误信息。

setScenePath

setScenePath(path: string) : Promise<boolean>

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

setSceneIndex

setSceneIndex(index: number) : Promise<boolean>

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

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

参数

名称	描述
index	- 目标场景在当前场景组下的索引号。

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

putScenes

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

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

参数

名称	描述
dir	- 场景组名称，必须以 / 开头。不能为场景路径。
scenes	- 由多个场景构成的数组。单个场景的字段详见 Scene。
index	- 待插入的多个场景中，第一个场景在该场景组的索引号。 - 如果传入的索引号大于该场景组已有场景总数，新插入的场景会排在现有场景的最后。 - 场景的索引号从 0 开始。

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

moveScene

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

移动场景。

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

参数

名称	描述
sourcePath	- 需要移动的场景原路径。必须为场景路径，不能是场景组的路径。
targetDirOrPath	- 目标场景组路径或目标场景路径： - 当 targetDirOrPath 设置为目标场景组路径时，表示将指定场景移至其他场景组中，场景路径会发生改变，但是场景名称不变。 - 当 targetDirOrPath 设置为目标场景路径时，表示改变指定场景在当前场景组的位置，场景路径和场景名称都会发生改变。

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

removeScenes

removeScenes(dirOrPath: string) : void

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

cleanScene

cleanScene(retainPpt?: boolean) : void

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

参数

名称	描述
retainPpt	是否保留 PPT 内容： - true：保留 PPT。 - false：连 PPT 一起清空。

refreshViewSize

refreshViewSize() : void

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

scalePptToFit

scalePptToFit(mode?: AnimationMode) : void

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

参数

名称	描述
mode	视角调整时的动画模式。

disableCameraTransform

disableCameraTransform(disable: boolean) : void

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

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

参数

名称	描述
disable	是否禁止用户调整视角： - true: 禁止用户调整视角。 - false: (默认) 允许用户调整视角。

disableDeviceInputs

disableDeviceInputs(disable: boolean) : void

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

参数

名称	描述
disable	是否禁止用户操作白板工具： - true：禁止用户操作白板工具操作。 - false：（默认）允许用户操作白板工具输入操作。

disableWindowOperation

disableWindowOperation(disable: boolean) : void

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

参数

名称	描述
disable	- 是否禁止窗口操作： - true：禁止窗口操作。 - false：（默认）允许窗口操作。

setContainerSizeRatio

setContainerSizeRatio(ratio: number) : void

设置多窗口显示比例

参数

名称	描述
ratio	高与宽比例, 初始化默认值 9:16

setPrefersColorScheme

setPrefersColorScheme(colorScheme: WindowPrefersColorScheme) : void

设置设置暗色模式

参数

名称	描述
colorScheme

addApp

addApp(appParam: WindowAppParam) : Promise<string>

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

fitOriginSizeAndCamera

fitOriginSizeAndCamera() : void

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

closeApp

closeApp(appId: string) : Promise<boolean>

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

focusApp

focusApp(appId: string) : Promise<boolean>

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

queryApp

queryApp(appId: string) : Promise<WindowAppSyncAttrs>

查询窗口信息

参数

名称	描述
appId

queryAllApps

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

查询所有窗口信息

addPage

addPage(param: AddPageParam = {}) : void

添加新页面

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

removePage

removePage(param: RemovePageParam = {}) : void

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

insertText

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

在指定位置插入文字。

updateText

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

更新指定文字内容。

dispatchDocsEvent

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

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

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

setSyncMode

setSyncMode(useSyncMode: boolean) : void

设置同步模式。

nextPage

nextPage() : Promise<boolean>

切换到下一个页面

prevPage

prevPage() : Promise<boolean>

切换到上一个页面

getLocalLogState

getLocalLogState() : Promise<object>

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

collectLocalLogs

collectLocalLogs() : Promise<object>

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

flushLocalLogs

flushLocalLogs() : Promise<object>

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

uploadLocalLogs

uploadLocalLogs() : Promise<object>

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

reloadBackgroundImage

reloadBackgroundImage(params: ReloadBackgroundImageParams) : Promise<ReloadBackgroundImageResult>

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

hasBackgroundImage

hasBackgroundImage(params: HasBackgroundImageParams) : Promise<boolean>

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

公开成员函数

leaveRoom

leaveRoom(): Promise<object>

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