@netless/window-manager 1.0.0-canary.8 → 1.0.0

package/docs/camera.md

@@ -1,53 +1,52 @@
-# 视角
-在多窗口模式下, 可以同时存在多块白板，但是大多数情况下用户都只需要对主白板也就是 `mainView` 进行操作
+# view angle
+In multi-window mode, multiple whiteboards can exist at the same time, but in most cases users only need to operate on the main whiteboard, which is `mainView`
 
 
-## 获取 `mainView` 的 `camera`
+## Get `camera` of `mainView`
 ```typescript
 manager.mainView.camera
 ```
 
-## 获取 `mainView` 的 `size`
+## Get `size` of `mainView`
 ```typescript
 manager.mainView.size
 ```
 
-## 监听 `mainView` 的 `camera` 变化
+## Monitor `camera` changes in `mainView`
 ```typescript
 manager.mainView.callbacks.on("onCameraUpdated", camera => {
-    // 更新后的 camera
+     // updated camera
 })
 ```
 
-## 监听 `mainView` 的 `size` 的变化
+## Monitor the change of `size` of `mainView`
 ```typescript
 manager.mainView.callbacks.on("onSizeUpdated", camera => {
-    // 更新后的 size
+     // updated size
 })
 ```
 
-## 通过 `api` 移动 `camera`
+## Move `camera` via `api`
 ```typescript
 manager.moveCamera(camera)
 ```
 
-## 设置视角边界
-把所有人的视角限制在以世界坐标 (0, 0) 为中心，宽为 1024，高为 768 的矩形之中。
+## Set view bounds
+Limit everyone's viewing angle to a rectangle centered at world coordinates (0, 0) with a width of 1024 and a height of 768.
 ```typescript
 manager.setCameraBound({
-    centerX: 0,
-    centerY: 0,
-    width: 1024,
-    height: 768,
+     centerX: 0,
+     centerY: 0,
+     width: 1024,
+     height: 768,
 })
 ```
 
-## 禁止/允许 `mainView` `camera` 的移动，缩放
+## Prohibit/allow movement and scaling of `mainView` `camera`
 ```typescript
-// 禁止 `camera` 移动,缩放
+// Prohibit `camera` from moving and zooming
 manager.mainView.disableCameraTransform = false
 
-// 恢复 `camera` 移动,缩放
+// restore `camera` movement, scaling
 manager.mainView.disableCameraTransform = true
-```
-
+```

package/docs/cn/advanced.md

@@ -0,0 +1,137 @@
+## 进阶使用
+
+- 目录
+  - [撤销重做](#redo-undo)
+  - [清屏](#clean-current-scene)
+  - [判断是否打开某种 APP](#has-kind)
+  - [页面控制器](#page-control)
+  - [视角](#view-mode)
+  - [插入图片到当前app](#insert-image-to-app)
+
+
+<h3 id="redo-undo">撤销重做</h3>
+
+> 以下事件和属性都会根据 `focus` 的窗口来进行自动切换应用对象
+
+#### 获取可以撤销/重做的步数
+
+```ts
+manager.canUndoSteps
+manager.canRedoSteps
+```
+
+#### 监听可以撤销/重做的步数的变化
+
+`canRedoStepsChange` 和 `canUndoStepsChange` 会在切换窗口时重新触发
+
+```ts
+manager.emitter.on("canUndoStepsChange", (steps: number) => {
+    // 可以撤销的步数更新
+})
+manager.emitter.on("canRedoStepsChange", (steps: number) => {
+    // 可以重做的步数更新
+})
+```
+
+#### 撤销/重做
+
+```ts
+manager.undo() //撤销
+manager.redo() // 重做 
+```
+
+<br>
+
+<h3 id="clean-current-scene">清屏</h3>
+
+因为在多窗口模式下有多个白板, 如果想要清除当前 `focus` 的白板只需要调用
+
+```ts
+manager.cleanCurrentScene()
+```
+
+只想清理主白板的笔迹则需要
+
+```ts
+manager.mainView.cleanCurrentScene()
+```
+
+
+<br>
+
+<h3 id="has-kind">判断是否打开某种 APP</h3>
+
+```ts
+manager.emitter.on("ready", () => { // ready 事件在所有 app 创建完成后触发
+    const apps = manager.queryAll(); //  获取所有已经打开的 App
+    const hasSlide = apps.some(app => app.kind === "Slide"); // 判断已经打开的 APP 中是否有 Slide
+});
+```
+
+<br>
+
+<h3 id="page-control">页面控制器</h3>
+
+`manager` 提供了一个 `pageState` 来获取当前的 index 和总页数
+
+```ts
+manager.pageState.index // 当前的 index
+manager.pageState.length // 总页数
+
+manager.emitter.on("pageStateChange", state => {
+    // 当前 index 变化和总页数变化会触发此事件
+});
+```
+
+上一页/下一页/添加一页
+
+```ts
+manager.nextPage()
+manager.prevPage()
+manager.addPage()
+```
+
+<br>
+
+<h3 id="view-mode">视角跟随</h3>
+
+多窗口中 `ViewMode` 有 `broadcaster` `freedom` 两种模式
+
+- `freedom`
+
+    自由模式，用户可以自由放缩、移动视角
+
+    即便房间里有主播，主播也无法影响用户的视角
+
+- `broadcaster`
+
+    主播模式, 操作时其他人的视角都会跟随我
+
+    同时其他为 `broadcaster` 模式的人也会影响我的视角
+
+    在 `isWritable` 为 `false` 时只会跟随其他 `broadcaster` 的视角
+
+<br>
+
+<h3 id="insert-image-to-app">插入图片到当前 app</h3>
+
+```ts
+// 判断当前是否为最大化
+if (manager.boxState === "maximized") {
+    // `focused` 的值的会根据当前 focus 的 app 不同而变化
+    const app = manager.queryOne(manager.focused)
+    // 有 view 的 app 才可以插入图片, 像是 视频，音频之类的 app 是没有 view 的
+    if (app.view) {
+        var imageInformation = {
+            uuid: uuid,
+            centerX: centerX,
+            centerY: centerY,
+            width: width,
+            height: height,
+            locked: false,
+        };
+        app.view.insertImage(imageInformation);
+        app.view.completeImageUpload(uuid, src);
+    }
+}
+```

package/docs/cn/api.md

@@ -0,0 +1,309 @@
+# API
+
+## 目录
+  - [静态方法](#static-methods)
+    - [`mount`](#mount)
+    - [`register`](#register)
+    - [`registered`](#registered)
+    - [`setContainer`](#set-container)
+    - [`setCollectorContainer`](#set-collector-container)
+  - [实例方法](#instance-methods)
+    - [`addApp`](#addApp)
+    - [`closeApp`](#closeApp)
+    - [`focusApp`](#focusApp)
+    - [`setMainViewSceneIndex`](#setMainViewSceneIndex)
+    - [`setBoxState`](#setBoxState)
+    - [`cleanCurrentScene`](#cleanCurrentScene)
+    - [`redo`](#redo)
+    - [`undo`](#undo)
+    - [`copy`](#copy)
+    - [`paste`](#paste)
+    - [`delete`](#delete)
+    - [`duplicate`](#duplicate)
+    - [`insertText`](#insertText)
+    - [`insertImage`](#insertImage)
+    - [`completeImageUpload`](#completeImageUpload)
+    - [`lockImage`](#lockImage)
+    - [`lockImages`](#lockImages)
+    - [`nextPage`](#nextPage)
+    - [`prevPage`](#prevPage)
+    - [`addPage`](#addPage)
+    - [`removePage`](#removePage)
+    - [`refresh`](#refresh)
+    - [`setContainerSizeRatio`](#setContainerSizeRatio)
+  - [实例属性](#prototypes)
+  - [事件回调](#events)
+
+<br>
+
+<h2 id="static-methods">静态方法</h2>
+
+<h3 id="mount">WindowManager.mount</h3>
+
+> 挂载 WindowManager
+
+```typescript
+const manager = await WindowManager.mount(
+    room: room,
+    container: document.getElementById("container")
+    // 完整配置见下方
+);
+```
+
+参数
+
+| name                   | type                                    | default | desc                         |
+| ---------------------- | --------------------------------------- | ------- | ---------------------------- |
+| room                   | [require] Room                          |         | 房间实例                         |
+| container              | [require] HTMLElement                   |         | 房间挂载容器                       |
+| containerSizeRatio     | [optional] number                       | 9 / 16  | 多窗口区域的高宽比，默认为 9 : 16         |
+| chessboard             | [optional] boolean                      | true    | 多窗口区域以外的空间显示 PS 棋盘背景，默认 true |
+| collectorContainer     | [optional] HTMLElement                  |         | 用于多窗口最小化图标挂载的 dom            |
+| collectorStyles        | [optional] Partial{CSSStyleDeclaration} |         | 配置 collector 的样式             |
+| overwriteStyles        | [optional] string                       |         | 用于覆盖窗口的样式                    |
+| cursor                 | [optional] boolean                      | false   | 开启光标同步                       |
+| disableCameraTransform | [optional] boolean                      |         | 禁用主白板的相机移动                   |
+| prefersColorScheme     | [optional] string                       | light   | auto, light, dark            |
+| debug                  | [optional] boolean                      | false   | 打印日志信息   
+| applianceIcons         | [optional] {ApplianceNames, string}     |         | 配置光标使用的教具图片           ｜
+
+<h3 id="register">WindowManager.register</h3>
+
+> 注册 `APP` 到 `WindowManager`
+
+```typescript
+WindowManager.register({
+    kind: "helloWorld",
+    src: NetlessApp,
+    appOptions: () => "appOptions",
+    addHooks: (emitter) => {
+         emitter.on("created", result => {
+            console.log("HelloWordResult", result);
+        });
+        emitter.on("focus", result => {
+            console.log("HelloWorld focus", result);
+        })
+        emitter.on("destroy", result => {
+            console.log("HelloWorld destroy", result);
+        })
+    }
+})
+```
+
+<br>
+
+<h3 id="registered">WindowManager.registered</h3>
+
+> 获取已经注册过的 `App`
+
+```ts
+WindowManager.registered
+```
+
+<br>
+
+<h3 id="set-container">setContainer</h3>
+
+> 设置白板挂载容器
+
+```typescript
+WindowManager.setContainer(document.getElementById("container"));
+```
+
+<h3 id="set-container">setCollectorContainer</h3>
+
+> 设置 `Collector` 挂载的容器
+
+```typescript
+WindowManager.setCollectorContainer(document.getElementById("collector-container"));
+```
+
+<br>
+
+<h2 id="instance-methods">实例方法</h2>
+
+<h3 id="addApp">addApp</h3>
+
+> 添加 `app` 至白板
+
+```typescript
+const appId = await manager.addApp({
+    kind: "helloWorld"
+    options: { // 可选配置
+        scenePath: "/hello-world"
+    }
+})
+```
+具体参数请参考 `APP` 本身的要求
+
+<h3 id="closeApp">closeApp</h3>
+
+> 关闭已经打开的 `APP`
+
+```typescript
+manager.closeApp(appId)
+```
+
+<h3 id="focusApp">focusApp</h3>
+
+> 切换当前 `focus` 的 `app`, 并把此 `app` 置为最前
+
+```typescript
+manager.focusApp(appId)
+```
+
+<h3 id="setMainViewSceneIndex">setMainViewSceneIndex</h3>
+
+> 设置主白板的 `SceneIndex`
+
+```ts
+manager.setMainViewSceneIndex(1)
+```
+
+<h3 id="setBoxState">setBoxState</h3>
+
+> 设置当前的 `boxState`
+
+```ts
+manager.setBoxState("normal") // boxState: normal | maximized | minimized
+```
+
+<h3 id="cleanCurrentScene">cleanCurrentScene</h3>
+
+> 清除当前 focus 的 view 的笔迹
+
+```ts
+manager.cleanCurrentScene()
+```
+
+<h3 id="redo">redo</h3>
+
+> 在当前 focus 的 view 上重做上一步操作
+
+```ts
+manager.redo()
+```
+
+<h3 id="undo">undo</h3>
+
+> 在当前 focus 的 view 上撤消上一步操作
+
+```ts
+manager.undo()
+```
+
+<h3 id="nextPage">nextPage</h3>
+
+> 切换主白板至下一页
+
+```ts
+const success = await manager.nextPage()
+if (!success) {
+    // 已经到了最后一页
+}
+```
+
+<h3 id="prevPage">prevPage</h3>
+
+> 切换主白板至上一页
+
+```ts
+const success = await manager.prevPage()
+if (!success) {
+    // 已经到了第一页
+}
+```
+
+<h3 id="addPage">addPage</h3>
+
+> 在主白板添加一页
+
+```ts
+manager.addPage() // 默认在最后添加一页
+manager.addPage({ after: true }) // 在当前页后添加一页
+manager.addPage({ scene: { name: "page2" } }) // 传入 page 信息
+```
+
+<h3 id="removePage">removePage</h3>
+
+> 移除一页
+> 当只剩一页时, 最后一页不允许被删除
+
+```ts
+const success = await manager.removePage() // 默认删除当前页
+const success = await manager.removePage(1) // 可以删除指定 index
+```
+
+<h3 id="refresh">refresh</h3>
+
+> 刷新 `manager` 的内部状态, 用于从其他房间 `copy` `attributes`
+
+```ts
+manager.refresh()
+```
+
+<h3 id="setContainerSizeRatio">setContainerSizeRatio</h3>
+
+> 设置白板同步区域的宽高比
+
+```ts
+manager.setContainerSizeRatio(10 / 16)
+```
+
+<br>
+
+<h2 id="prototypes">实例属性</h2>
+
+| name               | type    | default | desc                   |
+| ------------------ | ------- | ------- | -----------------      |
+| mainView           | View    |         | 主白板                  |
+| mainViewSceneIndex | number  |         | 当前主白板的 SceneIndex  |
+| mainViewScenesLength | number |        | mainView 的 scenes 长度 |
+| boxState           | string  |         | 当前窗口状态             |
+| darkMode           | boolean |         | 黑夜模式                 |
+| prefersColorScheme | string  |         | 颜色主题                 |
+| focused            | string |          | focus 的 app            |
+| canRedoSteps       | number  |         | 当前 focus 的 view 可以重做的步数 |
+| canRedoSteps       | number  |         | 当前 focus 的 view 可以撤销的步数 |
+| sceneState         | SceneState |      | 兼容原本 SDK 的 sceneState 属性, 只对 mainView 生效 |
+| pageState          | PageState |       | 组合 mainView 的 index 和 scenes 的修改 |
+
+<br>
+
+<h2 id="events">事件回调</h2>
+
+```typescript
+manager.emitter.on(events, listener)
+```
+
+| name                     | type           | default | desc                       |
+| ------------------------ | -------------- | ------- | -------------------------- |
+| mainViewModeChange       | ViewVisionMode |         |                            |
+| mainViewSceneIndexChange | index: number  |         |                            |
+| boxStateChange           | string         |         | normal,minimized,maximized |
+| darkModeChange           | boolean        |         |                            |
+| prefersColorSchemeChange | string         |         | auto,light,dark            |
+| cameraStateChange        | CameraState    |         |                            |
+| focusedChange            | string, undefined |     | 当前 focus 的 appId，主白板时为 undefined  |
+| mainViewScenesLengthChange | number      |         | mainView scenes 添加或删除时触发 |
+| canRedoStepsChange       | number         |         | 当前 focus 的 view 可重做步数改变 |
+| canUndoStepsChange       | number         |         | 当前 focus 的 view 可撤销步数改变 |
+| loadApp                  | LoadAppEvent   |         | 加载远程APP 事件                |
+| ready                    | undefined      |         | 当所有 APP 创建完毕时触发      ｜
+| sceneStateChange         | SceneState     |         | 当 sceneState 修改时触发     |
+| pageStateChange          | PageState      |         |                            ｜
+
+```ts
+type LoadAppEvent = {
+    kind: string;
+    status: "start" | "success" | "failed";
+    reason?: string;
+}
+```
+
+```ts
+type PageState = {
+    index: number;
+    length: number;
+}
+```