@netless/window-manager 1.0.0-canary.9 → 1.0.1

package/docs/cn/app-context.md

@@ -0,0 +1,369 @@
+## AppContext
+
+    `AppContext` 是插件运行时传入的上下文
+    你可以通过此对象操作 APP 的 ui, 获取当前房间的状态, 以及订阅状态的变化
+
+- [api](#api)
+    - [view](#view)
+    - [page](#page)
+    - [storage](#storage)
+- [ui(box)](#box)
+- [events](#events)
+- [Advanced](#Advanced)
+
+<h2 id="api">API</h2>
+
+- **context.appId**
+
+    插入 `app` 时生成的唯一 ID
+
+    ```ts
+    const appId = context.appId;
+    ```
+
+- **context.isReplay**
+    
+    类型: `boolean`
+    
+    当前是否回放模式
+
+- **context.getDisplayer()**
+
+    在默认情况下 `Displayer` 为白板的 `room` 实例
+
+    回放时则为 `Player` 实例
+
+    ```ts
+    const displayer = context.getDisplayer();
+
+    assert(displayer, room); // 互动房间
+    assert(displayer, player); // 回放房间
+    ```
+
+
+- **context.getIsWritable()**
+
+    获取当前状态是否可写\
+    可以通过监听 `writableChange` 事件获取可写状态的改变
+
+    ```ts
+    const isWritable = context.getIsWritable();
+    ```
+
+- **context.getBox()**
+
+    获取当前 app 的 box
+
+    ```ts
+    const box = context.getBox();
+
+    box.$content; // box 的 main element
+    box.$footer;
+    ```
+
+<h3 id="view">挂载白板</h3>
+
+当应用想要一个可以涂画的白板，可以使用以下接口
+
+- **context.mountView()**
+
+    挂载白板到指定 dom
+
+    ```ts
+    context.mountView(element);
+    ```
+
+**注意** 在调用 `manager` 的 `addApp` 时必须填写 `scenePath` 才可以使用 `view`
+```ts
+manager.addApp({
+    kind: "xxx",
+    options: { // 可选配置
+        scenePath: "/example-path"
+    }
+})
+```
+
+<h3 id="page">Page</h3>
+
+白板有多页的概念, 可以通过以下接口添加，切换，以及删除
+
+- **context.addPage()**
+
+    添加一页至 `view`
+
+    ```ts
+    context.addPage() // 默认在最后添加一页
+    context.addPage({ after: true }) // 在当前页后添加一页
+    context.addPage({ scene: { name: "page2" } }) // 传入 page 信息
+    ```
+
+- **context.nextPage()**
+
+    上一页
+
+    ```ts
+    context.nextPage();
+    ```
+
+- **context.prevPage()**
+
+    下一页
+
+    ```ts
+    context.prevPage();
+    ```
+- **context.removePage()**
+
+    删除一页
+
+    ```ts
+    context.removePage() // 默认删除当前页
+    context.removePage(1) // 也可以指定 index 删除
+    ```
+
+- **context.pageState**
+
+    获取当前所在的 `index` 和一共有多少页\
+    当想要监听 `pageState` 的变化时, 可以监听 `pageStateChange` 事件获取最新的 `pageState`
+
+    ```ts
+    context.pageState;
+    // {
+    //     index: number,
+    //     length: number,
+    // }
+    ```
+
+<h3 id="storage">storage</h3>
+
+存储和同步状态，以及发送事件的一系列集合
+
+- **context.storage**
+
+    默认创建的 storage 实例
+
+    ```ts
+    context.storage
+    ```
+
+- **context.createStorage(namespace)**
+
+    同时你也可以创建多个 `storage` 实例
+    
+    返回: `Storage<State>`
+
+    ```ts
+    type State = { count: number };
+    const defaultState = { count: 0 };
+    const storage = context.createStorage<State>("store1", defaultState);
+    ```
+
+- **storage.state**
+
+  类型: `State`\
+  默认值: `defaultState`
+
+  在所有客户端之间同步的状态，调用 `storage.setState()` 来改变它。
+
+- **storage.ensureState(partialState)**
+
+  确保 `storage.state` 包含某些初始值，类似于执行了：
+
+  ```js
+  // 这段代码不能直接运行，因为 app.state 是只读的
+  storage.state = { ...partialState, ...storage.state };
+  ```
+
+  **partialState**
+
+  类型: `Partial<State>`
+
+  ```js
+  storage.state; // { a: 1 }
+  storage.ensureState({ a: 0, b: 0 });
+  storage.state; // { a: 1, b: 0 }
+  ```
+
+- **storage.setState(partialState)**
+
+  和 React 的 `setState` 类似，更新 `storage.state` 并同步到所有客户端。
+
+  当设置某个字段为 `undefined` 时，它会被从 `storage.state` 里删除。
+
+  > - 状态同步所需的时间和网络状态与数据大小有关，建议只在 state 里存储必须的数据。
+
+  **partialState**
+
+  类型: `Partial<State>`
+
+  ```js
+  storage.state; //=> { count: 0, a: 1 }
+  storage.setState({ count: storage.state.count + 1, b: 2 });
+  storage.state; //=> { count: 1, a: 1, b: 2 }
+  ```
+
+- **storage.addStateChangedListener(listener)**
+
+  它在有人调用 `storage.setState()` 后触发 (包含当前 `storage`)
+
+  返回: `() => void`
+
+  ```js
+  const disposer = storage.addStateChangedListener(diff => {
+    console.log("state changed", diff.oldValue, diff.newValue);
+    disposer(); // remove listener by calling disposer
+  });
+  ```
+
+- **context.dispatchMagixEvent(event, payload)**
+
+  向其他客户端广播事件消息
+
+  ```js
+  context.dispatchMagixEvent("click", { data: "data" });
+  ```
+
+- **context.addMagixEventListener(event, listener)**
+
+  当接收来自其他客户端的消息时(当其他客户端调用'context.dispatchMagixEvent()`时), 它会被触发
+
+  返回: `() => void` a disposer function.
+
+  ```js
+  const disposer = context.addMagixEventListener("click", ({ payload }) => {
+    console.log(payload.data);
+    disposer();
+  });
+
+  context.dispatchMagixEvent("click", { data: "data" });
+  ```
+
+<h2>UI (box)</h2>
+
+    box 是白板为所有应用默认创建的 UI
+    应用所有可以操作的 UI 部分都在 box 范围内
+
+- **context.getBox()**
+
+    获取 box
+    返回类型: `ReadonlyTeleBox`
+
+- **box.mountStyles()**
+
+    挂载样式到 `box`
+    参数: `string | HTMLStyleElement`
+
+    ```js
+    const box = context.getBox();
+    box.mountStyles(`
+        .app-span {
+            color: red;
+        }
+    `)
+    ```
+
+- **box.mountContent()**
+
+    挂载元素到 `box`
+    参数: `HTMLElement`
+
+    ```js
+    const box = context.getBox();
+    const content = document.createElement("div");
+    box.mountContent(context);
+    ```
+
+- **box.mountFooter()**
+
+    挂载元素到 `box` 的 `footer`
+    参数: `HTMLElement`
+
+    ```js
+    const box = context.getBox();
+    const footer = document.createElement("div");
+    box.mountFooter(context);
+    ```
+
+<h2 id="events">events</h2>
+
+- **destroy**
+
+    app 被关闭时发送
+
+    ```ts
+    context.emitter.on("destroy", () => {
+        // release your listeners
+    });
+    ```
+
+- **writableChange**
+
+    白板可写状态切换时触发
+
+    ```ts
+    context.emitter.on("writableChange", isWritable => {
+        //
+    });
+    ```
+
+- **focus**
+
+    当前 app 获得焦点或者失去焦点时触发
+
+    ```ts
+    context.emitter.on("focus", focus => {
+        //
+    });
+    ```
+
+- **pageStateChange**
+
+    `PageState`
+
+    ```ts
+    type PateState {
+        index: number;
+        length: number;
+    }
+    ```
+
+    当前页数和总页数变化时触发
+
+    ```ts
+    context.emitter.on("pageStateChange", pageState => {
+        // { index: 0, length: 1 }
+    });
+    ```
+- **roomStageChange**
+
+    房间的状态变化时触发\
+    比如当教具切换时
+
+    ```js
+    context.emitter.on("roomStageChange", stage => {
+        if (state.memberState) {
+            console.log("appliance change to", state.memberState.currentApplianceName);
+        }
+    });
+    ```
+
+    或者是当前房间人数变化时
+
+    ```js
+     context.emitter.on("roomStageChange", stage => {
+        if (state.roomMembers) {
+            console.log("current room members change", state.roomMembers);
+        }
+    });
+    ```
+    详细状态的介绍请参考 https://developer.netless.link/javascript-zh/home/business-state-management
+
+<h2 id="Advanced">Advanced</h2>
+
+- **context.getView()**
+
+    获取 `view` 实例
+
+    ```ts
+    const view = context.getView();
+    ```

package/docs/cn/basic.md

@@ -0,0 +1,64 @@
+# 基础教程
+`WindowManager` 内置了 `DocsViewer` 和 `MediaPlayer` 用来播放 PPT 和音视频
+
+## 打开动态/静态 PPT
+```typescript
+import { BuiltinApps } from "@netless/window-manager";
+
+const appId = await manager.addApp({
+    kind: BuiltinApps.DocsViewer,
+    options: {
+        scenePath: "/docs-viewer", // 定义 ppt 所在的 scenePath
+        title: "docs1", // 可选
+        scenes: [], // SceneDefinition[] 静态/动态 Scene 数据
+    },
+});
+```
+
+## 打开音视频
+```typescript
+import { BuiltinApps } from "@netless/window-manager";
+
+const appId = await manager.addApp({
+    kind: BuiltinApps.MediaPlayer,
+    options: {
+        title: "test.mp3", // 可选
+    },
+    attributes: {
+        src: "xxxx", // 音视频 url
+    },
+});
+```
+ 
+
+## 查询所有的 App
+```typescript
+const apps = manager.queryAll();
+```
+
+## 查询单个 APP
+```typescript
+const app = manager.queryOne(appId);
+``` 
+
+## 关闭 App
+```typescript
+manager.closeApp(appId);
+```
+
+## events
+
+### 窗口最小化最大化
+```typescript
+manager.emitter.on("boxStateChange", state => {
+    // maximized | minimized | normal
+});
+```
+
+### 视角跟随模式
+```typescript
+manager.emitter.on("broadcastChange", state => {
+    // state: number | undefined
+});
+```
+

package/docs/cn/camera.md

@@ -0,0 +1,53 @@
+# 视角
+在多窗口模式下, 可以同时存在多块白板，但是大多数情况下用户都只需要对主白板也就是 `mainView` 进行操作
+
+
+## 获取 `mainView` 的 `camera`
+```typescript
+manager.mainView.camera
+```
+
+## 获取 `mainView` 的 `size`
+```typescript
+manager.mainView.size
+```
+
+## 监听 `mainView` 的 `camera` 变化
+```typescript
+manager.mainView.callbacks.on("onCameraUpdated", camera => {
+    // 更新后的 camera
+})
+```
+
+## 监听 `mainView` 的 `size` 的变化
+```typescript
+manager.mainView.callbacks.on("onSizeUpdated", camera => {
+    // 更新后的 size
+})
+```
+
+## 通过 `api` 移动 `camera`
+```typescript
+manager.moveCamera(camera)
+```
+
+## 设置视角边界
+把所有人的视角限制在以世界坐标 (0, 0) 为中心，宽为 1024，高为 768 的矩形之中。
+```typescript
+manager.setCameraBound({
+    centerX: 0,
+    centerY: 0,
+    width: 1024,
+    height: 768,
+})
+```
+
+## 禁止/允许 `mainView` `camera` 的移动，缩放
+```typescript
+// 禁止 `camera` 移动,缩放
+manager.mainView.disableCameraTransform = true
+
+// 恢复 `camera` 移动,缩放
+manager.mainView.disableCameraTransform = false
+```
+**注意**，该属性为 `true` 时，仅仅禁止设备操作。你依然可以用 `moveCamera` 方法主动调整视角。

package/docs/cn/concept.md

@@ -0,0 +1,9 @@
+# 概念
+
+## 同步区域
+
+在不同分辨率的设备上，想要看到相同的区域和窗口，我们就需要在所有设备保持一个相同的比例。
+
+所以 `WindowManager` 有一个 `containerSizeRatio` 的选项来配置白板的宽高比，默认为 `9 / 16`
+
+如果外层给到 `WindowManager` 宽高并不是完美适配这个宽高比的话, `WindowManger` 会自动在内部算出一个适配这个比例的最大宽高，然后填充上去，这时在内部就会有一些区域不能操作

package/docs/cn/custom-max-bar.md

@@ -0,0 +1,31 @@
+## 如何自定义最大化 `titleBar`
+
+获取并订阅所有的 `box`
+
+```js
+manager.boxManager.teleboxManager.boxes$.subscribe(boxes => {
+    // boxes 为所有的窗口，当窗口添加和删除时都会触发
+})
+```
+
+切换 `box` 的 `focus`
+```js
+manager.boxManager.teleBoxManager.focusBox(box)
+```
+
+关闭某个 `box`
+```js
+manager.boxManager.teleBoxManager.remove(box)
+```
+
+切换最大化状态
+```js
+manager.boxManager.teleBoxManager.setMaximized(false)
+manager.boxManager.teleBoxManager.setMaximized(true)
+```
+
+切换最小化状态
+```js
+manager.boxManager.teleBoxManager.setMinimized(true)
+manager.boxManager.teleBoxManager.setMaximized(false)
+```

package/docs/cn/develop-app.md

@@ -0,0 +1,94 @@
+# 开发自定义 APP
+
+- [AppContext](./app-context.md)
+
+## official apps https://github.com/netless-io/netless-app
+
+## app-with-whiteboard
+
+如果需要 app 中挂载白板请参考 [board.tsx](https://github.com/netless-io/window-manager/blob/master/example/app/board.tsx)
+
+<br>
+
+```ts
+import type { NetlessApp, AppContext } from "@netless/window-manager";
+
+const HelloWorld: NetlessApp = {
+    kind: "HelloWorld",
+    setup: (context: AppContext) => {
+        context.mountView(context.getBox().$content); // 可选: 挂载 View 到 box 上
+    },
+};
+
+WindowManager.register({
+    kind: HelloWorld.kind,
+    src: HelloWorld,
+});
+
+manager.addApp({
+    kind: "HelloWorld",
+    options: {
+        scenePath: "/hello-world", // 如果需要在 App 中使用白板则必须声明 scenePath
+    },
+});
+```
+
+## Counter
+
+```ts
+const Counter: NetlessApp<{ count: number }> = {
+    kind: "Counter",
+    setup: (context) => {
+        const storage = context.storage;
+        storage.ensureState({ count: 0 });
+
+        const box = context.getBox(); // box 为这个应用打开的窗口
+        const $content = box.$content // 获取窗口的 content
+
+        const countDom = document.createElement("div");
+        countDom.innerText = storage.state.count.toString();
+        $content.appendChild(countDom);
+
+        // 监听 state 变化回调
+        storage.addStateChangedListener(diff => {
+            if (diff.count) {
+                // diff 会给出 newValue 和 oldValue
+                console.log(diff.count.newValue);
+                console.log(diff.count.oldValue);
+                countDom.innerText = diff.count.newValue.toString();
+            }
+        });
+
+        const incButton = document.createElement("button");
+        incButton.innerText = "Inc";
+        const incButtonOnClick = () => {
+            storage.setState({ count: storage.state.count + 1 });
+        }
+        incButton.addEventListener("click", incButtonOnClick);
+        $content.appendChild(incButton);
+
+        const decButton = document.createElement("button");
+        decButton.innerText = "Dec";
+        const decButtonOnClick = () => {
+            storage.setState({ count: storage.state.count - 1 });
+        }
+        decButton.addEventListener("click", decButtonOnClick);
+        $content.appendChild(decButton);
+
+            // 监听事件
+        const event1Disposer = context.addMagixEventListener("event1", msg => {
+            console.log("event1", msg);
+        });
+
+        // 向打开 app 的其他人发送消息
+        context.dispatchMagixEvent("event1", { count: 10 });
+
+        // 应用销毁时, 注意清理掉监听器
+        context.emitter.on("destroy", () => {
+            incButton.removeEventListener("click", incButtonOnClick);
+            decButton.removeEventListener("click", decButtonOnClick);
+            event1Disposer();
+        });
+    }
+}
+```

package/docs/cn/export-pdf.md

@@ -0,0 +1,48 @@
+# 导出 PDF
+
+此功能需要额外安装 `jspdf` 依赖才能使用
+
+```
+npm install jspdf@2.5.1
+```
+
+### 支持的 app 及版本
+
+1. @netless/app-slide  `0.2.23` 及以上版本支持保存动态 ppt 板书
+
+2. @netless/app-docs-viewer  `0.2.10` 及以上版本支持保存 pdf 板书, **注意** app-docs-viewer 中可以展示静态 ppt, pdf, 动态 ppt. 其中只有 pdf 文件支持保存板书
+
+   对应 @netless/window-manager `0.4.50` 及以上
+
+3. white-web-sdk  `2.16.37` 及以上
+
+### 发起保存板书任务
+
+通过 `window.postMessage` 发事件来发起保存板书任务, 注意不要在任务尚未完成之前重复发送该事件.
+
+```js
+window.postMessage({
+    type: "@netless/_request_save_pdf_",
+    appId: /* windowManager.addApp 返回的值, 指定要保存哪个窗口的板书, */
+})
+```
+
+### 获取任务进度
+
+任务进度也通过 message 事件传递, 你需要在发起任务之前监听任务进度事件, 实例代码如下所示.
+其中 data.result 只有在任务成功时候才有值, 任务失败或者任务进行中都为 null.
+**如果下载任务失败, 则 progress 为 100 但是 result 为 null.**
+
+```js
+window.addEventListener("message", evt => {
+    if (evt.data.type === "@netless/_result_save_pdf_") {
+        console.log(evt.data);
+        // data 包含如下属性
+        // data.type: 固定值 "@netless/_result_save_pdf_"
+        // data.appId: 指明是哪次下载任务, 与发起保存板书时候传递的 appId 值一致
+        // data.progress: 下载进度,  0 ~ 100
+        // data.result: { pdf: ArrayBuffer {}, title: "a.pptx" } 或者 null, 为板书的 pdf 文件内容,
+        //              仅当下载进度 100 时才有值. 获取到 ArrayBuffer 后需要自行完成下载到本地的逻辑.
+    }
+});
+```