docs: update appliance-plugin.md

hqer927 · hqer927 · commit 232b87ad5d5d · 2025-02-05T11:56:43.000+08:00
diff --git a/README.md b/README.md
@@ -120,7 +120,7 @@ Install `@netless/fastboard-react`, use the `<Fastboard />` component.
 npm add <b>@netless/fastboard-react</b> @netless/window-manager white-web-sdk react react-dom @netless/appliance-plugin
 </pre>
 
-> **注意：** The `@netless/appliance-plugin` needs to be installed only when [Use performance](#performance) is enabled.
+> **Note:** The `@netless/appliance-plugin` needs to be installed only when [Use performance](#performance) is enabled.
 
 
 #### Full package
diff --git a/docs/en/appliance-plugin.md b/docs/en/appliance-plugin.md
@@ -195,6 +195,7 @@ The following interfaces are involved:
     import { EStrokeType, ApplianceNames } from '@netless/appliance-plugin';
     room.setMemberState({currentApplianceName: ApplianceNames.laserPen, strokeType: EStrokeType.Normal});
     ```
+    ![Image](https://github.com/user-attachments/assets/3cd10c3a-b17b-4c01-b9d4-868c69116d96)
 2. Extended Teaching AIDS (Version >=1.1.1)
     ```js
     export enum EStrokeType { 
@@ -247,8 +248,55 @@ The following interfaces are involved:
     manager.mainView.setMemberState({ ... } as ExtendMemberState);
     appliance.setMemberState({ ... } as ExtendMemberState);
     ```
-3. Split screen display Elements (little whiteboard featrue), need to combine '@netless/app-little-white-board' (Version >=1.1.3)
+    - Set stroke type:
+    ```js
+    // Solid line
+    setMemberState({strokeType: EStrokeType.Normal });
+    // Line with pen edge
+    setMemberState({strokeType: EStrokeType.Stroke });
+    // Dotted line
+    setMemberState({strokeType: EStrokeType.Dotted });
+    // Long dotted line
+    setMemberState({strokeType: EStrokeType.LongDotted });
+    ```
+    ![Image](https://github.com/user-attachments/assets/fabe4ea7-db42-4c31-a751-10df4dd82807)
+    - Set stroke and shape border opacity (marker):
+    ```js
+    setMemberState({strokeOpacity: 0.5 });
+    ```
+    ![Image](https://github.com/user-attachments/assets/1aac265d-9643-4858-bcc6-a43af94ed73e)
+    - Set text color, text opacity, text background color, text background opacity
+    ```js
+    setMemberState({textOpacity: 0.5, textBgOpacity: 0.5, textBgColor:[0, 0, 0]});
+    ```
+    ![Image](https://github.com/user-attachments/assets/b59a9864-8f3f-4700-abee-2ccbe264cc86)
+    - Set shape fill color and fill opacity
+    ```js
+    setMemberState({fillOpacity: 0.5, fillColor:[0, 0, 0]});
+    ```
+    ![Image](https://github.com/user-attachments/assets/468b930c-3db0-4355-87be-6b55af764799)
+    - Custom regular polygon
+    ```js
+    // regular pentagon
+    setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Polygon, vertices: 5});
+    ```
+    ![Image](https://github.com/user-attachments/assets/f34540f5-d779-42f9-bb8a-91250fcfe4e1)
+    - Custom star shape
+    ```js
+    // fat hexagonal star
+    setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Star, vertices: 12, innerVerticeStep: 2, innerRatio: 0.8});
+    ```
+    ![Image](https://github.com/user-attachments/assets/49215362-722a-47d3-998f-cc933a2b5126)
+    - Customize the placement of the speechballoon
+    ```js
+    // The dialog box in the lower left corner
+    setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.SpeechBalloon, placement: 'bottomLeft'});
+    ```
+    ![Image](https://github.com/user-attachments/assets/6d52dedf-ca21-406d-a353-d801273b98bf)
+
 
+3. Split screen display Elements (little whiteboard featrue), need to combine '@netless/app-little-white-board' (Version >=1.1.3)
+    ![Image](https://github.com/user-attachments/assets/20810ea6-7d85-4e72-b75f-185599fffaf8)
 4. Minimap function (Version >=1.1.6)
     ```js
     /** Create a minimap
@@ -259,6 +307,7 @@ The following interfaces are involved:
     /** Destroy minimap */
     destroyMiniMap(viewId: string): Promise<void>;
     ```
+    ![Image](https://github.com/user-attachments/assets/8888dc2f-ba66-4807-aa12-16530b3b8a3c)
 5. Filter Elements (Version >=1.1.6)
     ```js
     /** Filter Elements
@@ -276,6 +325,7 @@ The following interfaces are involved:
      */
     cancelFilterRender(viewId: string, isSync?:boolean): void;
     ```
+    ![Image](https://github.com/user-attachments/assets/7952ee1d-4f9c-4e86-802a-bac8e4ae6a51)
 6. Handwriting graphics automatic association function: 'autoDraw' (version >=1.1.7)
     ```js
     export type AutoDrawOptions = {
@@ -295,11 +345,12 @@ The following interfaces are involved:
     });
     plugin.usePlugin(autoDrawPlugin);
     ```
+    ![Image](https://github.com/user-attachments/assets/c388691c-ae72-44ec-bbb7-e92c3a73c9c7)
 ### Configure parameters 
 ``getInstance(wm: WindowManager, adaptor: ApplianceAdaptor)`` 
 - wm: WindowManager\room\player. In multi-window mode, you pass WindowManager, and in single-window mode, you pass room or player(whiteboard playback mode). 
 - adaptor: configures the adapter. 
-    - options: ``AppliancePluginOptions``; The cdn addresses of both workers must be configured. 
+    - ``options: AppliancePluginOptions``; The cdn addresses of both workers must be configured. 
         ```js 
             export type AppliancePluginOptions = { 
                 /** cdn Configuration item */ 
@@ -308,9 +359,16 @@ The following interfaces are involved:
                 syncOpt? : SyncOpt; 
                 /** Canvas configuration item */ 
                 canvasOpt? : CanvasOpt; 
+                /** stroke width range */
+                strokeWidth?: {
+                    min: number,
+                    max: number,
+                }
             } 
         ```
-    - cursorAdapter? : ``CursorAdapter``; This parameter is optional. In single whiteboard mode, customize the mouse style.
+    - ``cursorAdapter? : CursorAdapter``; This parameter is optional. In single whiteboard mode, customize the mouse style.
+    - ``logger?: Logger``; This parameter is optional. Configure the log printer object. The default output is on the local console. If logs need to be uploaded to the specified server, you need to manually configure the configuration.
+        >If you need to upload the log to the whiteboard log server, configure the `room.logger` to this item。
 
 ### Front-end debugging introduction 
 During the interconnection process, if you want to understand and track the internal status of the plug-in, you can view the internal data through the following console commands. 
diff --git a/docs/zh/appliance-plugin.md b/docs/zh/appliance-plugin.md
@@ -153,52 +153,54 @@ module: {
 具体涉及以下接口:
 
 1. room上接口
-- `setMemberState`
-- `undo`
-- `redo`
-- `callbacks`
-- `insertImage`
-- `lockImage`
-- `completeImageUpload`
+- [`setMemberState`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#setmemberstate)
+- [`undo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#undo)
+- [`redo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#redo)
+- [`callbacks`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#callbacks)
+- [`insertImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#insertImage)
+- [`lockImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#lockImage)
+- [`completeImageUpload`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#completeImageUpload)
 - `getImagesInformation`
-- `cleanCurrentScene`
+- [`cleanCurrentScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#cleanCurrentScene)
 
 2. windowmanager上接口
-- `cleanCurrentScene`
-- `canUndoSteps`
-- `canRedoSteps`
+- [`cleanCurrentScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#cleanCurrentScene)
+- [`canUndoSteps`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#canUndoSteps)
+- [`canRedoSteps`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#canUndoSteps)
 
 3. windowmanager的mainview上的接口
-- `setMemberState`
-- `undo`
-- `redo`
-- `callbacks`
-- `insertImage`
-- `lockImage`
-- `completeImageUpload`
+- [`setMemberState`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#setmemberstate)
+- [`undo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#undo)
+- [`redo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#redo)
+- [`callbacks`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#callbacks)
+- [`insertImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#insertImage)
+- [`lockImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#lockImage)
+- [`completeImageUpload`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#completeImageUpload)
 - `getImagesInformation`
-- `cleanCurrentScene`
+- [`cleanCurrentScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#cleanCurrentScene)
 
 4. 自定义
 - `getBoundingRectAsync` 替代接口 room.getBoundingRect
-- `screenshotToCanvasAsync` 替代接口 room.screenshotToCanvas
-- `scenePreviewAsync` 替代接口 room.scenePreview
-- `fillSceneSnapshotAsync` 替代接口 room.fillSceneSnapshot
+- `screenshotToCanvasAsync` 替代接口 [room.screenshotToCanvas](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#screenshotToCanvas)
+- `scenePreviewAsync` 替代接口 [room.scenePreview](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#scenePreview)
+- `fillSceneSnapshotAsync` 替代接口 [room.fillSceneSnapshot](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#fillSceneSnapshot)
 - `destroy` 销毁appliance-plugin的实例
-- `addListener` 添加监听器
-- `removeListener` 移除监听器
+- `addListener` 添加appliance-plugin内部事件监听器
+- `removeListener` 移除appliance-plugin内部事件监听器
 
 5. 不兼容
-- `exportScene` appliance-plugin开启后,笔记不能按room的方式导出
-- 服务端截图, appliance-plugin开启后, 笔记不能通过调用服务端截图方式获取截图,而需要改用`screenshotToCanvasAsync`获取
+- [`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`获取
 
 #### 新功能
 1. 激光铅笔教具 (Version >=1.1.1)
     ```js
     import { EStrokeType, ApplianceNames } from '@netless/appliance-plugin';
     room.setMemberState({currentApplianceName: ApplianceNames.laserPen, strokeType: EStrokeType.Normal});
     ```
+    ![Image](https://github.com/user-attachments/assets/3cd10c3a-b17b-4c01-b9d4-868c69116d96)
 2. 扩展教具 (Version >=1.1.1)
+    在原来的[白板教具](https://doc.shengwang.cn/api-ref/whiteboard/javascript/globals.html#memberstate)类型上,增加了一些扩展功能属性,如下:
     ```js
     export enum EStrokeType {
         /** 实心线条 */
@@ -250,7 +252,55 @@ module: {
     manager.mainView.setMemberState({ ... } as ExtendMemberState);
     appliance.setMemberState({ ... } as ExtendMemberState);
     ```
-3. 分屏显示笔记(小白板功能),需要结合 `@netless/app-little-white-board` (Version >=1.1.3)
+    - 设置笔记类型:
+    ```js
+    // 实心线条
+    setMemberState({strokeType: EStrokeType.Normal });
+    // 带笔锋线条
+    setMemberState({strokeType: EStrokeType.Stroke });
+    // 虚线线条
+    setMemberState({strokeType: EStrokeType.Dotted });
+    // 长虚线线条
+    setMemberState({strokeType: EStrokeType.LongDotted });
+    ```
+    ![Image](https://github.com/user-attachments/assets/fabe4ea7-db42-4c31-a751-10df4dd82807)
+    - 设置笔记、图形边框透明度(马克笔):
+    ```js
+    setMemberState({strokeOpacity: 0.5 });
+    ```
+    ![Image](https://github.com/user-attachments/assets/1aac265d-9643-4858-bcc6-a43af94ed73e)
+    - 设置文字颜色、透明度、背景颜色、透明度
+    ```js
+    setMemberState({textOpacity: 0.5, textBgOpacity: 0.5, textBgColor:[0, 0, 0]});
+    ```
+    ![Image](https://github.com/user-attachments/assets/b59a9864-8f3f-4700-abee-2ccbe264cc86)
+    - 设置图形填充色及透明度
+    ```js
+    setMemberState({fillOpacity: 0.5, fillColor:[0, 0, 0]});
+    ```
+    ![Image](https://github.com/user-attachments/assets/468b930c-3db0-4355-87be-6b55af764799)
+    - 自定义正多边形
+    ```js
+    // 正五边形
+    setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Polygon, vertices: 5});
+    ```
+    ![Image](https://github.com/user-attachments/assets/f34540f5-d779-42f9-bb8a-91250fcfe4e1)
+    - 自定义星形
+    ```js
+    // 胖六角星
+    setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Star, vertices: 12, innerVerticeStep: 2, innerRatio: 0.8});
+    ```
+    ![Image](https://github.com/user-attachments/assets/49215362-722a-47d3-998f-cc933a2b5126)
+    - 自定义泡泡框方向
+    ```js
+    // 左下角提示框
+    setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.SpeechBalloon, placement: 'bottomLeft'});
+    ```
+    ![Image](https://github.com/user-attachments/assets/6d52dedf-ca21-406d-a353-d801273b98bf)
+
+
+3. 分屏显示笔记(小白板功能),需要结合[`@netless/app-little-white-board`](https://github.com/netless-io/app-little-white-board) (Version >=1.1.3)
+    ![Image](https://github.com/user-attachments/assets/20810ea6-7d85-4e72-b75f-185599fffaf8)
 4. 小地图功能 (Version >=1.1.6)
     ```js
     /** 创建小地图
@@ -261,6 +311,7 @@ module: {
     /** 销毁小地图 */
     destroyMiniMap(viewId: string): Promise<boolean>;
     ```
+    ![Image](https://github.com/user-attachments/assets/8888dc2f-ba66-4807-aa12-16530b3b8a3c)
 5. 过滤笔记 (Version >=1.1.6)
     ```js
     /** 过滤笔记
@@ -278,6 +329,7 @@ module: {
      */
     cancelFilterRender(viewId: string, isSync?:boolean): void;
     ```
+    ![Image](https://github.com/user-attachments/assets/7952ee1d-4f9c-4e86-802a-bac8e4ae6a51)
 6. 手写图形自动联想功能:`autoDraw` (version >=1.1.7)
     ```js
     export type AutoDrawOptions = {
@@ -297,12 +349,13 @@ module: {
     });
     plugin.usePlugin(autoDrawPlugin);
     ```
+    ![Image](https://github.com/user-attachments/assets/c388691c-ae72-44ec-bbb7-e92c3a73c9c7)
 
 ### 配置参数
 ``getInstance(wm: WindowManager, adaptor: ApplianceAdaptor)``
 - wm: `` WindowManager\room\player``。多窗口模式下传入的是WindowManager，单窗口模式下传入的是room或者player(白板回放模式)。
 - adaptor: 配置适配器.
-    - options: ``AppliancePluginOptions``; 必须配置, 两个worker的cdn地址。
+    - ``options: AppliancePluginOptions``; 必须配置, 两个worker的cdn地址。
         ```js
             export type AppliancePluginOptions = {
                 /** cdn配置项 */
@@ -311,9 +364,16 @@ module: {
                 syncOpt?: SyncOpt;
                 /** 画布配置项 */
                 canvasOpt?: CanvasOpt;
+                /** 线条粗细范围配置项 */
+                strokeWidth?: {
+                    min: number,
+                    max: number,
+                }
             }
         ```
-    - cursorAdapter?: ``CursorAdapter``; 非必填, 单白板模式下, 配置的自定义鼠标样式。
+    - ``cursorAdapter?: CursorAdapter``; 非必填, 单白板模式下, 配置的自定义鼠标样式。
+    - ``logger?: Logger``; 非必填, 配置日志打印器对象. 不填写默认在本地console输出, 如果需要把日志上传到指定server, 则需要手动配置.
+        >如需要上传到白板日志服务器,可以把room上的logger配置到该项目。
 
 ### 前端调试介绍
 对接过程中如果想了解和跟踪插件内部状态,可以通过以下几个控制台指令,查看内部数据.
