教具插件介绍与启用

  • HarmonyOS

更新时间

适用于 Whiteboard HarmonyOS SDK 0.2.11,内嵌 Appliance Plugin 1.1.45。本章的 Version 条件指插件版本。

推荐在新接入房间中开启 enableAppliancePlugin,使用内嵌的高性能教具插件。插件负责笔迹绘制、元素选中和编辑、图片交互、文字编辑、撤销重做及多窗口中的教具显示,业务继续使用 SDK 的公开接口。

开启插件

TypeScript
import { WhiteboardOptions, Region } from '@shengwang/whiteboard';

const options: WhiteboardOptions = {
  appIdentifier: 'APP_IDENTIFIER',
  roomUuid: 'ROOM_UUID',
  roomToken: 'ROOM_TOKEN',
  uid: 'CLIENT_UID',
  region: Region.CN_HZ,
  writable: true,
  useMultiViews: true,
  enableAppliancePlugin: true,
  floatBar: true
};

将 options 传给 Whiteboard 组件,在 callbacks.onRoomReady 后使用 WhiteboardController。插件选项通过 WhiteboardOptions.appliancePluginOptions.extras 配置,在创建组件前填写。

当前版本需同时配置 useMultiViews=true 与 enableAppliancePlugin=true。未启用动态配置且本地未设置时,插件开关默认 false;启用动态配置时,未显式配置的字段允许继承远端值。同一房间的互动端和只读显示端应一致启用插件,保证插件内容的同步显示;迁移已有房间时先核对已有内容的显示和编辑效果。

SDK 已内嵌插件和绘制资源,无需在本端工程单独安装 npm 包或配置 Worker URL。插件为白板提供绘制与编辑交互,业务应用仍需提供自己的教具切换按钮。

教具与操作

教具用途主要配置
Pencil自由书写和标注线条颜色、粗细
Selector选中、移动、缩放元素;符合条件的单个图片可使用旋转手柄内置选择框与属性栏
Rectangle / Ellipse / Straight / Arrow绘制矩形、椭圆、直线和箭头线条颜色与粗细
Shape绘制三角形、菱形、五角星和气泡框通过 shapeType 选择图形
Text输入和编辑文字文字颜色、字号、文字编辑器选项
Eraser擦除命中的整个可擦除元素通过 Appliance.ERASER 选择
Pencil Eraser擦除局部笔迹通过本端教具入口选择
Hand / Clicker移动视角、点击课件通过本端教具入口选择
表格内容超出当前宽度,可横向滚动查看更多列。

例如,入房成功后切换铅笔并设置颜色、粗细:

TypeScript
import { Appliance, MemberState } from '@shengwang/whiteboard';

const pencil: MemberState = {
  currentApplianceName: Appliance.PENCIL,
  strokeColor: [32, 102, 255],
  strokeWidth: 4
};
controller.setMemberState(pencil);

复制、删除、撤销和重做仍使用 SDK 的对应公开接口。只读用户用于显示内容,不开放写入或编辑操作。

扩展能力

功能本端接入方式
铅笔、选择、图形、文字、图片及局部笔迹擦除通过本端教具、元素和撤销重做接口操作
背景图加载状态、查询和失败恢复通过本端查询、恢复及加载回调管理插件背景资源
Auto Shape通过业务扩展 MemberState 传递 autoShape 开关,见 Auto Shape 文档
表格内容超出当前宽度,可横向滚动查看更多列。

按需求继续配置

公开方法签名见客户端 API。插件能力和具体接入选项以本章所标版本为准。

动态配置

需要远程调整教具参数时,参见动态配置。本地显式 extras 优先;未提供的字段允许继承远端 appliancePlugin.extras。SDK 内嵌绘制资源,回调继续在本端绑定。