Fastboard SDK API 参考文档

本页提供声网 Fastboard SDK for Web 的 TypeScript API 参考。

createFastboard

createFastboard(options: FastboardOptions): Promise;

创建一个白板应用（FastboardApp）实例。

参数

• options：Object。白板配置选项。详见 FastboardOptions。

返回

方法调用成功时返回 FastboardApp 对象。

createUI

createUI(app?: FastboardApp | null, div?: Element): UI;

创建 Fastboard 内置的一套 UI 组件。

参数

• app：Object。FastboardApp 实例，为 createFastboard 方法的返回值。
• div：HTML Element。容纳白板应用的网页元素。

返回

方法调用成功时返回 UI 组件。详见 UI。

createReplayUI

createReplayUI(player?: FastboardPlayer | null, div?: Element): ReplayUI;

创建内置回放模式的一套 UI 组件。

参数

• player：FastboardPlayer 实例。
• div：HTML Element。容纳白板应用的网页元素。

返回

方法调用成功时返回 ReplayUI 组件。详见 replayUI。

mount

mount(app: FastboardApp, div: HTMLDivElement, options?: MountProps): {
 update(props?: MountProps | undefined): void;
 destroy(): void;
};

挂载白板应用到 HTML 元素上。

参数

• app：Object。FastboardApp 实例，为 createFastboard 方法的返回值。
• div：HTML Element。容纳白板应用的网页元素。
• options：（可选）Object。白板用户界面（UI）配置选项。详见 MountProps。

返回

方法调用成功时返回如下函数：

• update：更新白板的 UI：
  • props：UI 配置选项。详见 MountProps。
• destroy：卸载白板应用。

FastboardApp 类

FastboardApp 类提供管理 FastboardApp 对象的方法。

注意

该类中的方法必须在成功调用 createFastboard 创建 FastboardApp 对象后调用。

undo

undo(): void

撤销上一步操作。

redo

redo(): void

重做，即回退撤销操作。

moveCamera

moveCamera(camera: Partial<Camera>): void

调整视角。

参数

• camera：Object。视角的参数配置，详见 Camera。

示例

移动视角使网页元素的中心与白板中心正好对齐，且缩放比例为 100%：

app.moveCamera({ centerX: 0, centerY: 0, scale: 1 });

moveCameraToContain

moveCameraToContain(rect: Rectangle): void;

调整视角以完整显示指定的矩形区域。

参数

• rect：视觉矩形的参数设置，详见 Rectangle。

setAppliance

setAppliance(appliance: ApplianceNames, shape?: ShapeType): void

设置当前使用的白板工具。

参数

• appliance：白板工具名称。详见 ApplianceNames。
• shape：图形工具。详见 ShapeType。当 appliance 设为 shape 时，可使用该参数设置具体的图形形状。

setStrokeWidth

setStrokeWidth(strokeWidth: number): void

设置线条的宽度。

参数

• strokeWidth：Number。线条宽度。

setStrokeColor

setStrokeColor(strokeColor: Color): void

设置线条的颜色。

参数

• strokeColor：线条颜色，为 RGB 格式，例如 [0, 0, 255] 表示蓝色。详见 Color。

setTextColor

setTextColor(textColor: Color): void

设置字体的颜色。

参数

• textColor：字体颜色，为 RGB 格式，例如 [0, 0, 255] 表示蓝色。详见 Color。

setTextSize

setTextSize(textSize: number): void

设置字体的大小。

参数

• textSize：Number。字体大小。

insertImage

insertImage(url: string): Promise<void>

插入图片。

该方法可以将指定的网络图片插入并展示到当前白板页面上。

参数

• url：String。图片的 URL 地址。请确保 app 客户端能够访问该 URL，否则图片无法正常展示。

insertMedia

insertMedia(title: string, src: string): Promise<string | undefined>

在白板子窗口中插入并播放音视频。

参数

• title：窗口标题。
• src：音视频文件的 URL 地址。请确保 app 客户端能够访问该 URL，否则无法正常加载音视频文件。

返回

方法调用成功时，返回插件的标识符。

insertDocs [1/2]

insertDocs(title: string, response: ConversionResponse): Promise<string | undefined>;

在白板子窗口中插入并展示文档。

成功发起文档转换任务并调用查询文档转换任务进度 API 获取文档转换结果后，可以调用该方法并传入获取的文档转换结果，SDK 会自动创建子窗口，插入并分页展示转换后的文档。

参数

• title：窗口标题。
• response：查询文档转换任务进度 API 请求成功时返回的响应包体。

返回

方法调用成功时，返回插件的标识符。

insertDocs [2/2]

insertDocs(params: InsertDocsStatic | InsertDocsDynamic): Promise<string | undefined>;

在白板子窗口中插入并展示文档。

成功发起文档转换任务后， 可以调用该方法，传入转换后文档的相关参数，SDK 会自动创建子窗口，插入并分页展示转换后的文档。

参数

• params：插入文档的参数设置。待插入文档为静态类型，详见 InsertDocsStatic；待插入文档为动态类型，详见 InsertDocsDynamic。

insertCodeEditor

insertCodeEditor(): Promise<string | undefined>

插入代码编辑器。

CodeEditor 是基于 Monaco Editor 开发的代码编辑器插件。通过调用 insertCodeEditor 方法，你可以快速在白板中集成 CodeEditor 插件，并使用代码编辑、自动补全、调试等功能。

返回

方法调用成功时，返回插件的标识符。

insertCountdown

insertCountdown(): Promise<string | undefined>

插入计时器。

Countdown 是声网开发的计时器插件。通过调用 insertCountdown 方法，你可以快速在白板中集成 Countdown 插件，并使用该插件设定、暂停、重置倒计时。

返回

方法调用成功时，返回插件的标识符。

insertGeoGebra

insertGeoGebra(): Promise<string | undefined>

插入 GeoGebra 数学计算器。

GeoGebra 是基于 GeoGebra 开发的数学计算器插件。通过调用 insertGeoGebra 方法，你可以快速在白板中集成 GeoGebra 插件并使用该插件的功能。

注意

目前 GeoGebra 插件仅作为示例插件集成于 Fastboard SDK 中，如需商用，请自行联系 GeoGebra 申请许可。

返回

方法调用成功时，返回插件的标识符。

removePage

removePage(index?): Promise<boolean>

删除指定白板页。

参数

• index：Number。需要删除的白板页页码，如果不填则默认删除当前页。

返回

true：调用成功。

false：调用失败。

AppsInToolbar 类

AppsInToolbar 类提供管理工具条上插件按钮的方法。

push

push(...data: AppInToolbar[]): void;

在插件中心的末尾添加插件按钮。

该方法支持一次添加多个新的插件按钮，新添加的插件按钮位于插件中心的最后。

参数

• data：插件按钮。详见 AppInToolbar。

示例代码

// 在插件中心添加一个 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(data: AppInToolbar, index: number): void;

在指定位置添加一个插件按钮。

该方法支持一次添加一个新的插件按钮，并支持指定添加的位置。

参数

• data：插件按钮。详见 AppInToolbar。
• index：Number。待添加按钮在插件中心的索引号。取值必须大于等于 0。

delete

delete(filter: (data: AppInToolbar) => boolean): void;

删除指定的插件按钮。

参数

• filter：filter() 方法，返回所有需要被删除的按钮组件。你需要在该方法中传入一个回调函数，用于筛选出需要删除的插件按钮。
  • data：插件按钮。详见 AppInToolbar。

clear

clear(): void;

删除所有插件按钮。

该方法可以删除插件中心的所有按钮，但不能删除白板工具条上的插件中心（apps）按钮。如果你需要隐藏白板工具条上的插件按钮，可以通过 mount 方法的 options 参数将 config.toolbar.apps.enable 设为 false。

类型定义

AppInToolbar

插件按钮。

interface AppInToolbar {
 kind: string;
 icon: string;
 label: string;
 onClick: (app: FastboardApp) => void;
}

AppInToolbar 包含如下属性：

• kind：String。插件按钮的唯一标识符。可以是任意字符串。
• icon：String。按钮图标的 URL 地址。
• label：String。按钮的标题，即显示在按钮下方的文字。建议长度不超过 12 个英文字符，否则文字会显示不全。
• onClick：点击按钮时触发的回调：
  • app：FastboardApp 对象。

ApplianceNames

ApplianceNames 包含以下枚举值：

selector = "selector"

选择工具。

clicker = "clicker"

点击工具。目前主要用于点击 HTML5 文件上的内容。

laserPointer = "laserPointer"

激光笔。

pencil = "pencil"

铅笔。

rectangle = "rectangle"

矩形工具。

ellipse = "ellipse"

椭圆工具。

shape = "shape"

图形工具。

eraser = "eraser"

橡皮工具。

text = "text"

文字工具。

straight = "straight"

直线工具。

arrow = "arrow"

箭头工具。

hand = "hand"

抓手工具。

Camera

Camera 接口包含以下属性：

• centerX：Number。网页元素的中心在白板坐标系（以网页元素的中心为原点的坐标系）中的 X 轴坐标。默认值为 0。
• centerY：Number。网页元素中心在白板坐标系（以网页元素的中心为原点的坐标系）中的 Y 轴坐标。默认值为 0。
• scale：Number。视角的缩放比例，默认值为 1，即缩放比例为 100%。

Color

Color：Number[]。颜色，格式为 RGB。例如 [0, 0, 255] 代表蓝色。

FastboardOptions

FastboardOptions 接口包含以下属性：

• sdkConfig: （必需）Object。WhiteWebSdk 实例的配置，必须传入以下参数：
  • appIdentifier：String。互动白板项目的 App Identifier。详见获取互动白板项目的安全密钥。
  • region：String。数据中心，必须与创建房间时设置的数据中心一致。取值如下：
    • cn-hz：中国杭州，服务区覆盖其他数据中心未覆盖的地区。
    • us-sv：美国硅谷，服务区覆盖北美洲、南美洲。
    • sg：新加坡，服务区覆盖新加坡、东亚、东南亚。
    • in-mum：印度孟买，服务区覆盖印度。
    • eu：欧洲（法兰克福），服务区覆盖欧洲。
• joinRoom: Object。（必需）调用 joinRoom 加入房间的参数设置，必须传入以下参数：
  • uid: String。用户的 UID，即用户的唯一标识符，字符串格式，不能超过 1024 字节。请确保同一房间内每个用户的 uid 唯一。
  • uuid: String。房间的 UUID，即房间的唯一标识符。详见创建房间请求成功后响应包体中 uuid 参数的值。
  • roomToken: String 型。房间的 Room Token，用于加入房间时的用户鉴权。可以通过以下方式获取：
    • 调用生成 Room Token RESTful API。
    • 在 app 服务端用代码生成，详见在 app 服务端生成 Token。
• managerConfig: （可选）Object。WindowManager 配置选项。
• netlessApps：（可选）Object。官方内置或自定义的 Fastboard 插件，详见注册和使用 Fastboard 插件。

FastboardProps

export declare interface FastboardProps {
 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。

FastboardUIConfig

白板用户界面上的组件配置。

type FastboardUIConfig = { toolbar?: { enable?: boolean; apps?: { enable?: boolean } }; redo_undo?: { enable?: boolean }; zoom_control?: { enable?: boolean }; page_control?: { enable?: boolean }; }

FastboardUIConfig 接口包含以下属性：

• toolbar：（可选）工具条：
  • enable：（可选）是否在白板用户界面上展示工具条：
    • true：（默认）展示。
    • false：不展示。
  • apps：（可选）插件中心：
    • enable：（可选）是否在工具条上展示插件中心：
      • true：（默认）展示。
      • false：不展示。
• redo_undo：（可选）重做和撤销按钮：
• enable：（可选）是否在白板用户界面上展示重做和撤销按钮：
  • true：（默认）展示。
  • false：不展示。
• zoom_control：（可选）缩放控制按钮：
• enable：（可选）是否在白板用户界面上展示缩放控制按钮：
  • true：（默认）展示。
  • false：不展示。
• page_control：（可选）页面控制按钮：
• enable：（可选）是否在白板用户界面上展示页面控制按钮：
  • true：（默认）展示。
  • false：不展示。

InsertDocsDynamic

export interface InsertDocsDynamic {
    readonly fileType: "pptx";
    readonly scenePath: string;
    readonly taskId: string;
    readonly title?: string;
    readonly url?: string;
   }

InsertDocsDynamic 接口包含以下属性：

• fileType: String。文档类型，取值为 "pptx"，表示动态文档。
• scenePath: String。白板场景路径，建议填 "/pptx/uuid"，其中 uuid 为文档转换任务的 UUID，即发起文档转换任务 API 请求成功时响应包体中 uuid 参数的值。
• taskId: String。文档转换任务的 UUID，即发起文档转换任务 API 请求成功时响应包体中 uuid 参数的值。
• title: （可选）String。窗口标题
• url: String。转换后文档的存储路径，例如，"https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/dynamicConvert“。

InsertDocsStatic

export interface InsertDocsStatic {
    readonly fileType: "pdf";
    readonly scenePath: string;
    readonly scenes: SceneDefinition[];
    readonly title?: string;
}

InsertDocsStatic 接口包含以下属性：

• fileType：String。文档类型，取值为 "pdf"，表示静态文档。
• scenePath: String。白板场景路径，建议填 "/pdf/uuid"，其中 uuid 为文档转换任务的 UUID，即发起文档转换任务 API 请求成功时响应包体中 uuid 参数的值。
• scenes: SceneDefinition[]。白板场景内容，即待展示的文档。由多个 object 组成，每个 object 表示一页文件，必须包含如下参数：
  • name：String。场景名字。
  • ppt：PptDescription。PPT 描述，包含以下属性：
    • width：Number。文件的宽度，单位为像素。
    • height：Number。文件的高度，单位为像素。
    • src：String。该页文件的 URL 地址，即查询文档转换任务进度 API 返回的响应包体中 conversionFileUrl 字段的值。
• title: （可选）String。窗口标题。

MountProps

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。

Rectangle

Rectangle 接口包含以下属性：

• originX：Number。矩形左上角在白板坐标系（以网页元素的中心为原点的坐标系）中的 X 轴坐标。
• originY：Number。矩形左上角在白板坐标系（以网页元素的中心为原点的坐标系）中的 Y 轴坐标。
• width：矩形的宽度（px）。
• height：矩形的高度（px）。

ReplayUI

回放模式的一套 UI 组件。

export interface ReplayUI {
  mount(div: Element, props?: ReplayFastboardProps): ReplayUI;
  update(props?: ReplayFastboardProps): void;
  destroy(): void;
}

ReplayUI 组件包含以下函数：

• mount: 挂载白板 UI 到 HTML 元素上。
  • div：HTML Element。容纳白板应用的网页元素。
  • props: Object。UI 配置选项，详见 FastboardProps。
• update: 用于 UI 配置变更后，更新 Fastboard UI。
  • props: Object。UI 配置选项，详见 FastboardProps。
• destroy: 移除 UI。

ShapeType

ShapeType 包含以下枚举值：

Triangle = "triangle"

三角形。

Rhombus = "rhombus"

菱形。

Pentagram = "pentagram"

五角星。

SpeechBalloon = "speechBalloon"

对话气泡。

UI

Fastboard 内置的一套 UI 组件。

export interface UI {
 mount(div: Element, props?: FastboardProps): UI;
 update(props?: FastboardProps): void;
 destroy(): void;
}

UI 组件包含以下函数：

• mount: 挂载白板 UI 到 HTML 元素上。
  • div：HTML Element。容纳白板应用的网页元素。
  • props: Object。UI 配置选项，详见 FastboardProps。
• update: 用于 UI 配置变更后，更新 Fastboard UI。
  • props: Object。UI 配置选项，详见 FastboardProps。
• destroy: 移除 UI。