@netless/appliance-plugin 1.1.36-beta.2 → 1.1.36-beta.3

package/READMA.zh-CN.md

@@ -317,20 +317,26 @@ injectMethodToObject(windowmanager.mainView,'setMemberState');
 
 6. Selector / Element 扩展接口
 - `getSelectedElements(viewId?)` - 获取当前 selector 选中快照
+- `isElementPropertySupported(toolsType, field)` - 判断指定教具类型是否支持某个属性字段，适合自定义 floatbar 按钮显隐
 - `blurSelector(viewId?)` - 取消当前 selector 选中
 - `updateSelectedElements(viewId?, changes)` - 更新当前 selector 选中集的属性
 - `copySelectedElements(viewId?)` - 复制当前 selector 选中集
 - `deleteSelectedElements(viewId?)` - 删除当前 selector 选中集
 - `updateElement(elementId, scenePath, viewId, updateElementInfo, useUndoRedoStack?)` - 单元素最终态更新接口，返回 `Promise<boolean>`
+- `getFloatbarContainer(viewId?)` - 获取当前 view 内置的自定义 floatbar 挂载容器
+- `getViewOffsetToContainer(container, viewId?)` - 计算当前 view 到外部容器的坐标偏移，用于挂载到业务 overlay root
 
 其中需要注意：
 
 - `updateSelectedElements(...)` 是 selector-only 能力，只处理当前选中的 selector 集合
+- `blurSelector(...)`、`updateSelectedElements(...)`、`copySelectedElements(...)`、`deleteSelectedElements(...)`、`updateElement(...)` 都要求在可写权限下调用
 - `updateElement(...)` 是 storage-first 的单元素最终态更新通知接口
 - `updateElement(...)` 不表达调用返回时已经渲染完成
 - `updateElement(...)` 不支持 selector
 - `updateElementInfo` 需要显式携带 `toolsType`，并按教具类型声明对应字段
 - `updateElement(...)` 返回 `Promise<boolean>`，仅表示本次调用是否通过基础校验并成功发起
+- `getFloatbarContainer(...)` 是推荐的自定义 floatbar 挂载方式；挂到该容器下时，`selectorGeometryChange.viewRect` 可直接用于定位
+- 如果业务必须挂到外部容器，请配合 `getViewOffsetToContainer(...)` 做坐标换算
 
 7. Selector 扩展事件
 - `selectedElementsChange`
@@ -345,7 +351,14 @@ injectMethodToObject(windowmanager.mainView,'setMemberState');
 - `remoteSelectorChange`
   - 表示远端 / 被同步端 selector 的同步结果变化
 
-5. 不兼容接口
+8. Selector / Floatbar 自定义能力
+- 支持关闭内置 floatbar，仅保留 selector 选中、拖拽、缩放、旋转等交互能力
+- 支持基于 `selectedElementsChange`、`selectorGeometryChange`、`selectorTransformChange`、`remoteSelectorChange` 事件渲染业务自定义 UI
+- 支持通过 `overwriteSelectorStyles` 覆盖 selector 外框、控制点、端点和锁态图标样式
+- 支持将自定义 floatbar 挂到 plugin 内部容器，或挂到业务自己的外部 overlay 容器
+- 推荐结合 [customer-custom-selector-floatbar-integration.zh-CN.md](https://github.com/user-attachments/files/29439912/customer-custom-selector-floatbar-integration.zh-CN.md) 接入
+
+9. 不兼容接口
 - [`exportScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#exportScene) - appliance-plugin 开启后，笔记不能按 room 的方式导出
 - [服务端截图](https://doc.shengwang.cn/doc/whiteboard/restful/fastboard-sdk/restful-wb/operations/post-v5-rooms-uuid-screenshots) - appliance-plugin 开启后，笔记不能通过调用服务端截图方式获取截图，而需要改用 `screenshotToCanvasAsync` 获取
 
@@ -387,6 +400,41 @@ room.setMemberState({
 - 闭合绘制矩形、圆/椭圆、三角形、五角星
 - 箭头和直线保持单笔非闭合
 
+##### 自定义 Selector / Floatbar 与 Selector 扩展 API (Version >=1.1.36-beta.2)
+
+当前版本新增了一套围绕 selector 的事件与命令式 API，方便业务在 `white-web-sdk` / `@netless/window-manager` 场景下自定义 selector UI、floatbar UI 和选中属性面板。
+
+新增事件：
+
+- `selectedElementsChange` - 只表示最终选中集合变化
+- `selectorGeometryChange` - 只表示最终几何结果变化，坐标统一输出 `viewRect`
+- `selectorTransformChange` - 只表示拖拽、拉伸、旋转、端点编辑等过程态
+- `remoteSelectorChange` - 表示远端 / 被同步端 selector 的同步结果变化
+
+新增 API：
+
+- `getSelectedElements(viewId?)`
+- `isElementPropertySupported(toolsType, field)`
+- `blurSelector(viewId?)`
+- `updateSelectedElements(viewId?, changes)`
+- `copySelectedElements(viewId?)`
+- `deleteSelectedElements(viewId?)`
+- `updateElement(elementId, scenePath, viewId, updateElementInfo, useUndoRedoStack?)`
+- `getFloatbarContainer(viewId?)`
+- `getViewOffsetToContainer(container, viewId?)`
+
+典型用途：
+
+- 关闭内置 floatbar，自己渲染按钮、色板、字号和文本样式 UI
+- 通过 `getSelectedElements()` 获取当前选中快照
+- 通过 `updateSelectedElements()` 批量更新当前选中元素属性
+- 通过 `updateElement()` 更新某个非当前选中的单元素
+- 通过 `getFloatbarContainer()` 或 `getViewOffsetToContainer()` 决定自定义 floatbar 挂载位置
+- 通过 `overwriteSelectorStyles` 统一覆盖 selector 视觉样式
+
+详细设计与接入示例请参考：
+- [customer-custom-selector-floatbar-integration.zh-CN.md](https://github.com/user-attachments/files/29439912/customer-custom-selector-floatbar-integration.zh-CN.md)
+
 ##### 扩展教具 (Version >=1.1.1)
 在原来的[白板教具](https://doc.shengwang.cn/api-ref/whiteboard/javascript/globals.html#memberstate)类型上,增加了一些扩展功能属性,如下:
 

package/README.md

@@ -307,7 +307,51 @@ The following interfaces are involved:
 - `updateMarkmap` - Update markdown text in whiteboard (Version >=1.1.32) **This method requires enabling extras.useBackgroundThread**
 - `insertBackgroundImage` - Insert whiteboard background image (Version >=1.1.32) **This method requires enabling extras.useBackgroundThread**
 
-5. Incompatible interfaces
+5. Selector / Element extension APIs
+- `getSelectedElements(viewId?)` - Get the current selector snapshot
+- `isElementPropertySupported(toolsType, field)` - Check whether a property field is supported by a specific tools type, useful for custom floatbar button visibility
+- `blurSelector(viewId?)` - Clear the current selector selection
+- `updateSelectedElements(viewId?, changes)` - Update properties of the current selector selection set
+- `copySelectedElements(viewId?)` - Copy the current selector selection set
+- `deleteSelectedElements(viewId?)` - Delete the current selector selection set
+- `updateElement(elementId, scenePath, viewId, updateElementInfo, useUndoRedoStack?)` - Single-element final-state update API, returns `Promise<boolean>`
+- `getFloatbarContainer(viewId?)` - Get the built-in custom floatbar mount container for the current view
+- `getViewOffsetToContainer(container, viewId?)` - Convert coordinates from the current view to an external container, useful when mounting to a business overlay root
+
+Notes:
+
+- `updateSelectedElements(...)` is selector-only and only operates on the current selection set
+- `blurSelector(...)`, `updateSelectedElements(...)`, `copySelectedElements(...)`, `deleteSelectedElements(...)`, and `updateElement(...)` should be called only when the room is writable
+- `updateElement(...)` is a storage-first single-element final-state update API
+- `updateElement(...)` does not imply rendering has finished when the Promise resolves
+- `updateElement(...)` does not support selector itself
+- `updateElementInfo` must explicitly include `toolsType`, and fields must match that tools type
+- `updateElement(...)` returning `Promise<boolean>` only means the call passed validation and the update flow was started successfully
+- `getFloatbarContainer(...)` is the recommended mount point for a custom floatbar; when mounted there, `selectorGeometryChange.viewRect` can be used directly for positioning
+- If you must mount to an external container, use `getViewOffsetToContainer(...)` to convert coordinates
+
+6. Selector extension events
+- `selectedElementsChange`
+  - Fires only when `selectedIds` change
+  - Represents only the final selection set change
+- `selectorGeometryChange`
+  - Represents only the final geometry change
+  - Coordinates are unified as `viewRect`
+- `selectorTransformChange`
+  - Represents only transform process states such as drag, resize, rotate, and endpoint editing
+  - Exposes only `viewId + emitEventType + workState`
+- `remoteSelectorChange`
+  - Represents selector sync result changes from remote / synced clients
+
+7. Custom selector / floatbar capability
+- You can disable the built-in floatbar while keeping selector selection, drag, resize, rotate, and endpoint-edit interactions
+- You can render your own custom UI based on `selectedElementsChange`, `selectorGeometryChange`, `selectorTransformChange`, and `remoteSelectorChange`
+- You can override selector visuals such as the highlight box, control points, endpoint dots, and locked icon through `overwriteSelectorStyles`
+- You can mount your custom floatbar into the plugin-provided internal container or your own external overlay container
+- Recommended reading:
+  - [customer-custom-selector-floatbar-integration.zh-CN.md](https://github.com/user-attachments/files/29439912/customer-custom-selector-floatbar-integration.zh-CN.md)
+
+8. Incompatible interfaces
 - [`exportScene`](https://api-ref.agora.io/en/interactive-whiteboard-sdk/web/2.x/interfaces/room.html#exportscene) - After appliance-plugin is enabled, notes cannot be exported in room mode
 - [Server-side screenshot](https://docs.agora.io/en/interactive-whiteboard/reference/whiteboard-api/screenshots?platform=web#screenshot-a-scene-post) - After appliance-plugin is enabled, notes cannot be obtained by calling server-side screenshot, but need to use `screenshotToCanvasAsync` to obtain the screenshot
 
@@ -349,6 +393,42 @@ Recommendations:
 - Draw `Rectangle`, `Ellipse / Circle`, `Triangle`, and `Five-point Star` as closed strokes
 - Draw `Arrow` and `Straight` as open single strokes
 
+##### Custom Selector / Floatbar and Selector Extension APIs (Version >=1.1.36-beta.2)
+
+This version adds a selector-focused event and imperative API set so that integrators can build custom selector UI, floatbar UI, and selected-element property panels in `white-web-sdk` / `@netless/window-manager` scenarios.
+
+New events:
+
+- `selectedElementsChange` - final selection set changes only
+- `selectorGeometryChange` - final geometry changes only, with unified `viewRect`
+- `selectorTransformChange` - process states for drag, resize, rotate, and endpoint editing
+- `remoteSelectorChange` - selector sync result changes from remote / synced clients
+
+New APIs:
+
+- `getSelectedElements(viewId?)`
+- `isElementPropertySupported(toolsType, field)`
+- `blurSelector(viewId?)`
+- `updateSelectedElements(viewId?, changes)`
+- `copySelectedElements(viewId?)`
+- `deleteSelectedElements(viewId?)`
+- `updateElement(elementId, scenePath, viewId, updateElementInfo, useUndoRedoStack?)`
+- `getFloatbarContainer(viewId?)`
+- `getViewOffsetToContainer(container, viewId?)`
+
+Typical usage:
+
+- Disable the built-in floatbar and render your own buttons, palettes, font-size, and text-style UI
+- Use `getSelectedElements()` to read the current selector snapshot
+- Use `updateSelectedElements()` to batch-update the current selection
+- Use `updateElement()` to update a specific element outside the current selection
+- Use `getFloatbarContainer()` or `getViewOffsetToContainer()` to decide where custom floatbar UI should be mounted
+- Use `overwriteSelectorStyles` to customize selector visuals
+
+For design details and integration examples, see:
+
+- [customer-custom-selector-floatbar-integration.zh-CN.md](https://github.com/user-attachments/files/29439912/customer-custom-selector-floatbar-integration.zh-CN.md)
+
 ##### Extended Tools (Version >=1.1.1)
 On the original [whiteboard tools](https://api-ref.agora.io/en/interactive-whiteboard-sdk/web/2.x/globals.html#memberstate) type, some extended function attributes have been added, as follows:
 

package/dist/appliance-plugin.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-B7w-GcID.js");exports.ActiveContainerType=e.ActiveContainerType;exports.ApplianceMultiPlugin=e.ApplianceMultiPlugin;exports.ApplianceNames=e.ApplianceNames;exports.ApplianceSigleWrapper=e.ApplianceSigleWrapper;exports.ApplianceSinglePlugin=e.ApplianceSinglePlugin;exports.Cursor_Hover_Id=e.Cursor_Hover_Id;exports.ECanvasShowType=e.ECanvasShowType;exports.EDataType=e.EDataType;exports.EForceStopReason=e.EForceStopReason;exports.EImageType=e.EImageType;exports.EMatrixrRelationType=e.EMatrixrRelationType;exports.EOperationType=e.EOperationType;exports.EPostMessageType=e.EPostMessageType;exports.ERenderFilterType=e.ERenderFilterType;exports.ESVGType=e.ESVGType;exports.EScaleType=e.EScaleType;exports.EStrokeType=e.EStrokeType;exports.EToolsKey=e.EToolsKey;exports.ElayerType=e.ElayerType;exports.EmitEventType=e.EmitEventType;exports.EventMessageType=e.EventMessageType;exports.EventWorkState=e.EventWorkState;exports.EvevtWorkState=e.EventWorkState;exports.InternalMsgEmitterType=e.InternalMsgEmitterType;exports.Main_View_Id=e.Main_View_Id;exports.Plugin=e.Plugin;exports.ShapeType=e.ShapeType;exports.Task_Time_Interval=e.Task_Time_Interval;exports.fullWorkerUrl=e.fullWorker;exports.subWorkerUrl=e.subWorker;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-D9xjZ07S.js");exports.ActiveContainerType=e.ActiveContainerType;exports.ApplianceMultiPlugin=e.ApplianceMultiPlugin;exports.ApplianceNames=e.ApplianceNames;exports.ApplianceSigleWrapper=e.ApplianceSigleWrapper;exports.ApplianceSinglePlugin=e.ApplianceSinglePlugin;exports.Cursor_Hover_Id=e.Cursor_Hover_Id;exports.ECanvasShowType=e.ECanvasShowType;exports.EDataType=e.EDataType;exports.EForceStopReason=e.EForceStopReason;exports.EImageType=e.EImageType;exports.EMatrixrRelationType=e.EMatrixrRelationType;exports.EOperationType=e.EOperationType;exports.EPostMessageType=e.EPostMessageType;exports.ERenderFilterType=e.ERenderFilterType;exports.ESVGType=e.ESVGType;exports.EScaleType=e.EScaleType;exports.EStrokeType=e.EStrokeType;exports.EToolsKey=e.EToolsKey;exports.ElayerType=e.ElayerType;exports.EmitEventType=e.EmitEventType;exports.EventMessageType=e.EventMessageType;exports.EventWorkState=e.EventWorkState;exports.EvevtWorkState=e.EventWorkState;exports.InternalMsgEmitterType=e.InternalMsgEmitterType;exports.Main_View_Id=e.Main_View_Id;exports.Plugin=e.Plugin;exports.ShapeType=e.ShapeType;exports.Task_Time_Interval=e.Task_Time_Interval;exports.fullWorkerUrl=e.fullWorker;exports.subWorkerUrl=e.subWorker;

package/dist/appliance-plugin.mjs

@@ -1,4 +1,4 @@
-import { a7 as s, a8 as p, a9 as r, aa as t, ab as i, a4 as l, Z as n, b as E, ac as o, t as T, j as y, ad as v, a as g, ae as S, d as c, u, w as k, c as m, af as M, E as _, ag as d, v as A, v as I, ah as W, Y as P, ai as b, aj as f, a6 as h, ak as w, al as C } from "./index-CfKLCV2y.mjs";
+import { a7 as s, a8 as p, a9 as r, aa as t, ab as i, a4 as l, Z as n, b as E, ac as o, t as T, j as y, ad as v, a as g, ae as S, d as c, u, w as k, c as m, af as M, E as _, ag as d, v as A, v as I, ah as W, Y as P, ai as b, aj as f, a6 as h, ak as w, al as C } from "./index-Dllr4Im3.mjs";
 export {
   s as ActiveContainerType,
   p as ApplianceMultiPlugin,