# 统一页面控制 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/unified-page-control/harmonyos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 适用于 **Whiteboard HarmonyOS SDK 0.2.11**。 多窗口模式通过同一套接口控制主白板和课件。先完成[加入白板房间](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb),并等待入房成功;业务发起翻页、缩放以及新增或移除主白板页面还需要可写权限。 ## 目标与操作 [#目标与操作-3] | 目标 | `target` 输入 | 支持操作 | | --- | --- | --- | | MainView 主白板 | `mainView` | 前后页、跳页、缩放;[新增、移除页面](#mainview-add-remove)使用独立 API;不支持动画步骤 | | Slide 动态 PPT | 该窗口的 appId | 前后页、跳页、前后动画步骤、缩放(先启用 Slide 的 enableScale) | | Presentation 静态 PPT | 该窗口的 appId | 前后页、跳页、缩放;不支持动画步骤 | | DocsViewer 文档 | 该窗口的 appId | 前后页、跳页;不支持 scalePage | 省略 target 时跟随当前焦点,没有焦点时使用 MainView。不能把 `Slide` 或 `Presentation` 类型名当作 appId。查询结果的 target 则是 `mainView`、`Slide`、`Presentation`、`DocsViewer` 之一,用于标识目标类型。 下表列出 `dispatchDocsEvent` 支持的命令;新增和移除页面使用下文的独立 API。 | 命令 | 用途与参数 | | --- | --- | | prevPage / nextPage | 前一页 / 后一页 | | prevStep / nextStep | 前一动画步骤 / 后一动画步骤 | | jumpToPage | page 为从 1 开始的整数,不能直接使用零基场景索引 | | scalePage | scale 为相对适配倍率,1 表示适配大小;可选范围由 pageScaleRange 约束 | ## 新增与移除主白板页面 [#新增与移除主白板页面-3] 以下公开 API 固定操作 MainView 主白板的场景页,不受当前焦点或 `target` 影响,也不用于增加或删除课件源文件中的页面。先完成多窗口入房并取得可写权限。`dispatchDocsEvent` 不接受 `addPage`、`removePage` 命令。 通过入房成功后的 `WhiteboardController controller` 调用。参数类型均从 `@shengwang/whiteboard` 包入口导出。 | 操作 | `WhiteboardController` 公开 API | 参数与结果 | | --- | --- | --- | | 新增页面 | `addPage(param: AddPageParam = {}): void` | `after: true` 插到主白板当前页之后;省略或为 `false` 时追加到末尾。`scene` 可选,省略时新增空白页 | | 移除页面 | `removePage(param: RemovePageParam = {}): void` | 省略 `index` 删除主白板当前页;`index` 从 0 开始,指定待删除页 | ```typescript import { AddPageParam, RemovePageParam } from '@shengwang/whiteboard'; // 新增按钮:在主白板当前页之后插入空白页。 const addParam: AddPageParam = { after: true }; controller.addPage(addParam); // 删除按钮:删除主白板第一页;controller.removePage() 删除当前页。 const removeParam: RemovePageParam = { index: 0 }; controller.removePage(removeParam); ``` 0.2.11 的这两个方法均无完成回调,也不返回 Promise 或布尔结果。调用返回不表示新增或删除成功,请结合本页的主白板状态查询与 `unifiedPageStateChange` 观察实际页数变化。 新增页面后不会自动跳到新页,需要时再发送指定 `target: "mainView"` 的跳页命令。主白板至少保留一页;仅剩一页时不能删除。 **索引区别:** 删除 API 的 `index` 从 **0** 开始,`index = 0` 表示第一页;`dispatchDocsEvent("jumpToPage", ...)` 的 `page` 从 **1** 开始。传入待删除页索引前,请确认主白板的实际页数。 ## 发送命令与主动查询 [#发送命令与主动查询-3] ```typescript import { DispatchDocsEventRejectedResult } from '@shengwang/whiteboard'; // controller 已在 onRoomReady 后可用。 const result = await controller.dispatchDocsEvent({ event: 'jumpToPage', options: { target: appId, page: 2 } }); if (!result.accepted) { const rejected = result as DispatchDocsEventRejectedResult; console.warn(rejected.reason, rejected.message); } try { const state = await controller.getPageState({ target: appId }); console.info(state.page, state.pageCount, state.scale); } catch (error) { console.warn('当前状态尚不可用'); } ``` `dispatchDocsEvent` 的 accepted 只表示命令被接收;accepted=false 时读取 reason/message。Bridge 或宿主异常走 Promise 拒绝或原生错误回调。原因码包括 invalidEvent、invalidOptions、targetNotFound、targetNotSupported、eventNotSupported、notWritable、stateUnavailable、outOfRange、commandFailed。 `getPageState` 主动查询可观察的状态,不会触发翻页。返回 page/pageCount(从 1 开始)、target、可选 appId 与 scale。尚未完成初始化或状态确认时可能失败;可等待状态事件后再次查询,或设置有限重试次数与截止时间。 ## 监听实际页码与缩放 [#监听实际页码与缩放-3] ```typescript const callbacks = new WhiteboardCallbacks() .setOnUnifiedPageStateChange(state => { if (state.status === 'failure') { console.warn(state.reason, state.message); return; } console.info(state.changeType, state.page, state.scale); }); // 将 callbacks 传给本次 WhiteboardOptions;在页面退出后停止向页面提交状态。 ``` 观察事件的 status 为 pending/success;`changeType: page` 表示页变化,`changeType: scale` 表示缩放变化;旧兼容事件可能省略 changeType。异步执行失败时 status=failure,并包含 event、reason 和可选 message。不要从失败事件读取有效页码/倍率。 主动读取倍率使用 `getPageState` 返回的 scale;该值可能不存在,且它不是主白板相机的绝对 camera.scale。命令接收、焦点提交和页状态通知都不能代替课件全部资源或首帧完成信号。 ## 与 WindowManager 示例的对应关系 [#与-windowmanager-示例的对应关系-3] WindowManager example 中 `dispatchUnifiedDocsEvent` 包装正式 `dispatchDocsEvent`,`queryUnifiedPageState` 包装正式 `getPageState`。`scaleChangeEvent` 是示例保存缩放通知的 UI 状态变量,来自 unifiedPageStateChange 中 changeType=scale 的消息。这三个示例名称均不是可从 SDK 导入的独立方法或事件。 需要统一主白板与课件的书写参考尺寸时,继续阅读[统一笔记](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/unified-notes)。