加入白板房间

  • HarmonyOS

更新时间

了解如何快速接入互动白板 SDK,完成环境准备、参数配置、示例运行和核心流程验证。

声网 Whiteboard HarmonyOS SDK 提供 ArkUI 白板组件。通过 WhiteboardOptions 初始化并加入房间,使用 WhiteboardController 操作房间,使用 WhiteboardCallbacks 接收事件。

前提条件

  • DevEco Studio、HarmonyOS Stage 模型工程;本版仓库以 HarmonyOS 5.0.0 / API 12 为兼容基线。
  • 已开启互动白板服务,获取 AppIdentifier。
  • 业务服务端已创建房间,并下发匹配房间和数据中心的 Room Token。

获取 SDK

Shell
ohpm install @shengwang/whiteboard@0.2.11

添加权限

在模块 module.json5 的 module 中添加网络权限:

JSON
{
  "requestPermissions": [
    { "name": "ohos.permission.INTERNET" }
  ]
}

实现步骤

1. 创建房间

由业务服务端调用创建房间,保存返回的房间 UUID 和数据中心。

2. 生成 Room Token

由业务服务端生成 Room Token,将房间 UUID、Room Token 和用户 uid 下发给客户端。SDK Token 保存在服务端。

3. 准备控制器和回调

创建 WhiteboardController 和 WhiteboardCallbacks,在组件显示前设置回调。onRoomReady 表示已成功入房,之后可调用房间与 App 接口。以下完整示例包含这两个对象。

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. 接入多窗口

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 和页面接口。详细配置见多窗口与统一课件控制。

6. 接入动态 PPT

内嵌 Bridge 已注册 app-slide。业务服务端完成转换后,在 onRoomReady 回调之后,通过 controller.addApp 创建动态 PPT 窗口:

TypeScript
import { WindowAppParam } from '@shengwang/whiteboard';

// 放在 WhiteboardPage 的业务方法中;入房成功后由按钮调用。
async openDynamicPpt(): Promise<void> {
  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 与多窗口课件控制。

7. 开启新教具

创建组件前同时启用多 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 见教具插件介绍与启用。

上述开关在组件初始化前配置;已入房后修改 options 不用于动态开启插件。

离开房间

在组件仍然挂载时调用并等待 controller.disconnect(),完成后再隐藏或销毁白板组件。组件消失时会解除 Controller 与 Bridge 的绑定。异步接口应处理 Promise rejection。

后续功能

0.2.11 没有公开的回放 Player、SyncedStore 或自定义 App 注册入口。业务应依据 Harmony 实际公开接口集成。

等待退出完成

调用 await controller.leaveRoom() 等待所属房间清理;disconnect() 保留为兼容入口并委托相同退出流程。重复退出复用清理结果。退出失败时先处理错误,避免立刻发起下一次入房;组件解绑不能当作房间已经退出的通知。动态配置接入和缺省规则见动态配置。