Skip to content

Commit fc6ff34

Browse files
hqer927hqer927
committed
docs: update appliance-plugin.md
1 parent 5ae6c7d commit fc6ff34

File tree

3 files changed

+152
-34
lines changed

3 files changed

+152
-34
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# @netless/fastboard
22

3-
[Docs](./docs/en/) | [Sandbox](https://codesandbox.io/s/vanilla-fastboard-example-trns09?file=/src/index.ts) | [中文](./README-zh.md)
3+
[Docs](./docs/en/) | [Sandbox](https://codesandbox.io/s/vanilla-fastboard-example-trns09?file=/src/index.ts) | [中文](./README-zh.md) | [Demo online](https://demo.whiteboard.agora.io)
44

55
A starter library for making whiteboard web app, based on [white-web-sdk](https://www.npmjs.com/package/white-web-sdk), [@netless/window-manager](https://www.npmjs.com/package/@netless/window-manager) and [netless-app](https://github.com/netless-io/netless-app).
66

@@ -120,7 +120,7 @@ Install `@netless/fastboard-react`, use the `<Fastboard />` component.
120120
npm add <b>@netless/fastboard-react</b> @netless/window-manager white-web-sdk react react-dom @netless/appliance-plugin
121121
</pre>
122122

123-
> **注意：** The `@netless/appliance-plugin` needs to be installed only when [Use performance](#performance) is enabled.
123+
> **Note:** The `@netless/appliance-plugin` needs to be installed only when [Use performance](#performance) is enabled.
124124
125125

126126
#### Full package

‎docs/en/appliance-plugin.md‎

Lines changed: 61 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@ The following interfaces are involved:
195195
import { EStrokeType, ApplianceNames } from '@netless/appliance-plugin';
196196
room.setMemberState({currentApplianceName: ApplianceNames.laserPen, strokeType: EStrokeType.Normal});
197197
```
198+
![Image](https://github.com/user-attachments/assets/3cd10c3a-b17b-4c01-b9d4-868c69116d96)
198199
2. Extended Teaching AIDS (Version >=1.1.1)
199200
```js
200201
export enum EStrokeType {
@@ -247,8 +248,55 @@ The following interfaces are involved:
247248
manager.mainView.setMemberState({ ... } as ExtendMemberState);
248249
appliance.setMemberState({ ... } as ExtendMemberState);
249250
```
250-
3. Split screen display Elements (little whiteboard featrue), need to combine '@netless/app-little-white-board' (Version >=1.1.3)
251+
- Set stroke type:
252+
```js
253+
// Solid line
254+
setMemberState({strokeType: EStrokeType.Normal });
255+
// Line with pen edge
256+
setMemberState({strokeType: EStrokeType.Stroke });
257+
// Dotted line
258+
setMemberState({strokeType: EStrokeType.Dotted });
259+
// Long dotted line
260+
setMemberState({strokeType: EStrokeType.LongDotted });
261+
```
262+
![Image](https://github.com/user-attachments/assets/fabe4ea7-db42-4c31-a751-10df4dd82807)
263+
- Set stroke and shape border opacity (marker):
264+
```js
265+
setMemberState({strokeOpacity: 0.5 });
266+
```
267+
![Image](https://github.com/user-attachments/assets/1aac265d-9643-4858-bcc6-a43af94ed73e)
268+
- Set text color, text opacity, text background color, text background opacity
269+
```js
270+
setMemberState({textOpacity: 0.5, textBgOpacity: 0.5, textBgColor:[0, 0, 0]});
271+
```
272+
![Image](https://github.com/user-attachments/assets/b59a9864-8f3f-4700-abee-2ccbe264cc86)
273+
- Set shape fill color and fill opacity
274+
```js
275+
setMemberState({fillOpacity: 0.5, fillColor:[0, 0, 0]});
276+
```
277+
![Image](https://github.com/user-attachments/assets/468b930c-3db0-4355-87be-6b55af764799)
278+
- Custom regular polygon
279+
```js
280+
// regular pentagon
281+
setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Polygon, vertices: 5});
282+
```
283+
![Image](https://github.com/user-attachments/assets/f34540f5-d779-42f9-bb8a-91250fcfe4e1)
284+
- Custom star shape
285+
```js
286+
// fat hexagonal star
287+
setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Star, vertices: 12, innerVerticeStep: 2, innerRatio: 0.8});
288+
```
289+
![Image](https://github.com/user-attachments/assets/49215362-722a-47d3-998f-cc933a2b5126)
290+
- Customize the placement of the speechballoon
291+
```js
292+
// The dialog box in the lower left corner
293+
setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.SpeechBalloon, placement: 'bottomLeft'});
294+
```
295+
![Image](https://github.com/user-attachments/assets/6d52dedf-ca21-406d-a353-d801273b98bf)
251296

297+
298+
3. Split screen display Elements (little whiteboard featrue), need to combine [`@netless/app-little-white-board`](https://github.com/netless-io/app-little-white-board) (Version >=1.1.3)
299+
![Image](https://github.com/user-attachments/assets/20810ea6-7d85-4e72-b75f-185599fffaf8)
252300
4. Minimap function (Version >=1.1.6)
253301
```js
254302
/** Create a minimap
@@ -259,6 +307,7 @@ The following interfaces are involved:
259307
/** Destroy minimap */
260308
destroyMiniMap(viewId: string): Promise<void>;
261309
```
310+
![Image](https://github.com/user-attachments/assets/8888dc2f-ba66-4807-aa12-16530b3b8a3c)
262311
5. Filter Elements (Version >=1.1.6)
263312
```js
264313
/** Filter Elements
@@ -276,6 +325,7 @@ The following interfaces are involved:
276325
*/
277326
cancelFilterRender(viewId: string, isSync?:boolean): void;
278327
```
328+
![Image](https://github.com/user-attachments/assets/7952ee1d-4f9c-4e86-802a-bac8e4ae6a51)
279329
6. Handwriting graphics automatic association function: 'autoDraw' (version >=1.1.7)
280330
```js
281331
export type AutoDrawOptions = {
@@ -295,11 +345,12 @@ The following interfaces are involved:
295345
});
296346
plugin.usePlugin(autoDrawPlugin);
297347
```
348+
![Image](https://github.com/user-attachments/assets/c388691c-ae72-44ec-bbb7-e92c3a73c9c7)
298349
### Configure parameters
299350
``getInstance(wm: WindowManager, adaptor: ApplianceAdaptor)``
300351
- wm: WindowManager\room\player. In multi-window mode, you pass WindowManager, and in single-window mode, you pass room or player(whiteboard playback mode).
301352
- adaptor: configures the adapter.
302-
- options: ``AppliancePluginOptions``; The cdn addresses of both workers must be configured.
353+
- ``options: AppliancePluginOptions``; The cdn addresses of both workers must be configured.
303354
```js
304355
export type AppliancePluginOptions = {
305356
/** cdn Configuration item */
@@ -308,9 +359,16 @@ The following interfaces are involved:
308359
syncOpt? : SyncOpt;
309360
/** Canvas configuration item */
310361
canvasOpt? : CanvasOpt;
362+
/** stroke width range */
363+
strokeWidth?: {
364+
min: number,
365+
max: number,
366+
}
311367
}
312368
```
313-
- cursorAdapter? : ``CursorAdapter``; This parameter is optional. In single whiteboard mode, customize the mouse style.
369+
- ``cursorAdapter? : CursorAdapter``; This parameter is optional. In single whiteboard mode, customize the mouse style.
370+
- ``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.
371+
>If you need to upload the log to the whiteboard log server, configure the `room.logger` to this item。
314372
315373
### Front-end debugging introduction
316374
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.

‎docs/zh/appliance-plugin.md‎

Lines changed: 89 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -153,52 +153,54 @@ module: {
153153
具体涉及以下接口:
154154

155155
1. room上接口
156-
- `setMemberState`
157-
- `undo`
158-
- `redo`
159-
- `callbacks`
160-
- `insertImage`
161-
- `lockImage`
162-
- `completeImageUpload`
156+
- [`setMemberState`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#setmemberstate)
157+
- [`undo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#undo)
158+
- [`redo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#redo)
159+
- [`callbacks`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#callbacks)
160+
- [`insertImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#insertImage)
161+
- [`lockImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#lockImage)
162+
- [`completeImageUpload`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#completeImageUpload)
163163
- `getImagesInformation`
164-
- `cleanCurrentScene`
164+
- [`cleanCurrentScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#cleanCurrentScene)
165165

166166
2. windowmanager上接口
167-
- `cleanCurrentScene`
168-
- `canUndoSteps`
169-
- `canRedoSteps`
167+
- [`cleanCurrentScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#cleanCurrentScene)
168+
- [`canUndoSteps`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#canUndoSteps)
169+
- [`canRedoSteps`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#canUndoSteps)
170170

171171
3. windowmanager的mainview上的接口
172-
- `setMemberState`
173-
- `undo`
174-
- `redo`
175-
- `callbacks`
176-
- `insertImage`
177-
- `lockImage`
178-
- `completeImageUpload`
172+
- [`setMemberState`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#setmemberstate)
173+
- [`undo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#undo)
174+
- [`redo`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#redo)
175+
- [`callbacks`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#callbacks)
176+
- [`insertImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#insertImage)
177+
- [`lockImage`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#lockImage)
178+
- [`completeImageUpload`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#completeImageUpload)
179179
- `getImagesInformation`
180-
- `cleanCurrentScene`
180+
- [`cleanCurrentScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#cleanCurrentScene)
181181

182182
4. 自定义
183183
- `getBoundingRectAsync` 替代接口 room.getBoundingRect
184-
- `screenshotToCanvasAsync` 替代接口 room.screenshotToCanvas
185-
- `scenePreviewAsync` 替代接口 room.scenePreview
186-
- `fillSceneSnapshotAsync` 替代接口 room.fillSceneSnapshot
184+
- `screenshotToCanvasAsync` 替代接口 [room.screenshotToCanvas](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#screenshotToCanvas)
185+
- `scenePreviewAsync` 替代接口 [room.scenePreview](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#scenePreview)
186+
- `fillSceneSnapshotAsync` 替代接口 [room.fillSceneSnapshot](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#fillSceneSnapshot)
187187
- `destroy` 销毁appliance-plugin的实例
188-
- `addListener` 添加监听器
189-
- `removeListener` 移除监听器
188+
- `addListener` 添加appliance-plugin内部事件监听器
189+
- `removeListener` 移除appliance-plugin内部事件监听器
190190

191191
5. 不兼容
192-
- `exportScene` appliance-plugin开启后,笔记不能按room的方式导出
193-
- 服务端截图, appliance-plugin开启后, 笔记不能通过调用服务端截图方式获取截图,而需要改用`screenshotToCanvasAsync`获取
192+
- [`exportScene`](https://doc.shengwang.cn/api-ref/whiteboard/javascript/interfaces/room#exportScene) appliance-plugin开启后,笔记不能按room的方式导出
193+
- [服务端截图](https://doc.shengwang.cn/doc/whiteboard/restful/fastboard-sdk/restful-wb/operations/post-v5-rooms-uuid-screenshots), appliance-plugin开启后, 笔记不能通过调用服务端截图方式获取截图,而需要改用`screenshotToCanvasAsync`获取
194194

195195
#### 新功能
196196
1. 激光铅笔教具 (Version >=1.1.1)
197197
```js
198198
import { EStrokeType, ApplianceNames } from '@netless/appliance-plugin';
199199
room.setMemberState({currentApplianceName: ApplianceNames.laserPen, strokeType: EStrokeType.Normal});
200200
```
201+
![Image](https://github.com/user-attachments/assets/3cd10c3a-b17b-4c01-b9d4-868c69116d96)
201202
2. 扩展教具 (Version >=1.1.1)
203+
在原来的[白板教具](https://doc.shengwang.cn/api-ref/whiteboard/javascript/globals.html#memberstate)类型上,增加了一些扩展功能属性,如下:
202204
```js
203205
export enum EStrokeType {
204206
/** 实心线条 */
@@ -250,7 +252,55 @@ module: {
250252
manager.mainView.setMemberState({ ... } as ExtendMemberState);
251253
appliance.setMemberState({ ... } as ExtendMemberState);
252254
```
253-
3. 分屏显示笔记(小白板功能),需要结合 `@netless/app-little-white-board` (Version >=1.1.3)
255+
- 设置笔记类型:
256+
```js
257+
// 实心线条
258+
setMemberState({strokeType: EStrokeType.Normal });
259+
// 带笔锋线条
260+
setMemberState({strokeType: EStrokeType.Stroke });
261+
// 虚线线条
262+
setMemberState({strokeType: EStrokeType.Dotted });
263+
// 长虚线线条
264+
setMemberState({strokeType: EStrokeType.LongDotted });
265+
```
266+
![Image](https://github.com/user-attachments/assets/fabe4ea7-db42-4c31-a751-10df4dd82807)
267+
- 设置笔记、图形边框透明度(马克笔):
268+
```js
269+
setMemberState({strokeOpacity: 0.5 });
270+
```
271+
![Image](https://github.com/user-attachments/assets/1aac265d-9643-4858-bcc6-a43af94ed73e)
272+
- 设置文字颜色、透明度、背景颜色、透明度
273+
```js
274+
setMemberState({textOpacity: 0.5, textBgOpacity: 0.5, textBgColor:[0, 0, 0]});
275+
```
276+
![Image](https://github.com/user-attachments/assets/b59a9864-8f3f-4700-abee-2ccbe264cc86)
277+
- 设置图形填充色及透明度
278+
```js
279+
setMemberState({fillOpacity: 0.5, fillColor:[0, 0, 0]});
280+
```
281+
![Image](https://github.com/user-attachments/assets/468b930c-3db0-4355-87be-6b55af764799)
282+
- 自定义正多边形
283+
```js
284+
// 正五边形
285+
setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Polygon, vertices: 5});
286+
```
287+
![Image](https://github.com/user-attachments/assets/f34540f5-d779-42f9-bb8a-91250fcfe4e1)
288+
- 自定义星形
289+
```js
290+
// 胖六角星
291+
setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.Star, vertices: 12, innerVerticeStep: 2, innerRatio: 0.8});
292+
```
293+
![Image](https://github.com/user-attachments/assets/49215362-722a-47d3-998f-cc933a2b5126)
294+
- 自定义泡泡框方向
295+
```js
296+
// 左下角提示框
297+
setMemberState({currentApplianceName: ApplianceNames.shape, shapeType: ShapeType.SpeechBalloon, placement: 'bottomLeft'});
298+
```
299+
![Image](https://github.com/user-attachments/assets/6d52dedf-ca21-406d-a353-d801273b98bf)
300+
301+
302+
3. 分屏显示笔记(小白板功能),需要结合[`@netless/app-little-white-board`](https://github.com/netless-io/app-little-white-board) (Version >=1.1.3)
303+
![Image](https://github.com/user-attachments/assets/20810ea6-7d85-4e72-b75f-185599fffaf8)
254304
4. 小地图功能 (Version >=1.1.6)
255305
```js
256306
/** 创建小地图
@@ -261,6 +311,7 @@ module: {
261311
/** 销毁小地图 */
262312
destroyMiniMap(viewId: string): Promise<boolean>;
263313
```
314+
![Image](https://github.com/user-attachments/assets/8888dc2f-ba66-4807-aa12-16530b3b8a3c)
264315
5. 过滤笔记 (Version >=1.1.6)
265316
```js
266317
/** 过滤笔记
@@ -278,6 +329,7 @@ module: {
278329
*/
279330
cancelFilterRender(viewId: string, isSync?:boolean): void;
280331
```
332+
![Image](https://github.com/user-attachments/assets/7952ee1d-4f9c-4e86-802a-bac8e4ae6a51)
281333
6. 手写图形自动联想功能:`autoDraw` (version >=1.1.7)
282334
```js
283335
export type AutoDrawOptions = {
@@ -297,12 +349,13 @@ module: {
297349
});
298350
plugin.usePlugin(autoDrawPlugin);
299351
```
352+
![Image](https://github.com/user-attachments/assets/c388691c-ae72-44ec-bbb7-e92c3a73c9c7)
300353

301354
### 配置参数
302355
``getInstance(wm: WindowManager, adaptor: ApplianceAdaptor)``
303356
- wm: `` WindowManager\room\player``。多窗口模式下传入的是WindowManager，单窗口模式下传入的是room或者player(白板回放模式)。
304357
- adaptor: 配置适配器.
305-
- options: ``AppliancePluginOptions``; 必须配置, 两个worker的cdn地址。
358+
- ``options: AppliancePluginOptions``; 必须配置, 两个worker的cdn地址。
306359
```js
307360
export type AppliancePluginOptions = {
308361
/** cdn配置项 */
@@ -311,9 +364,16 @@ module: {
311364
syncOpt?: SyncOpt;
312365
/** 画布配置项 */
313366
canvasOpt?: CanvasOpt;
367+
/** 线条粗细范围配置项 */
368+
strokeWidth?: {
369+
min: number,
370+
max: number,
371+
}
314372
}
315373
```
316-
- cursorAdapter?: ``CursorAdapter``; 非必填, 单白板模式下, 配置的自定义鼠标样式。
374+
- ``cursorAdapter?: CursorAdapter``; 非必填, 单白板模式下, 配置的自定义鼠标样式。
375+
- ``logger?: Logger``; 非必填, 配置日志打印器对象. 不填写默认在本地console输出, 如果需要把日志上传到指定server, 则需要手动配置.
376+
>如需要上传到白板日志服务器,可以把room上的logger配置到该项目。
317377

318378
### 前端调试介绍
319379
对接过程中如果想了解和跟踪插件内部状态,可以通过以下几个控制台指令,查看内部数据.

0 commit comments

Comments
 (0)