# 加入白板房间 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb/harmonyos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 声网 Whiteboard HarmonyOS SDK 提供 ArkUI 白板组件。通过 `WhiteboardOptions` 初始化并加入房间,使用 `WhiteboardController` 操作房间,使用 `WhiteboardCallbacks` 接收事件。 ## 前提条件 [#前提条件-3] - DevEco Studio、HarmonyOS Stage 模型工程;本版仓库以 HarmonyOS 5.0.0 / API 12 为兼容基线。 - 已[开启互动白板服务](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/setup-and-access/enable-service),获取 AppIdentifier。 - 业务服务端已[创建房间](/zh-CN/api-reference/api-ref/whiteboard/restful/create-room),并下发匹配房间和数据中心的 Room Token。 ## 获取 SDK [#获取-sdk-3] ```shell ohpm install @shengwang/whiteboard@0.2.11 ``` ## 添加权限 [#添加权限-1] 在模块 `module.json5` 的 `module` 中添加网络权限: ```json { "requestPermissions": [ { "name": "ohos.permission.INTERNET" } ] } ``` ## 实现步骤 [#实现步骤-3] ### 1. 创建房间 [#1-创建房间-3] 由业务服务端调用[创建房间](/zh-CN/api-reference/api-ref/whiteboard/restful/create-room),保存返回的房间 UUID 和数据中心。 ### 2. 生成 Room Token [#2-生成-room-token-3] 由业务服务端[生成 Room Token](/zh-CN/api-reference/api-ref/whiteboard/restful/generate-room-token),将房间 UUID、Room Token 和用户 uid 下发给客户端。SDK Token 保存在服务端。 ### 3. 准备控制器和回调 [#3-准备控制器和回调] 创建 `WhiteboardController` 和 `WhiteboardCallbacks`,在组件显示前设置回调。`onRoomReady` 表示已成功入房,之后可调用房间与 App 接口。以下完整示例包含这两个对象。 ### 4. 创建组件并加入房间 [#4-创建组件并加入房间] ```typescript import { Whiteboard, WhiteboardOptions, WhiteboardController, WhiteboardCallbacks, Region, SDKError, WindowParams } from '@shengwang/whiteboard'; @Entry @Component struct WhiteboardPage { private controller: WhiteboardController = new WhiteboardController(); private callbacks: WhiteboardCallbacks = new WhiteboardCallbacks(); private options: WhiteboardOptions = { appIdentifier: 'APP_IDENTIFIER', roomUuid: 'ROOM_UUID', roomToken: 'ROOM_TOKEN', uid: 'CLIENT_UID', region: Region.CN_HZ, writable: true, useMultiViews: true, windowParams: new WindowParams(), enableAppliancePlugin: true }; aboutToAppear(): void { this.callbacks.setOnRoomReady(() => { // 已加入房间,可开始使用 controller 操作白板。 }); this.callbacks.sdkSetupFail = (error: SDKError) => { console.error(error.message); // 业务侧重新创建组件,完成 SDK 初始化和重新入房。 }; this.callbacks.setOnRoomPhaseChanged((phase) => { console.info(`room phase: ${phase}`); }); } build() { Column() { Whiteboard({ options: this.options, controller: this.controller, callbacks: this.callbacks, webDebug: false }).width('100%').height('100%'); }.width('100%').height('100%'); } } ``` `appIdentifier`、`roomUuid`、`roomToken`、`uid`、`region` 为必填字段。`region` 必须与创建房间的服务区域一致,`writable` 未传时映射为 true,`useMultiViews/userCursor/enableAppliancePlugin` 未显式提供时允许继承动态配置;未启用动态配置时使用内建默认。 必须把回调对象传给组件的 `callbacks` 参数;本版组件实际使用此参数,不能只填写 `options.callbacks`。组件加载后自动初始化 SDK 并入房,本版没有业务调用的 `joinRoom()` 方法。等待 `onRoomReady` 后再操作房间。 ### 5. 接入多窗口 [#5-接入多窗口-3] Window Manager 已通过内嵌 Bridge 集成。组件创建前设置 `WhiteboardOptions.useMultiViews=true`,窗口显示参数放在 `windowParams`。步骤 4 的示例已包含这两项: ```typescript // 在组件创建前配置,随后通过 Whiteboard 的 options 参数传入。 this.options.useMultiViews = true; const windowParams = new WindowParams(); windowParams.setContainerSizeRatio(9 / 16); this.options.windowParams = windowParams; ``` 组件初始化并入房后自动挂载窗口管理器,业务通过 Controller 调用 App 和页面接口。详细配置见[多窗口与统一课件控制](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/unified-page-control)。 ### 6. 接入动态 PPT [#6-接入动态-ppt-3] 内嵌 Bridge 已注册 app-slide。业务服务端完成转换后,在 `onRoomReady` 回调之后,通过 `controller.addApp` 创建动态 PPT 窗口: ```typescript import { WindowAppParam } from '@shengwang/whiteboard'; // 放在 WhiteboardPage 的业务方法中;入房成功后由按钮调用。 async openDynamicPpt(): Promise { const slide: WindowAppParam = { kind: 'Slide', options: { title: '教学课件.pptx', scenePath: '/slides/lesson-1' }, attributes: { taskId: 'CONVERSION_TASK_UUID', url: 'https://convertcdn.netless.link/dynamicConvert' } }; try { const appId = await this.controller.addApp(slide); console.info(`动态 PPT 窗口 ID:${appId}`); } catch (error) { console.error(`创建课件窗口失败:${error}`); } } ``` `taskId` 使用已完成转换的任务 UUID,`url` 是资源地址前缀(末尾不带 `/`,不是 PPT 源文件地址)。`options.scenePath` 必须是以 `/` 开头的场景目录,同一房间内每个 App 使用不同目录。创建 App 需要可写权限;房间中已存在的课件会同步显示,不要在每次入房时重复插入。返回 ID 不表示课件资源与首帧全部加载完成。课件操作见[新版 API 与多窗口课件控制](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/unified-page-control)。 ### 7. 开启新教具 [#7-开启新教具-3] 创建组件前同时启用多 View 与教具插件;步骤 4 的示例已开启: ```typescript this.options.useMultiViews = true; this.options.enableAppliancePlugin = true; ``` SDK 已内嵌 Appliance Plugin 和 Worker,业务继续使用 Controller 的原生方法设置 Pencil、Selector、Eraser、Shape、Text 等教具,同一房间各端应一致开启。入房前的插件参数放在 `WhiteboardOptions.appliancePluginOptions`,自定义教具、背景图和 Auto Shape 见[教具插件介绍与启用](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/overview)。 上述开关在组件初始化前配置;已入房后修改 options 不用于动态开启插件。 ## 离开房间 [#离开房间] 在组件仍然挂载时调用并等待 `controller.disconnect()`,完成后再隐藏或销毁白板组件。组件消失时会解除 Controller 与 Bridge 的绑定。异步接口应处理 Promise rejection。 ## 后续功能 [#后续功能] - [白板工具与房间状态](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/manage-whiteboard/use-tools-wb) - [多窗口和统一课件控制](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/unified-page-control) - [本地日志](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/local-log) - [教具插件介绍与启用](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/overview) - [背景图加载与恢复](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/background-image-recovery) - [客户端 API](/zh-CN/api-reference/whiteboard/whiteboard-sdk/harmonyos/overview) 0.2.11 没有公开的回放 Player、SyncedStore 或自定义 App 注册入口。业务应依据 Harmony 实际公开接口集成。 ## 等待退出完成 [#等待退出完成-1] 调用 `await controller.leaveRoom()` 等待所属房间清理;`disconnect()` 保留为兼容入口并委托相同退出流程。重复退出复用清理结果。退出失败时先处理错误,避免立刻发起下一次入房;组件解绑不能当作房间已经退出的通知。动态配置接入和缺省规则见[动态配置](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/dynamic-config)。