教具插件介绍与启用

适用于 Appliance Plugin 1.1.45。插件负责教具绘制、选中、文字编辑、撤销重做及多窗口 View 绑定。

安装和 Worker 资源

Shell

npm install white-web-sdk@2.16.59 @netless/window-manager@1.0.25 @netless/appliance-plugin@1.1.45

将同一插件版本的 dist/fullWorker.js、dist/subWorker.js 复制到站点静态资源目录 /appliance-1.1.45/，确保以 JavaScript MIME 返回，并按站点 CSP 允许 Worker 加载。两份 Worker 与主线程插件必须来自同一版本。

Shell

mkdir -p public/appliance-1.1.45
cp node_modules/@netless/appliance-plugin/dist/fullWorker.js public/appliance-1.1.45/
cp node_modules/@netless/appliance-plugin/dist/subWorker.js public/appliance-1.1.45/

启用插件

TypeScript

import { WhiteWebSdk, type InvisiblePluginClass } from 'white-web-sdk';
import { WindowManager } from '@netless/window-manager';
import { ApplianceMultiPlugin } from '@netless/appliance-plugin';
import '@netless/window-manager/dist/style.css';
import '@netless/appliance-plugin/dist/style.css';

const sdk = new WhiteWebSdk({ appIdentifier, region: 'cn-hz', useMobXState: true });
const room = await sdk.joinRoom({
  uuid, roomToken, uid, region: 'cn-hz',
  useMultiViews: true,
  disableMagixEventDispatchLimit: true,
  invisiblePlugins: [WindowManager as unknown as InvisiblePluginClass<string, object, object>, ApplianceMultiPlugin]
});
const manager = await WindowManager.mount({
  room, container, cursor: true, supportAppliancePlugin: true
});
const plugin = await ApplianceMultiPlugin.getInstance(manager, {
  options: {
    cdn: {
      fullWorkerUrl: '/appliance-1.1.45/fullWorker.js',
      subWorkerUrl: '/appliance-1.1.45/subWorker.js'
    },
    extras: { useBackgroundThread: true }
  },
  callbacks: {
    onInitLoadingChange: info => console.log(info),
    onBackgroundImageLoadEvent: event => console.log(event)
  }
});

Web 多窗口通过注册 ApplianceMultiPlugin、设置 supportAppliancePlugin 和创建插件实例启用教具插件。应用与这些插件使用同一份 white-web-sdk。

先 mount 主 View，再初始化插件。离开页面时先解除业务监听，等待 plugin.destroy()，再等待 manager.destroy()、room.disconnect()；若使用 Blob Worker URL，完成销毁后再 revoke URL。插件初始化返回不表示每个 App 的所有资源和首帧均已完成。

教具与操作

教具	用途
Selector	框选、移动、缩放和旋转可编辑元素
Pencil	自由书写，可设置颜色、粗细、线型与透明度
Eraser	整元素擦除
Pencil Eraser	局部笔迹擦除
Shape	直线、箭头、矩形、椭圆、三角形、菱形、多边形与星形
Text	文字输入、排版和样式设置
Hand	移动视角

同一房间各端应一致开启插件；建议先在测试房间验证已有笔迹的显示、编辑与撤销重做。操作类 API 需要可写权限，教具配置应在入房和初始化完成后使用。

扩展能力

功能	接入入口
背景图	背景图加载与恢复
Selector、Pencil、Shape 与 extras	自定义教具与样式
小地图、Auto Shape、过滤笔记	扩展功能
PublicListener、元素查询、Selector 事件	事件监听与元素查询

动态配置

需要远程调整教具参数时，参见动态配置。本地显式 extras 优先；未提供的字段允许继承远端 appliancePlugin.extras。DOM 容器、回调函数和 Worker 资源地址仍由本地接入提供。