# Fastboard Web SDK API 参考 (/zh-CN/api-reference/whiteboard/fastboard/web)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本页提供 **Fastboard Web 1.1.10** 的 TypeScript API 参考。依赖 Whiteboard Web 2.16.59、Window Manager 1.0.25 和 Appliance Plugin 1.1.45。
## createFastboard [#createfastboard]
```typescript
createFastboard = any>(options: FastboardOptions): Promise>;
```
创建一个白板应用（`FastboardApp`）实例。
**参数**
- `options`：Object。白板配置选项。详见 [`FastboardOptions`](#fastboardoptions)。
**返回**
方法调用成功时返回 `FastboardApp` 对象。
## createUI [#createui]
```typescript
function createUI(app?: FastboardApp | null, div?: Element): UI;
```
创建 Fastboard 内置的一套 UI 组件。
**参数**
- `app`：Object。`FastboardApp` 实例，为 `createFastboard` 方法的返回值。
- `div`：HTML Element。容纳白板应用的网页元素。
**返回**
方法调用成功时返回 `UI` 组件。详见 [`UI`](#ui)。
## replayFastboard [#replayfastboard]
```typescript
replayFastboard = any>(options: FastboardReplayOptions): Promise>;
```
创建一个回放播放器（`FastboardPlayer`）实例。
**参数**
- `options`：Object。回放配置选项。详见 [`FastboardReplayOptions`](#fastboardreplayoptions)。
**返回**
方法调用成功时返回 `FastboardPlayer` 对象。
## createReplayUI [#createreplayui]
```typescript
function createReplayUI(player?: FastboardPlayer | null, div?: Element): ReplayUI;
```
创建内置回放模式的一套 UI 组件。
**参数**
- `player`：`FastboardPlayer` 实例。
- `div`：HTML Element。容纳白板应用的网页元素。
**返回**
方法调用成功时返回 `ReplayUI` 组件。详见 [`replayUI`](#replayui)。
## dispatchDocsEvent [#dispatchdocsevent]
```typescript
function dispatchDocsEvent(fastboard: FastboardApp | WindowManager, event: DocsEvent, options?: DocsEventOptions): Promise;
```
统一控制 MainView、DocsViewer、Slide、Presentation。target 省略时跟随焦点，或指定 mainView/appId；page 从 1 开始，scale=1 为适配尺寸。accepted 表示命令接收，拒绝时检查 reason/message；不保证渲染完成。
## mount [#mount]
```typescript
mount(app: FastboardApp, div: HTMLDivElement, options?: MountProps): {
update(props?: MountProps | undefined): void;
destroy(): void;
};
```
:::warning[注意]
自 v0.3.6 起不推荐使用该方法，请改用 [`createUI`](#createui)。
:::
挂载白板应用到 HTML 元素上。
**参数**
- `app`：Object。`FastboardApp` 实例，为 `createFastboard` 方法的返回值。
- `div`：HTML Element。容纳白板应用的网页元素。
- `options`：（可选）Object。白板用户界面（UI）配置选项。详见 [`MountProps`](#mountprops)。
**返回**
方法调用成功时返回如下函数：
- `update`：更新白板的 UI：
- `props`：UI 配置选项。详见 [`MountProps`](#mountprops)。
- `destroy`：卸载白板应用。
## FastboardApp 类 [#fastboardapp-类]
`FastboardApp` 类提供管理 `FastboardApp` 对象的方法。
**注意**
该类中的方法必须在成功调用 `createFastboard` 创建 `FastboardApp` 对象后调用。
### canOperate [#canoperate]
```typescript
get canOperate(): boolean;
```
获取房间是否可操作。
返回当前房间可写且连接状态为 connected 时的操作状态。
### undo [#undo]
```typescript
undo(): void;
```
撤销上一步操作。
### redo [#redo]
```typescript
redo(): void;
```
重做，即回退撤销操作。
### moveCamera [#movecamera]
```typescript
moveCamera(camera: Partial & {
animationMode?: AnimationMode | undefined;
}): void;
```
调整视角。
**参数**
- `camera`：Object。视角的参数配置，详见 [`Camera`](#camera)。
**示例**
移动视角使网页元素的中心与白板中心正好对齐，且缩放比例为 100%：
```typescript
app.moveCamera({ centerX: 0, centerY: 0, scale: 1 });
```
### moveCameraToContain [#movecameratocontain]
```typescript
moveCameraToContain(rectangle: Rectangle & {
animationMode?: AnimationMode;
}): void;
```
调整视角以完整显示指定的矩形区域。
**参数**
- `rect`：视觉矩形的参数设置，详见 [`Rectangle`](#rectangle)。
### setAppliance [#setappliance]
```typescript
setAppliance(appliance: ExtendApplianceNames | Appliance, shape?: ShapeType | ExtendShapeType | Shape): void;
```
设置当前使用的白板工具。
**参数**
- `appliance`：白板工具名称。详见 [`ApplianceNames`](#appliancenames)。
- `shape`：图形工具。详见 [`ShapeType`](#shapetype)。当 `appliance` 设为 `shape` 时，可使用该参数设置具体的图形形状。
### setStrokeWidth [#setstrokewidth]
```typescript
setStrokeWidth(strokeWidth: number): void;
```
设置线条的宽度。
**参数**
- `strokeWidth`：Number。线条宽度。
### setStrokeColor [#setstrokecolor]
```typescript
setStrokeColor(strokeColor: Color): void;
```
设置线条的颜色。
**参数**
- `strokeColor`：线条颜色，为 RGB 格式，例如 `[0, 0, 255]` 表示蓝色。详见 [`Color`](#color)。
### setTextColor [#settextcolor]
```typescript
setTextColor(textColor: Color): void;
```
设置字体的颜色。
**参数**
- `textColor`：字体颜色，为 RGB 格式，例如 `[0, 0, 255]` 表示蓝色。详见 [`Color`](#color)。
### toggleDottedLine [#toggledottedline]
```typescript
toggleDottedLine(force?: boolean): void;
```
切换铅笔工具的画线样式。
不传入 `force` 直接调用该方法时，铅笔工具将在画实线和画虚线之间切换。例如，如果当前铅笔工具为画实线，调用 `toggleDottedLine()` 将切换铅笔工具为画虚线；当前为画虚线，调用 `toggleDottedLine()` 将切换为画实线。
**参数**
- `force`：Boolean。（可选）切换绘制线条的样式：
- `true`：切换为画虚线。
- `false`：切换为画实线。
### setPencilEraserSize [#setpencilerasersize]
```typescript
setPencilEraserSize(size: number): void;
```
设置铅笔橡皮工具的尺寸。
**参数**
- `size`：Number。铅笔橡皮的尺寸，支持传入以下值：
- `1`：（默认）小号。
- `2`：中号。
- `3`：大号。
### setTextSize [#settextsize]
```typescript
setTextSize(textSize: number): void;
```
设置字体的大小。
**参数**
- `textSize`：Number。字体大小。
### insertImage [#insertimage]
```typescript
insertImage(url: string, crossOrigin?: boolean | string): Promise;
```
插入图片。
该方法可以将指定的网络图片插入并展示到当前白板页面上，插入的图片默认置于当前视图的中心。
**参数**
- `url`：String。图片的 URL 地址。请确保 App 客户端能够访问该 URL，否则图片无法正常展示。
- `crossOrigin`: Boolean。是否对插入的图片启用跨域资源共享 (CORS, Cross-Origin Resource Sharing) ：
- `true`：（默认）启用 CORS。
- `false`：禁用 CORS。
### insertMedia [#insertmedia]
```typescript
insertMedia(title: string, src: string): Promise;
```
在白板子窗口中插入并播放音视频。
**参数**
- `title`：窗口标题。
- `src`：音视频文件的 URL 地址。请确保 app 客户端能够访问该 URL，否则无法正常加载音视频文件。
**返回**
方法调用成功时，返回插入音视频的标识符。
### insertDocs [#insertdocs]
```typescript
insertDocs(
filename: string,
status: ConversionResponse,
options?: InsertDocsOptions
): Promise;
insertDocs(
filename: string,
response: ProjectorResponse,
options?: InsertDocsOptions
): Promise;
insertDocs(params: InsertDocsParams, options?: InsertDocsOptions): Promise;
```
支持转换结果和结构化参数重载；staticRenderer=presentation 创建 Presentation，未设置时静态页使用 DocsViewer。返回 App ID 或 undefined。
### insertDocs：结构化参数 [#insertdocs结构化参数]
```typescript
insertDocs(params: InsertDocsParams, options?: InsertDocsOptions): Promise;
```
结构化静态页通过 `InsertDocsStatic` 提交，动态转换结果通过 `InsertDocsDynamic` 提交；返回类型为 `Promise`。
### insertCodeEditor [#insertcodeeditor]
```typescript
insertCodeEditor(): Promise;
```
:::warning[注意]
该方法自 v0.3.6 起废弃，请改用 `fastboard.manager.addApp({ kind: 'Monaco' })` 实现。
:::
插入代码编辑器。
CodeEditor 是基于 [Monaco Editor](https://github.com/microsoft/monaco-editor) 开发的代码编辑器插件。通过调用 `insertCodeEditor` 方法，你可以快速在白板中集成 CodeEditor 插件，并使用代码编辑、自动补全、调试等功能。
**返回**
方法调用成功时，返回插件的标识符。
### insertCountdown [#insertcountdown]
```typescript
insertCountdown(): Promise;
```
:::warning[注意]
该方法自 v0.3.6 起废弃，请改用 `fastboard.manager.addApp({ kind: 'Countdown' })` 实现。
:::
插入计时器。
Countdown 是声网开发的计时器插件。通过调用 `insertCountdown` 方法，你可以快速在白板中集成 Countdown 插件，并使用该插件设定、暂停、重置倒计时。
**返回**
方法调用成功时，返回插件的标识符。
### insertGeoGebra [#insertgeogebra]
```typescript
insertGeoGebra(): Promise;
```
:::warning[注意]
该方法自 v0.3.6 起废弃，请改用 `fastboard.manager.addApp({ kind: 'GeoGebra' })` 实现。
:::
插入 GeoGebra 数学计算器。
GeoGebra 是基于 [GeoGebra](https://www.geogebra.org/) 开发的数学计算器插件。通过调用 `insertGeoGebra` 方法，你可以快速在白板中集成 GeoGebra 插件并使用该插件的功能。
**注意**
目前 GeoGebra 插件仅作为示例插件集成于 Fastboard SDK 中，如需商用，请自行联系 GeoGebra 申请许可。
**返回**
方法调用成功时，返回插件的标识符。
### removePage [#removepage]
```typescript
removePage(index?: number): Promise;
```
删除指定白板页。
**参数**
- `index`：Number。需要删除的主白板页索引，从 0 开始；省略时删除当前页。
**返回**
`true`：调用成功。
`false`：调用失败。
### jumpPage [#jumppage]
```typescript
jumpPage(index: number): Promise;
```
跳转至指定页码的白板页。
**参数**
- `index`：Number。期望跳转的主白板页索引，范围为 0～n-1。统一页面命令中的 page 则从 1 开始。
### destroy [#destroy]
```typescript
destroy(): Promise;
```
销毁 Fastboard 实例并退出房间。返回 `Promise`，应等待清理完成。
### focusApp [#focusapp]
```typescript
focusApp(appId: string): Promise;
```
可等待的布尔值表示共享 focus、本端 Box 焦点和 zIndex 已提交；不表示 App setup 或首帧完成。
### getPageState [#getpagestate]
```typescript
getPageState(options?: PageStateOptions): Promise;
```
查询统一页面状态，返回 target、可选 appId、1-based page/pageCount、可选相对 scale。状态 target 为 mainView/DocsViewer/Slide/Presentation。
### appliancePlugin [#applianceplugin]
```typescript
readonly appliancePlugin?: AppliancePluginInstance;
```
启用插件后获取插件实例，通过其 addListener/removeListener 订阅插件 PublicListener。完整事件与 Selector 示例见[公共事件监听与元素查询](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/events-and-query)。
### sdk [#sdk]
```typescript
readonly sdk: WhiteWebSdk;
```
当前 WhiteWebSdk 实例。
### room [#room]
```typescript
readonly room: Room;
```
当前实时 Room 实例。
### manager [#manager]
```typescript
readonly manager: WindowManager;
```
当前多窗口 WindowManager 实例。
### hotKeys [#hotkeys]
```typescript
readonly hotKeys: Partial;
```
当前快捷键配置。
### syncedStore [#syncedstore]
```typescript
readonly syncedStore: SyncedStore;
```
用于自定义业务数据的同步存储实例。
### appInMainViewPlugin [#appinmainviewplugin]
```typescript
readonly appInMainViewPlugin?: AppInMainViewInstance | undefined;
```
启用主视图插件后可用的实例；未启用时为 undefined。
### bindContainer [#bindcontainer]
```typescript
bindContainer(container: HTMLElement): void;
```
绑定渲染容器。由内置 UI 处理时通常无需再次绑定。
### bindCollector [#bindcollector]
```typescript
bindCollector(container: HTMLElement): void;
```
将窗口收集器绑定到指定 HTML 容器。
### writable [#writable]
```typescript
readonly writable: Writable;
```
当前房间可写状态。读取 .value；通过 .set(boolean) 提交可写状态修改。
### phase [#phase]
```typescript
readonly phase: Readable<"connecting" | "connected" | "reconnecting" | "disconnecting" | "disconnected">;
```
连接或播放阶段的可订阅状态；通过 .value 读取，subscribe/reaction 监听。
### boxState [#boxstate]
```typescript
readonly boxState: Readable<"normal" | "minimized" | "maximized" | undefined>;
```
窗口状态：normal、minimized、maximized，尚未初始化时可为 undefined。
### focusedApp [#focusedapp]
```typescript
readonly focusedApp: Readable;
```
当前焦点 App ID，无焦点 App 时为 undefined。
### canRedoSteps [#canredosteps]
```typescript
readonly canRedoSteps: Readable;
```
当前主白板可重做的步数。
### canUndoSteps [#canundosteps]
```typescript
readonly canUndoSteps: Readable;
```
当前主白板可撤销的步数。
### camera [#camera]
```typescript
readonly camera: Readable;
```
主白板相机状态。通过 moveCamera 修改，通过此只读状态读取或订阅。
### memberState [#memberstate]
```typescript
readonly memberState: Readable;
```
当前用户教具状态，包含工具与样式；通过 setAppliance 等方法更新。
### sceneIndex [#sceneindex]
```typescript
readonly sceneIndex: Writable;
```
当前主白板页索引，从 0 开始。通过 .set(index) 切页。
### sceneLength [#scenelength]
```typescript
readonly sceneLength: Readable;
```
主白板总页数。
### appsStatus [#appsstatus]
```typescript
readonly appsStatus: Readable;
```
按 App kind 索引的下载状态：idle/loading/failed；失败时可含 reason。
### visibleApps [#visibleapps]
```typescript
readonly visibleApps: Readable>;
```
主视图插件当前可见的 App ID 集合。未开启 appInMainViewPlugin 时为空集合。
### cleanCurrentScene [#cleancurrentscene]
```typescript
cleanCurrentScene(): void;
```
清空当前主白板页的笔迹。调用前确认房间已连接且具有写入权限。
### setMemberState [#setmemberstate]
```typescript
setMemberState(state: Partial): void;
```
提交当前用户的插件扩展教具状态，参数使用 ExtendMemberState；需先启用插件。只传需要修改的字段。
### prevPage [#prevpage]
```typescript
prevPage(): Promise;
```
切换到上一张主白板页，返回是否切换成功；已在第一页时不能继续向前。
### nextPage [#nextpage]
```typescript
nextPage(): Promise;
```
切换到下一张主白板页，返回是否切换成功；已在最后一页时不能继续向后。
### addPage [#addpage]
```typescript
addPage(params?: AddPageParams): Promise;
```
在主白板新增页面。params 为 AddPageParams：after 指定相对当前页的插入方向，scene 提供新场景内容；等待 Promise 完成。
### dispatchDocsEvent [#dispatchdocsevent-1]
```typescript
dispatchDocsEvent(event: DocsEvent, options?: DocsEventOptions): Promise;
```
实例方法 app.dispatchDocsEvent(event, options)，与顶层 dispatchDocsEvent(app, event, options) 区分。返回命令接收结果，需检查 accepted；不表示课件渲染完成。page 从 1 开始。
## AppsInToolbar 类 [#appsintoolbar-类]
AppsInToolbar 类提供管理工具条上插件按钮的方法。
### push [#push]
```typescript
push(...data: AppInToolbar[]): void;
```
在插件中心的末尾添加插件按钮。
该方法支持一次添加多个新的插件按钮，新添加的插件按钮位于插件中心的最后。
**参数**
- `data`：插件按钮。详见 [`AppInToolbar`](#appintoolbar)。
**示例代码**
```typescript
// 在插件中心添加一个 YouTube 按钮。点击按钮后，在白板应用中插入 Plyr 播放器并播放指定的视频。
apps.push({
icon: "https://api.iconify.design/logos:youtube-icon.svg?color=currentColor",
kind: "Plyr",
label: "YouTube",
onClick(app) {
app.manager.addApp({
kind: "Plyr",
options: { title: "YouTube" },
attributes: {
src: "https://www.youtube.com/embed/bTqVqk7FSmY",
provider: "youtube",
},
});
},
});
```
### insert [#insert]
```typescript
insert(data: AppInToolbar, index: number): void;
```
在指定位置添加一个插件按钮。
该方法支持一次添加一个新的插件按钮，并支持指定添加的位置。
**参数**
- `data`：插件按钮。详见 [`AppInToolbar`](#appintoolbar)。
- `index`：Number。待添加按钮在插件中心的索引号。取值必须大于等于 0。
### delete [#delete]
```typescript
delete(filter: (data: AppInToolbar) => boolean): void;
```
删除指定的插件按钮。
参数
- `filter`：`filter()` 方法，返回所有需要被删除的按钮组件。你需要在该方法中传入一个回调函数，用于筛选出需要删除的插件按钮。
- `data`：插件按钮。详见 [`AppInToolbar`](#appintoolbar)。
### clear [#clear]
```typescript
clear(): void;
```
删除所有插件按钮。
该方法可以删除插件中心的所有按钮，但不能删除白板工具条上的插件中心（**apps**）按钮。如果你需要隐藏白板工具条上的插件按钮，可以通过 `mount` 方法的 `options` 参数将 `config.toolbar.apps.enable` 设为 `false`。
## 类型定义 [#类型定义]
### AppInToolbar [#appintoolbar]
插件按钮。
```typescript
interface AppInToolbar {
kind: string;
icon: string;
label: string;
onClick: (app: FastboardApp) => void | Promise;
}
```
`AppInToolbar` 包含如下属性：
- `kind`：String。插件按钮的唯一标识符。可以是任意字符串。
- `icon`：String。按钮图标的 URL 地址。
- `label`：String。按钮的标题，即显示在按钮下方的文字。建议长度不超过 12 个英文字符，否则文字会显示不全。
- `onClick`：点击按钮时触发的回调：
- app：`FastboardApp` 对象。
### ApplianceNames [#appliancenames]
`ApplianceNames` 包含以下枚举值：
```typescript
selector = "selector"
```
选择工具。
```typescript
clicker = "clicker"
```
点击工具。目前主要用于点击 HTML5 文件上的内容。
```typescript
laserPointer = "laserPointer"
```
激光笔。
```typescript
pencil = "pencil"
```
铅笔。
```typescript
rectangle = "rectangle"
```
矩形工具。
```typescript
ellipse = "ellipse"
```
椭圆工具。
```typescript
shape = "shape"
```
图形工具。
```typescript
eraser = "eraser"
```
橡皮工具。
```typescript
text = "text"
```
文字工具。
```typescript
straight = "straight"
```
直线工具。
```typescript
arrow = "arrow"
```
箭头工具。
```typescript
hand = "hand"
```
抓手工具。
### Camera [#camera-1]
`Camera` 接口包含以下属性：
- `centerX`：Number。网页元素的中心在白板坐标系（以网页元素的中心为原点的坐标系）中的 X 轴坐标。默认值为 0。
- `centerY`：Number。网页元素中心在白板坐标系（以网页元素的中心为原点的坐标系）中的 Y 轴坐标。默认值为 0。
- `scale`：Number。视角的缩放比例，默认值为 1，即缩放比例为 100%。
### Color [#color]
`Color`：Number[]。颜色，格式为 RGB。例如 `[0, 0, 255]` 代表蓝色。
## DocsEventOptions [#docseventoptions]
```typescript
interface DocsEventOptions {
target?: string;
/** @deprecated 使用 target */
appId?: string;
page?: number;
scale?: number;
}
```
`target` 可为 mainView 或 appId；`appId` 为旧兼容字段。page 从 1 开始，scale 是相对适配尺寸倍率。
## FastboardOptions [#fastboardoptions]
```typescript
interface FastboardOptions {
sdkConfig: Omit & {
region: NonNullable;
};
joinRoom: Omit & {
callbacks?: Partial>;
};
managerConfig?: Omit;
netlessApps?: NetlessApp[];
enableAppliancePlugin?: AppliancePluginOptions;
/** Runtime callbacks/logger/cursor adapter; functions must not be placed in options.extras. */
appliancePluginAdaptor?: Omit;
enableAppInMainViewPlugin?: true | AppInMainViewOptions;
}
```
`enableAppliancePlugin` 为带 cdn/extras 的配置对象，运行时回调使用 `appliancePluginAdaptor.callbacks`。配置与启用示例见[教具插件介绍](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/overview?platform=web)。
### FastboardReplayOptions [#fastboardreplayoptions]
```typescript
interface FastboardReplayOptions {
sdkConfig: Omit & {
region: NonNullable;
};
replayRoom: Omit & {
callbacks?: Partial;
};
managerConfig?: Omit;
netlessApps?: NetlessApp[];
enableAppliancePlugin?: AppliancePluginOptions;
appliancePluginAdaptor?: Omit;
enableAppInMainViewPlugin?: true | AppInMainViewOptions;
}
```
`FastboardReplayOptions` 接口包含以下属性：
- `sdkConfig`: （必需）Object。`WhiteWebSdk` 实例的配置，必须传入以下参数：
- `appIdentifier`：String。互动白板项目的 AppIdentifier。详见[获取互动白板项目的安全密钥](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。
- `region`：String。数据中心，必须与[创建房间](/zh-CN/api-reference/api-ref/whiteboard/restful/create-room)时设置的数据中心一致。取值如下：
- `cn-hz`：中国杭州，服务区覆盖其他数据中心未覆盖的地区。
- `us-sv`：美国硅谷，服务区覆盖北美洲、南美洲。
- `sg`：新加坡，服务区覆盖新加坡、东亚、东南亚。
- `in-mum`：印度孟买，服务区覆盖印度。
- `eu`：欧洲（法兰克福），服务区覆盖欧洲。
- `replayRoom`：Object。（必需）加入房间的参数设置，必须传入以下参数：
- `room`：String。房间的 UUID，即房间的唯一标识符。详见[创建房间](/zh-CN/api-reference/api-ref/whiteboard/restful/create-room)请求成功后响应包体中 `uuid` 参数的值。
- `roomToken`：String 型。房间的 Room Token，用于加入房间时的用户鉴权。可以通过以下方式获取：
- 调用[生成 Room Token ](/zh-CN/api-reference/api-ref/whiteboard/restful/generate-room-token)。
- 在 app 服务端用代码生成，详见[在 app 服务端生成 Token](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/generate-token#在-app-服务端生成-token)。
- `beginTimestamp`：Number。回放开始时间，单位为毫秒。
- `duration`：Number。回放持续时间，单位为毫秒。
- `managerConfig`: （可选）Object。[WindowManager](https://github.com/netless-io/window-manager/blob/master/docs/api.md#mount) 配置选项。
- `netlessApps`：（可选）Object。官方内置或自定义的 Fastboard 插件，详见[注册和使用 Fastboard 插件](https://github.com/netless-io/fastboard/blob/main/README-zh.md#%E6%B3%A8%E5%86%8C%E4%B8%8E%E4%BD%BF%E7%94%A8-apps)。
- `enableAppliancePlugin`: （可选）启用 `appliance-plugin` 插件，详见 [`AppliancePluginOptions`](https://github.com/netless-io/fastboard/blob/main/docs/zh/appliance-plugin.md#%E9%85%8D%E7%BD%AE%E5%8F%82%E6%95%B0)。
- `enableAppInMainViewPlugin`: （可选）启用 [`@netless/app-in-mainview-plugin`](https://www.npmjs.com/package/@netless/app-in-mainview-plugin) 插件，支持在白板主视图管理[小窗应用](/zh-CN/realtime-media/whiteboard/concepts#小窗应用)：
- `true`：采用默认配置启用插件。
- `AppInMainViewOptions`：采用自定义配置启用插件，详见 [`AppInMainViewOptions`](https://github.com/netless-io/appInMainView/blob/main/README.zh-cn.md#%E5%88%9D%E5%A7%8B%E5%8C%96%E6%96%B9%E6%B3%95%E5%8F%82%E6%95%B0%E9%85%8D%E7%BD%AE)。
### FastboardProps [#fastboardprops]
```typescript
interface FastboardProps {
app?: FastboardApp | null;
theme?: Theme;
language?: Language;
/**
* Note: updating this option does not take effect when the element was mounted.
* Make sure to set this option in `UI.mount(div, { containerRef })`.
*/
containerRef?: (container: HTMLDivElement | null) => void;
config?: FastboardUIConfig;
/** Whether to forcibly display the toolbar */
force_show_toolbar?: boolean;
/** Whether to force the display of the redo undo button */
force_show_redo_undo?: boolean;
/** Whether to force the display of the zoom control button */
force_show_zoom_control?: boolean;
/** Whether to forcibly display the page control button */
force_show_page_control?: boolean;
}
```
UI 配置选项，包含以下属性：
- `app`：`FastboardApp` 对象。
- `theme`：主题，支持的取值如下：
- `dark`：深色。
- `light`：（默认）浅色。
- `language`：语言，支持的取值如下：
- `en`：（默认）英文。
- `zh-CN`：中文。
- `containerRef`：加入白板房间且成功将白板应用挂载到网页元素时触发的回调：
- `container`：容纳白板应用的网页元素。
- `config`：组件配置。详见 [`FastboardUIConfig`](#fastboarduiconfig)。
### FastboardUIConfig [#fastboarduiconfig]
白板用户界面上的组件配置。
```typescript
interface FastboardUIConfig {
toolbar?: {
enable?: boolean;
} & ToolbarConfig;
redo_undo?: {
enable?: boolean;
};
zoom_control?: {
enable?: boolean;
};
page_control?: {
enable?: boolean;
};
}
```
`FastboardUIConfig` 接口包含以下属性：
- `toolbar`：（可选）工具条：
- `enable`：（可选）是否在白板用户界面上展示工具条：
- `true`：（默认）展示。
- `false`：不展示。
- `ToolbarConfig`：工具条配置项。详见 [`ToolbarConfig`](#toolbarconfig)。
- `redo_undo`：（可选）重做和撤销按钮：
- `enable`：（可选）是否在白板用户界面上展示重做和撤销按钮：
- `true`：（默认）展示。
- `false`：不展示。
- `zoom_control`：（可选）缩放控制按钮：
- `enable`：（可选）是否在白板用户界面上展示缩放控制按钮：
- `true`：（默认）展示。
- `false`：不展示。
- `page_control`：（可选）页面控制按钮：
- `enable`：（可选）是否在白板用户界面上展示页面控制按钮：
- `true`：（默认）展示。
- `false`：不展示。
### ToolbarConfig [#toolbarconfig]
```typescript
interface ToolbarConfig {
/** @default "left" */
placement?: "left" | "right";
/** @default ["clicker", "selector", "pencil", "text", "shapes", "eraser", "clear"] */
items?: ToolbarItem[];
/**
* Note: updating this option does not take effect when the element was mounted.
* Make sure to set this option in `UI.mount(div, { configs: { toolbar: { collapsed: true } } })`.
* @default false
*/
collapsed?: boolean;
/** Control the last button which opens apps stock on toolbar. */
apps?: {
enable?: boolean;
};
/** 颜色 */
colors?: Color[];
}
```
`ToolbarConfig` 接口包含以下属性：
- `placement`：（可选）String。工具条的位置，支持的取值如下：
- `left`：（默认）左侧。
- `right`：右侧。
- `items`：（可选）String[]。工具条上展示的工具按钮，默认展示所有工具，支持的取值如下：
- `clicker`：点击工具。
- `selector`：选择工具。
- `pencil`：铅笔工具。
- `text`：文字工具。
- `shapes`：图形工具。
- `eraser`：橡皮工具。
- `clear`：清空工具。
- `hand`：抓手工具
- `laserPointer`：激光笔工具。
- `collapsed`：（可选）Boolean。工具条是否折叠：
- `true`：折叠。
- `false`：（默认）不折叠。
- `apps`：（可选）Object。插件中心：
- `enable`：（可选）是否在工具条上展示插件中心按钮：
- `true`：（默认）展示。
- `false`：不展示。
- `colors`：（可选）Color[]。UI 组件的颜色，详见 [`Color`](#color)。
### InsertDocsDynamic [#insertdocsdynamic]
```typescript
interface InsertDocsDynamic {
readonly fileType: "pptx";
/** Unique string for binding whiteboard view to the doc. Must start with `/`. */
readonly scenePath: string;
/** Conversion task id, see https://developer.netless.link/server-en/home/server-conversion#get-query-task-conversion-progress. */
readonly taskId: string;
/** Window title. */
readonly title?: string;
/** Where the slide resource placed. @default `https://convertcdn.netless.link/dynamicConvert` */
readonly url?: string;
/** @example [{ name: '1' }, { name: '2' }, { name: '3' }] */
readonly scenes?: SceneDefinition[];
}
```
`InsertDocsDynamic` 接口包含以下属性：
- `fileType`: String。文档类型，取值为 `"pptx"`，表示动态文档。
- `scenePath`: String。白板场景路径，建议填 `"/pptx/uuid"`，其中 `uuid` 为文档转换任务的 UUID，即[发起文档转换任务](/zh-CN/api-reference/api-ref/whiteboard/restful/start-file-conversion) 请求成功时响应包体中 `uuid` 参数的值。
- `taskId`: String。文档转换任务的 UUID，即[发起文档转换任务](/zh-CN/api-reference/api-ref/whiteboard/restful/start-file-conversion) 请求成功时响应包体中 `uuid` 参数的值。
- `title`: （可选）String。窗口标题
- `url`: String。转换后文档的存储路径，例如，`"https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/dynamicConvert“`。
### InsertDocsStatic [#insertdocsstatic]
```typescript
interface InsertDocsStatic {
readonly fileType: "pdf";
/** Unique string for binding whiteboard view to the doc. Must start with `/`. */
readonly scenePath: string;
/** @example [{ name: '1', ppt: { src: 'url/to/ppt/1.png' } }] */
readonly scenes: SceneDefinition[];
/** Window title. */
readonly title?: string;
}
```
`InsertDocsStatic` 接口包含以下属性：
- `fileType`：String。文档类型，取值为 `"pdf"`，表示静态文档。
- `scenePath`: String。白板场景路径，建议填 `"/pdf/uuid"`，其中 `uuid` 为文档转换任务的 UUID，即[发起文档转换任务](/zh-CN/api-reference/api-ref/whiteboard/restful/start-file-conversion) 请求成功时响应包体中 `uuid` 参数的值。
- `scenes`: SceneDefinition[]。白板场景内容，即待展示的文档。由多个 object 组成，每个 object 表示一页文件，必须包含如下参数：
- `name`：String。场景名字。
- `ppt`：PptDescription。PPT 描述，包含以下属性：
- `width`：Number。文件的宽度，单位为像素。
- `height`：Number。文件的高度，单位为像素。
- `src`：String。该页文件的 URL 地址，即[查询文档转换任务进度](/zh-CN/api-reference/api-ref/whiteboard/restful/get-file-conversion-task) 返回的响应包体中 `images` 字段下 `url` 的值。
- `title`: （可选）String。窗口标题。
### MountProps [#mountprops]
```typescript
type MountProps = {
app?: FastboardApp | null;
theme?: Theme;
language?: Language;
containerRef?: (container: HTMLDivElement | null) => void;
config?: FastboardUIConfig;
}
```
UI 配置选项，包含以下属性：
- `app`：`FastboardApp` 对象。
- `theme`：主题，支持的取值如下：
- `dark`：深色。
- `light`：（默认）浅色。
- `language`：语言，支持的取值如下：
- `en`：（默认）英文。
- `zh-CN`：中文。
- `containerRef`：加入白板房间且成功将白板应用挂载到网页元素时触发的回调：
- `container`：容纳白板应用的网页元素。
- `config`：组件配置。详见 [`FastboardUIConfig`](#uiconfig)。
### Rectangle [#rectangle]
`Rectangle` 接口包含以下属性：
- `originX`：Number。矩形左上角在白板坐标系（以网页元素的中心为原点的坐标系）中的 X 轴坐标。
- `originY`：Number。矩形左上角在白板坐标系（以网页元素的中心为原点的坐标系）中的 Y 轴坐标。
- `width`：矩形的宽度（px）。
- `height`：矩形的高度（px）。
### ReplayUI [#replayui]
回放模式的一套 UI 组件。
```typescript
interface ReplayUI {
/** render UI to div */
mount(div: Element, props?: ReplayFastboardProps): ReplayUI;
/** update UI (theme, language, etc.) */
update(props?: ReplayFastboardProps): void;
/** remove UI */
destroy(): void;
}
```
`ReplayUI` 组件包含以下函数：
- `mount`: 挂载白板 UI 到 HTML 元素上。
- `div`：HTML Element。容纳白板应用的网页元素。
- `props`: Object。UI 配置选项，详见 [`FastboardProps`](#fastboardprops)。
- `update`: 用于 UI 配置变更后，更新 Fastboard UI。
- `props`: Object。UI 配置选项，详见 [`FastboardProps`](#fastboardprops)。
- `destroy`: 移除 UI。
### ShapeType [#shapetype]
`ShapeType` 包含以下枚举值：
```typescript
Triangle = "triangle"
```
三角形。
```typescript
Rhombus = "rhombus"
```
菱形。
```typescript
Pentagram = "pentagram"
```
五角星。
```typescript
SpeechBalloon = "speechBalloon"
```
对话气泡。
### UI [#ui]
Fastboard 内置的一套 UI 组件。
```typescript
interface UI {
/** render UI to div */
mount(div: Element, props?: FastboardProps): UI;
/** update UI (theme, language, etc.) */
update(props?: FastboardProps): void;
/** remove UI */
destroy(): void;
/** force show toolbar */
forceShowToolbar(): void;
/** force hide toolbar */
forceHideToolbar(): void;
/** recover show toolbar */
recoverToolbar(): void;
/** force show redo undo */
forceShowRedoUndo(): void;
/** force hide redo undo */
forceHideRedoUndo(): void;
/** recover show redo undo */
recoverRedoUndo(): void;
/** force show zoom control */
forceShowZoomControl(): void;
/** force hide zoom control */
forceHideZoomControl(): void;
/** recover show zoom control */
recoverZoomControl(): void;
/** force show page control */
forceShowPageControl(): void;
/** force hide page control */
forceHidePageControl(): void;
/** recover show page control */
recoverPageControl(): void;
}
```
`UI` 组件包含以下函数：
- `mount`: 挂载白板 UI 到 HTML 元素上。
- `div`：HTML Element。容纳白板应用的网页元素。
- `props`: Object。UI 配置选项，详见 [`FastboardProps`](#fastboardprops)。
- `update`: 用于 UI 配置变更后，更新 Fastboard UI。
- `props`: Object。UI 配置选项，详见 [`FastboardProps`](#fastboardprops)。
- `destroy`: 移除 UI。
## InsertDocsOptions [#insertdocsoptions]
```typescript
interface InsertDocsOptions {
/** Renderer for static documents. Dynamic documents always use Slide. @default "docsViewer" */
readonly staticRenderer?: "docsViewer" | "presentation";
}
```
`staticRenderer` 默认为 docsViewer；presentation 创建内置 Presentation。
## UnifiedPageState [#unifiedpagestate]
```typescript
export type UnifiedPageState = {
target: "mainView" | "DocsViewer" | "Slide" | "Presentation";
appId?: string;
page: number;
pageCount: number;
/** MainView/Slide/Presentation actual scale relative to fitted size. */
scale?: number;
};
```
查询结果用于实际页面观察；命令 accepted 不等于渲染完成。
## FastboardPlayer 类 [#fastboardplayer-类]
```typescript
// const player = await replayFastboard(options);
```
通过 replayFastboard 创建。状态与方法均属于回放实例，时间单位为毫秒。
### sdk [#sdk-1]
```typescript
readonly sdk: WhiteWebSdk;
```
当前 WhiteWebSdk 实例。
### player [#player]
```typescript
readonly player: Player;
```
底层回放 Player 实例。
### manager [#manager-1]
```typescript
readonly manager: WindowManager;
```
当前多窗口 WindowManager 实例。
### syncedStore [#syncedstore-1]
```typescript
readonly syncedStore: SyncedStore;
```
用于自定义业务数据的同步存储实例。
### appliancePlugin [#applianceplugin-1]
```typescript
readonly appliancePlugin?: AppliancePluginInstance | undefined;
```
启用教具插件后可用的实例；未启用时为 undefined。
### appInMainViewPlugin [#appinmainviewplugin-1]
```typescript
readonly appInMainViewPlugin?: AppInMainViewInstance | undefined;
```
启用主视图插件后可用的实例；未启用时为 undefined。
### destroy [#destroy-1]
```typescript
destroy(): Promise;
```
异步销毁回放并释放资源，等待 Promise 完成。
### bindContainer [#bindcontainer-1]
```typescript
bindContainer(container: HTMLElement): void;
```
绑定渲染容器。由内置 UI 处理时通常无需再次绑定。
### bindCollector [#bindcollector-1]
```typescript
bindCollector(container: HTMLElement): void;
```
将窗口收集器绑定到指定 HTML 容器。
### currentTime [#currenttime]
```typescript
readonly currentTime: Writable;
```
当前播放进度，单位毫秒。通过 .set(timestamp) 定位。
### phase [#phase-1]
```typescript
readonly phase: Readable<"waitingFirstFrame" | "playing" | "pause" | "stop" | "ended" | "buffering">;
```
连接或播放阶段的可订阅状态；通过 .value 读取，subscribe/reaction 监听。
### canplay [#canplay]
```typescript
readonly canplay: Readable;
```
缓冲完成、可开始播放时变为 true。
### playbackRate [#playbackrate]
```typescript
readonly playbackRate: Writable;
```
播放速度，默认 1。可通过 .set(value) 修改。
### duration [#duration]
```typescript
readonly duration: Readable;
```
回放总时长，单位毫秒。
### state [#state]
```typescript
readonly state: Readable;
```
当前时间点的白板状态，包含成员等信息。
### seek [#seek]
```typescript
seek(timestamp: number): Promise;
```
定位到指定毫秒时间点，异步返回 PlayerSeekingResult。
### play [#play]
```typescript
play(): void;
```
开始或继续播放。
### pause [#pause]
```typescript
pause(): void;
```
暂停播放。
### stop [#stop]
```typescript
stop(): void;
```
停止播放。
### setPlaybackRate [#setplaybackrate]
```typescript
setPlaybackRate(value: number): void;
```
设置播放倍速，等价于 playbackRate.set(value)。
## Readable 与 Writable [#readable-与-writable]
```typescript
interface Writable extends Readable {}
```
状态对象通过 .value 读取；使用订阅返回的函数解除业务监听。Writable 继承 Readable 的全部成员。
### value [#value]
```typescript
readonly value: T;
```
同步读取当前值。
### subscribe [#subscribe]
```typescript
subscribe(this: void, run: Subscriber): Unsubscriber;
```
订阅后立即回调当前值，随后在变化时回调；返回解除订阅函数。
### reaction [#reaction]
```typescript
reaction(this: void, run: Subscriber): Unsubscriber;
```
只监听后续变化，不立即回调当前值；返回解除订阅函数。
### dispose [#dispose]
```typescript
dispose(value?: T): void;
```
释放该状态的所有订阅，可先提供一个最终值。通常由状态所有者销毁时调用。
### set [#set]
```typescript
set(this: void, value: T): void;
```
写入新值。SDK 状态的写入会触发对应白板操作。
### update [#update]
```typescript
update(this: void, updater: Updater): void;
```
将当前值传给 updater，并写入它返回的新值。
```typescript
const unsubscribe = app.phase.subscribe(phase => console.log(phase));
app.writable.set(true);
const index = app.sceneIndex.value;
// 业务组件卸载时释放自己的监听。
unsubscribe();
```