Agora Interactive Whiteboard Web SDK API Reference

Type aliases

BroadcastState

BroadcastState: { broadcasterId?: number; mode: ViewMode }

视角状态，包含视角为主播模式的用户信息。

• broadcasterId?: number

  主播模式用户的用户 ID。若没有主播模式的用户，则为 undefined。

• mode: ViewMode

  用户的视角模式。

Camera

Camera: { centerX: number; centerY: number; scale: number }

视角的描述。

• centerX: number

  视角的中心点在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 X 轴坐标。

• centerY: number

  视角的中心点在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 Y 轴坐标。

• scale: number

  视角的缩放比例。

CameraBound

CameraBound: { centerX?: number; centerY?: number; damping?: number; height?: number; maxContentMode?: ContentMode; minContentMode?: ContentMode; width?: number }

CameraBound 类型用于设置视角边界。
视角边界是白板上用户可以看见的部分。在视角边界内，用户可以自由移动和缩放视角。视角如果超出了视角边界的范围，会被 SDK 拉回视角边界内。

• centerX?: number

  视角边界的中心点在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 X 轴坐标，默认值是 0.0。

• centerY?: number

  视角边界的中心点在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 Y 轴坐标，默认值是 0.0。

• damping?: number

  用户将视角移出视角边界时感受到的阻力大小。取值范围为 [0.0,1.0]，默认值为 0.75。取值越大，用户感受到的阻力越大。

  • 0.0: 用户将视角移出视角边界时，完全感受不到阻力，但当其手指离开屏幕时，视角会恢复到原位。

  • 1.0: 用户完全无法将视角移出视角边界。

• height?: number

  视角边界的高度，单位为像素。默认值是 Infinity，表示没有限制。

• maxContentMode?: ContentMode

  视角边界的最大缩放比例。如果不填，则表示视角缩放没有上限。

• minContentMode?: ContentMode

  视角边界的最小缩放比例。如果不填，则表示视角缩放没有下限。

• width?: number

  视角边界的宽度，单位为像素。默认值是 Infinity，表示没有限制。

CameraState

CameraState: Camera & { height: number; width: number }

since

2.10.0
视角状态。该类型继承 Camera 且增加以下属性：

• width: number
  视角的宽。

• height: number
  视角的高。

Color

Color: number[]

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

ConstructRoomParams

ConstructRoomParams: { cameraBound?: CameraBound; commandWheelToZoom?: boolean; cursorAdapter?: CursorAdapter | false; disableAutoResize?: boolean; disableCameraTransform?: boolean; disableOthersSelectingBox?: boolean; invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>; wrappedComponents?: WrappedComponents }

Room 对象和 Room 对象共用的参数配置。

• cameraBound?: CameraBound

  设置视角边界，即用户可以自由移动视角的范围。默认值为 undefined，表示视角没有任何限制。

• commandWheelToZoom?: boolean

  是否允许按住 command 键并滑动鼠标滚轮来放大或缩小白板。

  since

  2.16.51

  • true：允许按住 command 键并滚动来放大缩小白板。

  • false：(默认)不允许按住 command 键并滚动来放大缩小白板。

  note

  • 该属性仅使用于 macOS 系统。

  • 该属性不影响 control 滚轮的放大缩小行为。

• cursorAdapter?: CursorAdapter | false

  设置鼠标的光标适配器，详见 《鼠标光标适配器》。 设置为 false 将不再显示内部预设光标 (激光笔、橡皮擦等)。

• disableAutoResize?: boolean

  是否关闭自动适配尺寸功能。

  • true：关闭自动适配尺寸功能。关闭后，如果视角的尺寸发生改变，必须主动调用 refreshViewSize 来保证适配。

  • false：（默认）启用自动适配尺寸功能。

• disableCameraTransform?: boolean

  是否禁止用户通过触屏手势或鼠标滚轮移动或缩放调整视角。

  • true：禁止用户调整视角。

  • false：（默认）允许用户调整视角。

  该属性不会影响 setCameraBound、moveCamera、moveCameraToContain 方法的使用。

• disableOthersSelectingBox?: boolean

  是否隐藏其他人的鼠标移动到白板组件上时显示的高亮框。

  since

  2.12.0

  • true：隐藏其他人的高亮框。

  • false：显示其他人的高亮框。

  该属性不影响自己的高亮框显示。

• invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>

  不可见插件列表。

• wrappedComponents?: WrappedComponents

  由 React.ComponentType 类型组成的数组，用于自定义包装白板的界面。默认值为 []。

ContentMode

ContentMode: (screenSize: Size, boundSize: Size) => number

实时缩放比例。

param

屏幕的尺寸。

param

视角边界的尺寸。

returns

根据 screenSize 和 boundSize 计算出来的缩放比例。

ConvertedFile

ConvertedFile: { conversionFileUrl: string; height: number; preview?: string; width: number }

转换后生成的图片或动态 PPT 页。

• conversionFileUrl: string

  图片的 URL 地址或动态 PPT 页的 URI 地址。

• height: number

  图片或动态 PPT 页在白板中的高度，单位为像素。

• preview?: string

  图片或动态 PPT 预览图的 URL 地址。

• width: number

  图片或动态 PPT 页在白板中的宽度，单位为像素。

CursorDescription

CursorDescription: { height: number; width: number; x: number; y: number }

光标的描述。

• height: number

  光标图形的高。

• width: number

  光标图形的宽。

• x: number

  光标指示区域中心的 X 轴坐标（以光标图形的左上角为原点）。

• y: number

  光标指示区域中心的 Y 轴坐标（以光标图形的左上角为原点）。

DisplayerCallbacks

DisplayerCallbacks: { onBackgroundError: (url: string) => void; onCatchErrorWhenAppendFrame: (userId: number, error: Error) => void; onCatchErrorWhenRender: (error: Error) => void; onEnableWriteNowChanged: (enableWriteNow: boolean) => void; onHandToolActive: (active: boolean) => void; onPPTMediaPause: (shapeId: string, type: MediaType) => void; onPPTMediaPlay: (shapeId: string, type: MediaType) => void; onPPTMediaPlayError: (shapeId: string, type: MediaType, error: Error) => void; onRenderDuration: (renderDuration: number) => void; onSliceChanged: (slice: string) => void }

Displayer 对象的回调。

• onBackgroundError: (url: string) => void

  加载背景图片失败回调。

• onCatchErrorWhenAppendFrame: (userId: number, error: Error) => void

  同步用户行为发生错误的回调。

  • userId: number

  该用户的用户 ID。

  • error: Error

  错误信息。

• onCatchErrorWhenRender: (error: Error) => void

  渲染发生错误回调。

  • error: Error

  错误信息。

• onEnableWriteNowChanged: (enableWriteNow: boolean) => void

  用户的可写权限发生改变的回调。

  since

  2.10.0

  • enableWriteNow: boolean

  用户当前是否有写的权限：

  • true：有写的权限。

  • false：没有写的权限。

• onHandToolActive: (active: boolean) => void

  抓手工具的启用状态发生改变的回调。

  • active: boolean

  抓手工具是否启用:

  • true：启用。

  • false：不启用。

• onPPTMediaPause: (shapeId: string, type: MediaType) => void

  暂停播放动态 PPT 中媒体文件的回调。

  • shapeId: string

  插入媒体文件的 shape 对象的 ID。

  • type: MediaType

  媒体文件的类型。

• onPPTMediaPlay: (shapeId: string, type: MediaType) => void

  播放动态 PPT 中媒体文件的回调。

  • shapeId: string

  插入媒体文件的 shape 对象的 ID。

  • type: MediaType

  媒体文件的类型。

• onPPTMediaPlayError: (shapeId: string, type: MediaType, error: Error) => void

  动态 PPT 中的媒体文件播放出错回调。

  • shapeId: string

  插入媒体文件的 shape 对象的 ID。

  • type: MediaType

  媒体文件的类型。

  • error: Error

  错误提示。

• onRenderDuration: (renderDuration: number) => void

  渲染时长回调。

  • renderDuration: number

  渲染时长。

• onSliceChanged: (slice: string) => void

  所处分片发生改变的回调。

  • slice: string

  所处分片的 UUID。

DisplayerState

DisplayerState: { cameraState: CameraState; globalState: GlobalState; roomMembers: ReadonlyArray<RoomMember>; sceneState: SceneState }

DisplayerState 是 Room 对象和 Player 对象共有的类型。

• cameraState: CameraState

  当前视角的状态。

  since

  2.10.0

• globalState: GlobalState

  房间的全局状态。详见 GlobalState。

• roomMembers: ReadonlyArray<RoomMember>

  房间内所有互动模式（具有读写权限）用户的状态。

• sceneState: SceneState

  当前场景的状态。

Event

Event: { authorId: number; event: string; payload: any; phase: EventPhase; scope: Scope }

自定义事件。

• authorId: number

  事件触发者的用户 ID，若是系统事件，则为 AdminObserverId。

• event: string

  自定义事件的名称。

• payload: any

  自定义事件的内容。

• phase: EventPhase

  自定义事件的状态。

• scope: Scope

  自定义事件的范围。

EventFilter

EventFilter: (event: Event) => boolean

事件过滤器。

EventListener

EventListener: (event: Event) => void

事件监听器。

EventsListener

EventsListener: (events: Event[]) => void

事件组监听器。

FloatBarOptions

FloatBarOptions: { colors: ReadonlyArray<Readonly<Color>> }

悬浮条的配置参数。

• colors: ReadonlyArray<Readonly<Color>>

  悬浮条调色盘的颜色列表。

GlobalState

GlobalState: {}

实时房间的公共全局变量。
房间内所有用户看到的都是相同的 globalState，所有互动模式用户都可以读写。修改 globalState 属性会立即生效并同步给所有用户。

HotKey

HotKey: string | HotKeyDescription | ReadonlyArray<string | HotKeyDescription> | HotKeyChecker

自定义快捷键。

HotKeyChecker

HotKeyChecker: (event: HotKeyEvent, kind: KeyboardKind) => boolean

快捷键检查器。

param

自定义快捷键的事件。

param

键盘的类型。

returns

是否为指定的快捷键：

• true：是指定的快捷键。

• false：不是指定的快捷键。

HotKeyDescription

HotKeyDescription: { altKey: boolean | null; ctrlKey: boolean | null; key: string; shiftKey: boolean | null }

自定义快捷键的描述。

• altKey: boolean | null

  是否使用 Alt 键。

• ctrlKey: boolean | null

  是否使用 Ctrl 键。 C

• key: string

  指定的键。

• shiftKey: boolean | null

  是否使用 Shift 键。

HotKeyEvent

HotKeyEvent: { altKey: boolean; ctrlKey: boolean; key: string; kind: "KeyDown" | "KeyUp"; nativeEvent?: KeyboardEvent; shiftKey: boolean }

自定义快捷键的事件。

• altKey: boolean

  是否使用 Alt 键。

• ctrlKey: boolean

  是否使用 Ctrl 键。

• key: string

  指定的键。

• kind: "KeyDown" | "KeyUp"

  快捷键的事件类型。

  • KeyDown：键被按下。

  • KeyUp：键被松开。

• nativeEvent?: KeyboardEvent

  浏览器的原生事件。

• shiftKey: boolean

  是否使用 Shift 键。

HotKeys

HotKeys: { changeToArrow: HotKey; changeToClick: HotKey; changeToEllipse: HotKey; changeToEraser: HotKey; changeToHand: HotKey; changeToLaserPointer: HotKey; changeToPencil: HotKey; changeToRectangle: HotKey; changeToSelector: HotKey; changeToStraight: HotKey; changeToText: HotKey; copy: HotKey; delete: HotKey; duplicate: HotKey; lock: HotKey; paste: HotKey; redo: HotKey; undo: HotKey }

快捷键对应的效果。

• changeToArrow: HotKey

  切换到箭头工具（arrow）。

• changeToClick: HotKey

  切换到点选工具 (clicker)。

• changeToEllipse: HotKey

  切换到椭圆工具（ellipse）。

• changeToEraser: HotKey

  切换到橡皮工具（eraser）。

• changeToHand: HotKey

  切换到抓手工具（hand）。

• changeToLaserPointer: HotKey

  切换到激光笔（laserPointer）。

• changeToPencil: HotKey

  切换到铅笔工具（pencil）。

• changeToRectangle: HotKey

  切换到矩形工具（rectangle）。

• changeToSelector: HotKey

  切换到选择工具（selector）。

• changeToStraight: HotKey

  切换到直线工具（straight）。

• changeToText: HotKey

  切换到文字工具（text）。

• copy: HotKey

  复制。

• delete: HotKey

  删除。

• duplicate: HotKey

  复制并粘贴。

• lock: HotKey

  锁定缩放比例。

• paste: HotKey

  粘贴。

• redo: HotKey

  重做。

• undo: HotKey

  撤回。

Identifier

Identifier: string

组件插件的唯一标识符。

ImageInformation

ImageInformation: { centerX: number; centerY: number; crossOrigin?: boolean | string; height: number; locked: boolean; uniformScale?: boolean; uuid: string; width: number }

图片的描述。

• centerX: number

  图片的中心在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 X 轴坐标。

• centerY: number

  图片的中心在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 Y 轴坐标。

• crossOrigin?: boolean | string

  是否以跨域方式加载图片。

  since

  2.16.48

  • true: （默认）以跨域方式加载图片。

  • false: 不以跨域方式加载图片。

• height: number

  图片的高度，单位为像素。如果图片的高度超出视角的边界，用户将看不到超出部分。

• locked: boolean

  图片是否被锁定。

  • true: 图片被锁定。锁定一张图片后，用户无法移动或缩放该图片。

  • false: 图片没有被锁定。

• uniformScale?: boolean

  图片是否只能等比放缩。

  since

  2.12.0

  • true: 只能等比缩放。

  • false: 可以非等比缩放。

• uuid: string

  图片的 UUID，即图片在互动白板实时房间中的唯一标识符。

• width: number

  图片的宽度，单位为像素。如果图片的宽度超出视角的边界，用户将看不到超出部分。

International

International: { displayNote?: string; displaySidebar?: string; hideNote?: string; hideSidebar?: string; jumpTo?: string; nextPage?: string; nextStep?: string; pageNumber?: string; prePage?: string; preStep?: string; resetCurrentPPTAnimation?: string; resetCurrentSlideAnimation?: string }

International 类，用于添加 PPT 预览菜单栏的界面文字。你可以直接传入要展示的文字，例如 “Next”。

• displayNote?: string

  “显示 PPT 备注”的界面文字。

• displaySidebar?: string

  “显示侧边栏”的界面文字。

• hideNote?: string

  “隐藏 PPT 备注”的界面文字。

• hideSidebar?: string

  “隐藏侧边栏”的界面文字。

• jumpTo?: string

  “跳转到”的界面文字。

• nextPage?: string

  “下一页”的界面文字。

• nextStep?: string

  “下一步”的界面文字。

• pageNumber?: string

  “页码”的界面文字。

• prePage?: string

  “上一页”的界面文字。

• preStep?: string

  “上一步”的界面文字。

• resetCurrentPPTAnimation?: string

  “重置当前 PPT 文件的动画”的界面文字。

• resetCurrentSlideAnimation?: string

  “重置当前 PPT 页的动画”的界面文字。

InvisibleCallbacks

InvisibleCallbacks<A>: { onAttributesUpdate: (attributes: A) => void; onDestroy: () => void }

不可见插件的回调事件。

• onAttributesUpdate: (attributes: A) => void

  不可见插件属性更新的回调。

  • attributes: A

  更新的插件属性。

• onDestroy: () => void

  删除不可见插件的回调。

InvisiblePluginClass

InvisiblePluginClass<K, A, P>: { kind: K; onCreate?: (plugin: P) => void; onDestroy?: (plugin: P) => void }

不可见插件。

• kind: K

  插件的类型。

• onCreate?: (plugin: P) => void

  创建插件对象的回调。

  • plugin: P

  创建的插件对象。

• onDestroy?: (plugin: P) => void

  删除插件对象的回调。

  • plugin: P

  删除的插件对象。

InvisiblePluginContext

InvisiblePluginContext: { displayer: Displayer; kind: string }

不可见插件的上下文。

• displayer: Displayer

  不可见插件的 Displayer 对象。

• kind: string

  不可见插件的类型。

JoinRoomParams

JoinRoomParams: ConstructRoomParams & { disableDeviceInputs?: boolean; disableEraseImage?: boolean; disableMagixEventDispatchLimit?: boolean; disableNewPencil?: boolean; disablePencilWrittingLimitFrequency?: boolean; enableDrawPoint?: boolean; floatBar?: boolean | Partial<FloatBarOptions>; hotKeys?: Partial<HotKeys>; isWritable?: boolean; newPencilWritingQuality?: NewPencilWritingQuality; optimizeOptions?: OptimizeOptions; region?: string; rejectWhenReadonlyErrorLevel?: RoomErrorLevel; roomToken: string; uid: string; userPayload?: {}; uuid: string }

Room 对象的参数设置，用于加入互动白板实时房间。该类型继承 ConstructRoomParams 且包含以下属性：

• uuid: string
  房间的 UUID，即房间的唯一标识符。成功创建房间后会返回该属性。

• uid: string
  用户的 UID，即用户的唯一标识符，字符串格式，不能超过 1024 字节。请确保同一房间内每个用户 uid 的唯一性。

• region?: string
  连接的数据中心，支持传入以下值：

region	数据中心	服务区
us-sv	美国硅谷	北美洲、南美洲
sg	新加坡	新加坡、东亚、东南亚
in-mum	印度孟买	印度
eu	欧洲（法兰克福）	欧洲
cn-hz	中国杭州	其他数据中心服务区未覆盖的地区

Note

• 该属性必须与要加入的互动白板实时房间所在数据中心一致，否则无法加入房间。

• 该属性与 WhiteWebSdkConfiguration 中的 region 作用相同，二者只需要设置其中一个。如果同时设置，该属性会覆盖 WhiteWebSdkConfiguration 中的 region。

• roomToken: string
  房间的 Room Token，用于加入房间时的用户鉴权。详见互动白板 Token 概述。

• userPayload?: {[key: string]: any;}
  自定义用户信息。该属性可以是任意类型的数据结构。
  房间内其他用户可以通过如下代码读取特定用户在加入房间时设置的 userPayload：

example

JavaScript

for (var member of room.state.roomMembers) {
    // 读取房间内某个用户的 userPayload 字段
    console.log(member.userPayload);
}  

• isWritable?: boolean
  用户在房间中是否为互动模式（具有读写权限）。

  • true： （默认）互动模式，即具有读写权限。

  • false：订阅模式，即具有只读权限。
    该方法与 disableDeviceInputs 的区别详见 《只读模式｜禁止操作》。

• disableDeviceInputs?: boolean
  是否禁止用户通过鼠标、键盘、触摸屏幕操作白板工具。

  • true： 禁止用户操作白板工具。

  • false：（默认）允许用户操作白板工具。
    该方法与 isWritable 的区别详见《禁止设备操作｜禁止操作》。

• enableDrawPoint?: boolean
  是否允许使用铅笔工具（pencil）画点。

  • true： 允许。

  • false：（默认）不允许。此时使用铅笔工具单击白板绘制的点不会保留在屏幕上。

Note
该属性只有在 disableNewPencil 设为 false 时生效。

• disableNewPencil?: boolean
  自从：2.12.5
  关闭/开启新铅笔工具：

  • true:（默认）关闭新铅笔工具。

  • false: 开启新铅笔工具。开启后，SDK 会对铅笔工具（pencil）应用新版笔迹平滑算法，使书写笔迹更加流畅自然，并带有笔锋效果。

Note
为正常显示笔迹，在开启新铅笔前，请确保该房间内的所有用户使用如下 SDK：

• Android SDK 2.12.3 或更高版本

• iOS SDK 2.12.3 或更高版本

• Web SDK 2.12.5 或更高版本

• disableMagixEventDispatchLimit?: boolean
  自从：2.15.0
  是否关闭发送自定义事件的频率限制：

  • true：关闭频率限制。可能会出现卡顿。

  • false：（默认）开启频率限制。开启后，SDK 每隔 75 ms 发送一个事件。

• disableEraseImage?: boolean
  是否禁止橡皮擦除白板上的图片：

  • true： 禁止擦除。

  • false：（默认）允许擦除。

• disablePencilWrittingLimitFrequency?: boolean
  自从：2.15.2
  使用 pencil 书写时，是否关闭笔迹同步的频率限制：

  • true：关闭频率限制。笔迹会立即同步，但是可能会增加 CPU 性能消耗。

  • false：（默认）开启频率限制。笔迹同步会有轻微延迟，但是可以降低 CPU 性能消耗。

• floatBar?: boolean | Partial
  当 currentApplianceName 设为 selector 或 text 时，是否出现浮动条：

  • true： 出现浮动条。

  • false：（默认）不出现浮动条。

• hotKeys?: Partial
  添加自定义快捷键。若不传，则使用默认快捷键键方案，具体如下：

键盘按键	效果
Backspace 或 Delete	删除所选对象
Shift	锁定放缩长宽比，令其等比放缩
Ctrl + Z 或 Command + Z	撤回
Ctrl + Y 或 Command + Y	重做
Ctrl + C 或 Command + C	复制
Ctrl + V 或 Command + V	粘贴

如果你想关闭快捷键功能，可以将该属性的其值设为 {}。

• rejectWhenReadonlyErrorLevel?: RoomErrorLevel
  没有可写权限的用户进行写操作时，SDK 的应对方式。

• optimizeOptions?: OptimizeOptions

since

2.16.48
白板绘制性能优化选项。详见 OptimizeOptions。

Level

Level: "debug" | "info" | "warn" | "error"

日志等级。

since

2.11.8
日志级别由高到低的排序为 error，warn，info，和 debug。选择一个级别，你就可以看到不低于该级别的所有日志信息。 例如，选择 info 级别，就可以看到 error、warn、info 级别的所有日志信息。

• error：报错日志，表明出现了直接导致 SDK 无法正常运行的错误。

• warn：警告日志。当传入的参数不符合 SDK 要求时，SDK 会自动调整并发出警告。如果调用废弃 API，SDK 不会发出警告信息。

• info：信息日志，主要为连接状态。

• debug：调试日志，最详细的日志，目前内容与 info 一致。

LoggerOptions

LoggerOptions: { printLevelMask?: Level; reportDebugLogMode?: LoggerReportMode; reportLevelMask?: Level; reportQualityMode?: LoggerReportMode }

日志的配置参数。

• printLevelMask?: Level

  日志打印等级，详见 Level。默认等级为 info。

• reportDebugLogMode?: LoggerReportMode

  SDK 上报 debug 等级日志的模式。

• reportLevelMask?: Level

  日志上报等级，详见 Level。

• reportQualityMode?: LoggerReportMode

  SDK 上报连接质量数据的模式。

MagixEventListenerOptions

MagixEventListenerOptions: { fireInterval?: number; fireSelfEventAfterCommit?: boolean }

自定义事件监听选项。

since

v2.15.2

• fireInterval?: number

  SDK 触发自定义事件回调的间隔，单位为毫秒，默认值为 500。取值必须 ≥ 500。
  SDK 会根据该参数的值周期性触发自定义事件回调。

• fireSelfEventAfterCommit?: boolean

  设置是否待服务器确认 dispatchMagixEvent 方法调用成功后再发送事件回调：

  • true：调用 dispatchMagixEvent 后立即触发事件回调。

  • false：（默认）待服务器确认事件发送成功后再发送事件回调。

Margin

Margin: { bottom: number; left: number; right: number; top: number }

空白区域的设置。

• bottom: number

  下方的空白，单位为像素。

• left: number

  左边的空白，单位为像素。

• right: number

  右边的空白，单位为像素。

• top: number

  上方的空白，单位为像素。

MediaType

MediaType: "video" | "audio"

媒体文件的类型。

• video：视频文件。

• audio：音频文件。

MemberInformation

MemberInformation: { id: number; payload: any; session: string }

自定义用户信息。

deprecated

已废弃。请改用 JoinRoomParams 中的 userPayload。

• id: number

• payload: any

• session: string

MemberState

MemberState: { arrowCompleteToSelector?: boolean; bold?: boolean; currentApplianceName: ApplianceNames; dottedLine?: boolean; ellipseCompleteToSelector?: boolean; fillColor?: Color; italic?: boolean; lineThrough?: boolean; rectangleCompleteToSelector?: boolean; shapeCompleteToSelector?: boolean; shapeType?: ShapeType; straightCompleteToSelector?: boolean; strokeColor: Color; strokeWidth: number; textCanSelectText?: boolean; textColor?: Color; textCompleteToSelector?: boolean; textSize: number; textSizeOverride?: number; underline?: boolean }

互动白板实时房间的白板工具状态。

• arrowCompleteToSelector?: boolean

  是否在画完箭头后自动切到选择工具：

  • true：自动切换。

  • false：（默认）不自动切换。

• bold?: boolean

  是否加粗：

  • true：加粗。

  • false：（默认）不加粗。

• currentApplianceName: ApplianceNames

  当前使用的白板工具名称，详见 ApplianceNames。

• dottedLine?: boolean

  是否支持绘制虚线（仅限铅笔工具）：

  • true：支持绘制虚线。

  • false：（默认）不支持绘制虚线。

• ellipseCompleteToSelector?: boolean

  是否在画完圆形后自动切到选择工具：

  • true：自动切换。

  • false：（默认）不自动切换。

• fillColor?: Color

  设置图形元素的填充色。仅适用于圆、矩形等封闭图形。

• italic?: boolean

  是否使用斜体：

  • true：使用斜体。

  • false：（默认）不使用斜体。

• lineThrough?: boolean

  是否加删除线：

  • true：加删除线。

  • false：（默认）不加删除线。

• rectangleCompleteToSelector?: boolean

  是否在画完矩形后自动切到选择工具：

  • true：自动切换。

  • false：（默认）不自动切换。

• shapeCompleteToSelector?: boolean

  是否在画完三角、气泡等图形后自动切到选择工具：

  • true：自动切换。

  • false：（默认）不自动切换。

• shapeType?: ShapeType

  绘制图形的类型。

• straightCompleteToSelector?: boolean

  是否在画完直线后自动切到选择工具：

  • true：自动切换。

  • false：（默认）不自动切换。

• strokeColor: Color

  绘制线条的颜色，为 RGB 格式，例如 [0, 0, 255] 表示蓝色。

• strokeWidth: number

  绘制线条的粗细。

• textCanSelectText?: boolean

  是否允许直接选择并编辑文字：

  • true：允许直接选择并编辑文字。

  • false：（默认）不允许直接选择并编辑文字。

• textColor?: Color

  字体颜色，为 RGB 格式，例如 [0, 0, 255] 表示蓝色。

• textCompleteToSelector?: boolean

  是否在使用文字工具打完字后自动切到选择工具：

  • true：自动切换。

  • false：（默认）不自动切换。

• textSize: number

  字体大小，取值必须大于 0。Chrome 浏览器对于小于 12 的字体会自动调整为 12。

• textSizeOverride?: number

  设置文本工具的默认字体大小。如果不设置则默认使用 textSize，即上一次设置的文字大小。

• underline?: boolean

  是否加下划线：

  • true：加下划线。

  • false：（默认）不加下划线。

NativeEvent

NativeEvent: MouseEvent | WheelEvent | KeyboardEvent | TouchEvent

浏览器的原生事件。

• MouseEvent：鼠标事件，详见 MouseEvent。

• WheelEvent：滚轮事件，详见 WheelEvent。

• KeyboardEvent：键盘事件，详见 KeyboardEvent。

• TouchEvent：触摸事件，详见 TouchEvent。

PlayableCheckingParams

PlayableCheckingParams: { beginTimestamp?: number; duration?: number; region?: string; room: string; roomToken: string; slice?: string }

检查白板房间是否可以回放的参数配置。

• beginTimestamp?: number

  回放的起始时间（单位为毫秒的 Unix 时间戳）。
  该属性必须和 room、duration 一起使用，而且使用时禁止传入 slice。

• duration?: number

  回放的时长（毫秒）。
  该属性必须和 room、beginTimestamp 一起使用，而且使用时禁止传入 slice。

• region?: string

  当前房间所在的数据中心，支持传入以下值：

  region	数据中心	服务区
  us-sv	美国硅谷	北美洲、南美洲
  sg	新加坡	新加坡、东亚、东南亚
  in-mum	印度孟买	印度
  eu	欧洲（法兰克福）	欧洲
  cn-hz	中国杭州	其他数据中心服务区未覆盖的地区

• room: string

  房间的 UUID，即房间的唯一标识符。成功创建房间后会返回该值。

  • 如果只传该属性，不传 beginTimestamp 和 duration，则表明回放该房间的所有录像片段。

  • 如果同时传入该属性和 beginTimestamp、duration，则表明回放该房间在对应时间范围内的所有录像片段。

• roomToken: string

  房间的 Room Token，用于加入房间时的用户鉴权。详见互动白板 Token 概述。

• slice?: string

  回放的录像片段的 UUID。你可以在房间录制的时候从 room.slice 获取。
  Note

  • 该属性需要和 room 同时传入。

  • 传入该属性表明只回放特定片段，因此禁止再传入 beginTimestamp 和 duration。

PlayerCallbacks

PlayerCallbacks: DisplayerCallbacks & { onIsPlayableChanged: (isPlayable: boolean) => void; onLoadFirstFrame: () => void; onPhaseChanged: (phase: PlayerPhase) => void; onPlayerStateChanged: (modifyState: Partial<PlayerState>) => void; onProgressTimeChanged: (progressTimestamp: number) => void; onStoppedWithError: (error: Error) => void }

PlayerCallbacks 包含白板回放的事件回调。该类型继承 DisplayerCallbacks 且包含以下成员：

• onIsPlayableChanged: (isPlayable: boolean)=>void
  isPlayable 发生改变的回调。

param

isPlayable 是否能立即播放：

• true：可以立即播放。

• false：不能立即播放。

• onPhaseChanged: (phase: PlayerPhase)=>void
  回放阶段发生改变的回调。

param

phase 回放阶段。

• onLoadFirstFrame: ()=>void
  首帧加载完成的回调。

• onPlayerStateChanged: (modifyState: Partial)=>void
  回放状态发生改变的回调。

param

modifyState 回放状态。

• onStoppedWithError: (error: Error)=>void
  出错导致回放暂停的回调。

param

error 错误信息。

• onProgressTimeChanged: (progressTimestamp: number)=>void
  回放进度发生改变的回调。

param

progressTimestamp 回放进度。

PlayerState

PlayerState: DisplayerState & { observerMode: ObserverMode }

Player 对象的状态。该类型继承 DisplayerState 且包含以下成员：

• observerMode: ObserverMode

白板回放的观看模式，详见 ObserverMode。

Plugin

Plugin<C, T>: { defaultAttributes?: T; hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean; kind?: string; render: ComponentType<PluginProps<C, T>>; willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean }

组件插件的描述。Agora 支持的自定义插件包括组件插件和不可见插件。

• defaultAttributes?: T

  属性的默认值。

• hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean

  碰撞检测。你可以通过碰撞检测定义组件插件可以被选择工具选中的区域。

  • plugin: PluginInstance<C, T>

  组件插件对象。

  • x: number

  可选中区域的中心点的 X 轴坐标。

  • y: number

  可选中区域的中心点的 Y 轴坐标。

  • selectorRadius: number

  可选中区域的半径。

• kind?: string

  组件插件的类型，即该组件插件的唯一识别符。

• render: ComponentType<PluginProps<C, T>>

  组件插件的外观。

• willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean

  设置是否拦截该组件插件的原生事件。

  • plugin: PluginInstance<C, T>

  组件插件对象。

  • event: NativeEvent

  原生事件。

PluginDescription

PluginDescription<A>: { attributes?: A; height?: number; originX?: number; originY?: number; selectable?: boolean; width?: number }

组件插件对象的描述。

• attributes?: A

  组件插件对象的属性。

• height?: number

  组件插件对象的高。

• originX?: number

  组件插件对象的左上角在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 X 轴坐标。

• originY?: number

  组件插件对象的左上角在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 Y 轴坐标。

• selectable?: boolean

  能否选中组件插件对象：

  • true：能选中。

  • false：不能选中。

• width?: number

  组件插件对象的宽。

PluginProps

PluginProps<C, T>: { margin: Margin; origin: Point; plugin: PluginInstance<C, T>; scale: number; size: Size }

组件插件的外观设置。

• margin: Margin

  组件插件图标周围的空白。

• origin: Point

  组件插件图标的中心点在世界坐标系中（以白板初始化时的中心点为原点的坐标系）的坐标。

• plugin: PluginInstance<C, T>

  组件插件对象。

• scale: number

  组件插件图标的缩放比例。

• size: Size

  组件插件图标的大小。

Point

Point: { x: number; y: number }

世界坐标系（以白板初始化时的中心点为原点的坐标系）的点坐标。

• x: number

  点在世界坐标系中的 X 轴坐标。

• y: number

  点在世界坐标系中的 Y 轴坐标。

PptDescription

PptDescription: { height: number; previewURL?: string; src: string; width: number }

图片或动态 PPT 页的描述。
你可以在初始化 WhiteScene 时配置 PptDescription，以在白板上插入图片或动态 PPT。
支持的图片或动态 PPT 格式包括：

• PNG、JPG/JPEG、WEBP 格式的图片，或由 PPT、PPTX、DOC、DOCX、PDF 格式的文件转换成 PNG、JPG/JPEG、WEBP 格式的图片。

• 使用 文档转换功能转换过的 PPTX 文件。

Note

• 一个场景只能插入一张图片或动态 PPT 页。

• 插入的图片或动态 PPT 页的中心点坐标默认为世界坐标系的原点。图片或动态 PPT 页插入场景后，你无法改变它在白板上的位置。

• height: number

  图片或动态 PPT 在白板中的高度，单位为像素。

• previewURL?: string

  图片或动态 PPT 预览图的 URL 地址。动态 PPT 预览图的 URL 地址可以从查询转换任务进度中的 previews 字段获取，例如，"https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/dynamicConvert/2fdxxxxx67e/preview/1.png"。

• src: string

  图片或动态 PPT 页的地址，支持的格式如下：

  • 图片：URL 地址，可以是你自己生成的 URL 地址，也可以是通过文档转换功能生成的 URL 地址，例如，"https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticConvert/2fdxxxxx67e/1.jpeg"。

  • 动态 PPT 页：通过文档转换功能生成的 URI 地址，例如，"pptx://cover.herewhite.com/dynamicConvert/6a212c90fa5311ea8b9c074232aaccd4/1.slide"。

• width: number

  图片或动态 PPT 在白板中的宽度，单位为像素。

PreviewConfig

PreviewConfig: { international?: International }

PPT 预览页面的配置。

• international?: International

  给预览页面的菜单栏添加界面文字。详见 International。

Progress

Progress: { convertedFileList: ConvertedFile[]; convertedPageSize: number; convertedPercentage: number; currentStep?: CurrentStep; totalPageSize: number }

文档转换任务的进度详情。

• convertedFileList: ConvertedFile[]

  转换后生成的图片或动态 PPT 页。

• convertedPageSize: number

  已转换的页数。

• convertedPercentage: number

  转换进度的百分比。

• currentStep?: CurrentStep

  转换任务当前的步骤。

• totalPageSize: number

  总页数。

RTCClient

RTCClient: { adjustAudioMixingPlayoutVolume?: (volume: number) => number; adjustAudioMixingPublishVolume?: (volume: number) => number; adjustAudioMixingVolume?: (volume: number) => number; getAudioMixingCurrentPosition?: () => number; getAudioMixingDuration?: () => number; getAudioMixingPlayoutVolume?: () => number; getAudioMixingPublishVolume?: () => number; pauseAudioMixing: () => number; resumeAudioMixing: () => number; setAudioMixingPosition: (position: number) => number; startAudioMixing: (filePath: string, loopback: boolean, replace: boolean, cycle: number, callback?: (state: number, errorCode: number) => void) => number; stopAudioMixing: (callback?: (state: number, errorCode: number) => void) => number }

AgoraRTCClient 类用于桥接 Agora RTC SDK 的混音方法和白板 SDK。
当用户同时使用音视频功能和互动白板，且在互动白板中展示的动态 PPT 包含音频文件时，可能遇到以下问题：

• 播放 PPT 内的音频时声音很小。

• 播放 PPT 内的音频时有回声。

为解决上述问题，你可以使用 AgoraRTCClient 类调用 Agora RTC SDK 的混音方法播放动态 PPT 中的音频文件。
Note
目前仅支持 Electron 平台的 Agora RTC SDK.

• adjustAudioMixingPlayoutVolume?: (volume: number) => number

  调节音乐文件的本地播放音量。

  • volume: number

  音乐文件在本端播放的音量。取值范围为 0 到 100 间的整数，默认为 100，即保持原始文件音量。

• adjustAudioMixingPublishVolume?: (volume: number) => number

  调节音乐文件的远端播放音量。

  • volume: number

  音乐文件在远端播放的音量。取值范围为 0 到 100 间的整数，默认为 100，即保持原始文件音量。

• adjustAudioMixingVolume?: (volume: number) => number

  调节音乐文件的播放音量。
  该方法调节混音里伴奏在本端和远端播放的音量。

  • volume: number

  伴奏在本端和远端播放的音量。取值范围为 0 到 100 间的整数，默认为 100，即保持原始文件音量。

• getAudioMixingCurrentPosition?: () => number

  获取音乐文件的播放进度。

• getAudioMixingDuration?: () => number

  获取指定音乐文件的总时长。

• getAudioMixingPlayoutVolume?: () => number

  获取音乐文件的本地播放音量。

• getAudioMixingPublishVolume?: () => number

  获取音乐文件的远端播放音量。

• pauseAudioMixing: () => number

  暂停播放音乐文件及混音。

• resumeAudioMixing: () => number

  恢复播放音乐文件及混音。

• setAudioMixingPosition: (position: number) => number

  设置音乐文件的播放位置。
  该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而不是非得从头到尾播放一个文件。

  • position: number

  设置的播放位置，单位为毫秒，取值必须为整数。

• startAudioMixing: (filePath: string, loopback: boolean, replace: boolean, cycle: number, callback?: (state: number, errorCode: number) => void) => number

  开始播放音乐文件及混音。

  • filePath: string

  指定需要混音的本地或在线音频文件的绝对路径。

  • loopback: boolean

  是否只有本地用户可以听到混音后的音频流：

  • true：只有本地可以听到混音的音频流。

  • false：本地和对方都可以听到混音的音频流。

  • replace: boolean

  是否播放麦克风采集的音频：

  • true： 只播放音频文件，不播放麦克风采集的音频。

  • false: 将音频文件和麦克风采集的音频混音后播放。

  • cycle: number

  音乐文件的播放次数。

  • ≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。

  • -1: 无限循环播放。

  • callback: (state: number, errorCode: number) => void

  开始播放音乐文件及混音的回调。其中 state: number 为音乐文件及混音的播放状态，errorCode: number 为错误码。

• stopAudioMixing: (callback?: (state: number, errorCode: number) => void) => number

  停止播放音乐文件及混音。

  • callback: (state: number, errorCode: number) => void

  停止播放音乐文件及混音的回调。其中 state: number 为音乐文件及混音的播放状态，errorCode: number 为错误码。

ReconnectionOptions

ReconnectionOptions: { disableReconnect: boolean }

断线重连设置。

• disableReconnect: boolean

  是否关闭断线重连：

  • true: 关闭断线重连。

  • false: 开启断线重连。

Rectangle

Rectangle: Size & { originX: number; originY: number }

视觉矩形的描述。该类继承 Size 且包含以下成员：

• originX: number
  视觉矩形左上角原点在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 X 轴坐标。

• originY: number
  视觉矩形左上角原点在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 Y 轴坐标。

RenderPlugin

RenderPlugin<C, T>: { defaultAttributes?: T; hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean; kind: string; render: ComponentType<PluginProps<C, T>>; willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean }

组件插件的渲染。

• defaultAttributes?: T

  组件插件属性的默认值。

• hitTest?: (plugin: PluginInstance<C, T>, x: number, y: number, selectorRadius: number) => boolean

  碰撞检测。你可以通过碰撞检测定义组件插件可以被选择工具选中的区域。

  • plugin: PluginInstance<C, T>

  组件插件对象。

  • x: number

  可选中区域的中心点的 X 轴坐标。

  • y: number

  可选中区域的中心点的 Y 轴坐标。

  • selectorRadius: number

  可选中区域的半径。

• kind: string

  组件插件类型，为该组件插件的唯一识别符。

• render: ComponentType<PluginProps<C, T>>

  组件插件的外观。

• willInterruptEvent?: (plugin: PluginInstance<C, T>, event: NativeEvent) => boolean

  设置是否拦截该组件插件的原生事件。

  • plugin: PluginInstance<C, T>

  组件插件对象。

  • event: NativeEvent

  原生事件。

ReplayRoomParams

ReplayRoomParams: ConstructRoomParams & { alignmentInterval?: number; alignmentThreshold?: number; beginTimestamp?: number; crops?: Array<{ from: number; to: number }>; duration?: number; region?: string; room: string; roomToken: string; slice?: string }

Player 对象的参数配置，用于白板回放。该类型继承 ConstructRoomParams 且增加以下属性：

• region?: string
  Player 对象所在的数据中心。支持传入以下值：

region	数据中心	服务区
us-sv	美国硅谷	北美洲、南美洲
sg	新加坡	新加坡、东亚、东南亚
in-mum	印度孟买	印度
eu	欧洲（法兰克福）	欧洲
cn-hz	中国杭州	其他数据中心服务区未覆盖的地区

Note

• 如果你不设置该属性，SDK 会使用 WhiteWebSdkConfiguration 中 region 的值。

• 如果在初始化 WhiteWebSdk 对象和创建 Player 对象时都没有设置数据中心，SDK 会报错。

• slice?: string
  回放的录像片段的 UUID。你可以在房间录制的时候从 room.slice 获取。
  Note

  • 该属性需要和 room 同时传入。

  • 传入该属性表明只回放特定片段，因此禁止再传入 beginTimestamp 和 duration。

• room: string
  回放房间的 UUID，即房间的唯一标识符。成功创建房间后会返回该值。

  • 如果只传该属性，不传 beginTimestamp 和 duration，则表明回放该房间的所有录像片段。

  • 如果同时传入该属性和 beginTimestamp 和 duration，则表明回放该房间在对应时间范围内的所有录像片段。

• roomToken: string
  房间的 Room Token，用于加入房间时的用户鉴权。详见互动白板 Token 概述。

• beginTimestamp?: number
  白板回放的起始时间（单位为毫秒的 Unix 时间戳）。
  该属性必须和 room、duration 一起使用，而且使用时禁止传入 slice。

• duration?: number
  白板回放的时长（毫秒）。
  该属性必须和 room、beginTimestamp 一起使用，而且使用时禁止传入 slice。

• crops?: Array

since

2.16.48
回放录像裁剪区间，包含以下属性：

• from: number。裁剪区间起点时间戳。

• to: number。裁剪区间终点时间戳。

• alignmentThreshold?: number

since

2.16.48
回放时间轴对齐阈值, 超过此阈值会对齐回放播放器时间, 单位 ms, 默认值为 600 ms。

• alignmentInterval?: number

since

2.16.48
回放时间轴对齐时长, 即在此段时间内，将回放时间通过倍速播放对齐到外部时间戳, 单位 ms, 默认值为 3000 ms。

RoomCallbacks

RoomCallbacks: DisplayerCallbacks & { onCanRedoStepsUpdate: (canRedoSteps: number) => void; onCanUndoStepsUpdate: (canUndoSteps: number) => void; onConnection: (duration: number) => void; onDisconnectWithError: (error: Error) => void; onKeyDown: (event: KeyboardEvent) => void; onKeyUp: (event: KeyboardEvent) => void; onKickedWithReason: (reason: string) => void; onObjectsLimit: (limit: number, soft: boolean) => void; onPhaseChanged: (phase: RoomPhase) => void; onRoomStateChanged: (modifyState: Partial<RoomState>) => void; willInterceptKeyboardEvent: (event: KeyboardEvent) => boolean }

RoomCallbacks 包含白板房间的事件回调。该类型继承 DisplayerCallbacks 并增加以下成员：

• onConnection: (duration: number)=>void
  房间连接成功回调，报告已经建立 WebSocket 连接，将要进入初始化阶段。

param

duration 建立连接的时间，单位是毫秒。

• onPhaseChanged: (phase: RoomPhase)=>void
  房间连接状态发生变化的回调。

param

phase 房间的连接状态，详见 RoomPhase。你可以阅读管理房间连接状态了解更多信息。

• onRoomStateChanged: (modifyState: Partial)=>void
  房间状态属性发生变化回调。
  该回调仅返回发生变化的房间状态属性，未发生变化的房间状态字段均为空。

param

modifyState 发生变化的房间状态属性，详见 RoomState。

• onDisconnectWithError: (error: Error)=>void
  白板 SDK 与白板服务器连接中断回调。

param

error 错误信息。

• onObjectsLimit: limit: number, soft: boolean)=>void
  白板中的元素数量超过限制回调。

param

limit 白板中的元素数量限制。

param

soft 是否为软限制：

• true：软限制。当白板中的元素数量超过限制时，SDK 会发出警告，但仍可以插入白板元素。

• false：硬限制。当白板中的元素数量超过限制时，SDK 会发出警告，本次添加元素操作无效，房间状态会被强制回退至操作前，且后端会将进行本次操作的用户踢出频道。

• onKickedWithReason: (reason: string)=>void
  用户被服务器移出房间回调。

param

reason 用户被移出房间的原因。

reason 字段	描述
kickByAdmin	被管理员踢出
roomDelete	房间被删除
roomZombie	房间不活跃
roomBan	房间被封禁
GatewayAdjust	网关调整
replaceByOther	被另一个用户顶替，当前用户被迫下线
crash	服务器崩溃

• onCanUndoStepsUpdate: (canUndoSteps: number)=>void
  可撤销次数发生变化回调。
  当本地用户调用 undo 撤销上一步操作时，会触发该回调，报告剩余的可撤销次数。

param

canUndoSteps 剩余的可撤销次数。

• onCanRedoStepsUpdate: (canRedoSteps: number)=>void
  可重做次数发生变化回调。
  当本地用户调用 undo 重做上一步操作时，会触发该回调，报告剩余的可重做次数。

param

canRedoSteps 剩余的可重做次数。

• willInterceptKeyboardEvent: (event: KeyboardEvent)=>boolean
  是否拦截监听的键盘事件：

  • true: 拦截。拦截后，该键盘事件不会触发回调。

  • false: 不拦截。

• onKeyDown: (event: KeyboardEvent)=>void
  键盘按下事件回调。

• onKeyUp: (event: KeyboardEvent)=>void
  键盘松开事件回调。

RoomMember

RoomMember: { memberId: number; memberState: MemberState; payload: UserPayload; session: string }

实时房间内互动模式（具有读写权限）用户的信息。

• memberId: number

  用户 ID。
  在用户加入互动白板实时房间时，会自动分配用户 ID，用于标识房间内的用户。同一房间中的每个用户具有唯一的用户 ID。

• memberState: MemberState

  用户所有的白板工具状态，详见 MemberState。

• payload: UserPayload

  自定义用户信息，在用户加入房间时传入。详见 UserPayload。

  since

  v2.15.0

• session: string

  当前的 session ID。

RoomState

RoomState: DisplayerState & { broadcastState: Readonly<BroadcastState>; memberState: MemberState }

互动白板实时房间的所有状态。该类继承 DisplayerState 且包含以下成员：

• memberState: MemberState
  当前使用的白板工具，详见 MemberState。

• broadcastState: Readonly
  当前的视角状态。

SceneDefinition

SceneDefinition: { name?: string; ppt?: PptDescription }

场景定义。

• name?: string

  场景名称。

• ppt?: PptDescription

  在场景中展示的图片或动态 PPT。每个场景中可以展示一张图片或一页动态 PPT，你可以通过 PptDescription 设置待插入图片或动态 PPT 的宽、高、资源地址或预览图等。详见 PptDescription。

SceneMap

SceneMap: {}

场景列表。

SceneState

SceneState: { contextPath: string; index: number; sceneName: string; scenePath: string; scenes: ReadonlyArray<WhiteScene> }

场景状态。

• contextPath: string

  当前场景所属场景目录的路径。

  since

  2.10.3

• index: number

  当前场景在所属场景目录中的索引号。

• sceneName: string

  当前场景的名称。

  since

  2.10.3

• scenePath: string

  当前场景的路径。

• scenes: ReadonlyArray<WhiteScene>

  当前场景目录下所有场景的列表。

ScenesCallbacks

ScenesCallbacks: { onAddScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onAddSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onRemoveScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onRemoveSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void; onScenesCountUpdate: (scenesCallbacks: ScenesCallbacksNode, scenesCount: number) => void; onScenesGroupCountUpdate: (scenesCallbacks: ScenesCallbacksNode, sceneGroupsCount: number) => void }

场景回调。

• onAddScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

  新增场景回调。

  param

  场景目录的信息。详见 ScenesCallbacksNode。

  param

  新增场景的场景名称。

• onAddSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

  新增子场景目录回调。

  param

  场景目录的信息。详见 ScenesCallbacksNode。

  param

  新增的子场景目录的名称。

• onRemoveScene: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

  删除场景回调。

  param

  场景目录的信息。详见 ScenesCallbacksNode。

  param

  被删除场景的场景名称。

• onRemoveSceneGroup: (scenesCallbacks: ScenesCallbacksNode, name: string) => void

  删除子场景目录回调。

  param

  场景目录的信息。详见 ScenesCallbacksNode。

  param

  被删除的子场景目录的名称。

• onScenesCountUpdate: (scenesCallbacks: ScenesCallbacksNode, scenesCount: number) => void

  指定场景目录下场景数量发生变化回调。

  param

  场景目录的信息。详见 ScenesCallbacksNode。

  param

  指定场景目录下当前的场景数量。

• onScenesGroupCountUpdate: (scenesCallbacks: ScenesCallbacksNode, sceneGroupsCount: number) => void

  指定场景目录下子场景目录数量发生变化回调。

  param

  场景目录的信息。详见 ScenesCallbacksNode。

  param

  指定场景目录下当前子场景目录的数量。

Size

Size: { height: number; width: number }

尺寸大小。

• height: number

  高度。

• width: number

  宽度。

TextFormat

TextFormat: { bold?: boolean; color?: Color; fontSize?: number; italic?: boolean; lineThrough?: boolean; underline?: boolean }

字体样式。

• bold?: boolean

  是否加粗：

  • true：加粗。

  • false：（默认）不加粗。

• color?: Color

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

• fontSize?: number

  字体大小，取值必须大于 0。

• italic?: boolean

  是否使用斜体：

  • true：使用斜体。

  • false：（默认）不使用斜体。

• lineThrough?: boolean

  是否加删除线：

  • true：加删除线。

  • false：（默认）不加删除线。

• underline?: boolean

  是否加下划线：

  • true：加下划线。

  • false：（默认）不加下划线。

UserCursorIcons

UserCursorIcons: {}

用户自定义图标。

UserFonts

UserFonts: {}

自定义字体。

UserPayload

UserPayload: {} & { uid: string }

自定义用户信息。

• [key: string]: any
  key-value 结构的自定义用户信息，例如，"avatar", "https://example.com/user.png"。

• uid: string
  用户标识，字符串格式，不能超过 1024 字节。
  请确保同一房间内每个用户 uid 的唯一性。

since

v2.15.0

WhiteScene

WhiteScene: { name: string; ppt?: PptDescription }

白板场景。

• name: string

  场景名称。

• ppt?: PptDescription

  在场景中展示的图片或动态 PPT。每个场景中可以展示一张图片或一页动态 PPT，你可以通过 PptDescription 设置待插入图片或动态 PPT 的宽、高、资源地址或预览图等。

WhiteWebSdkConfiguration

WhiteWebSdkConfiguration: { appIdentifier: string; deviceType?: DeviceType; disableCurveAnimes?: boolean; disableNewPencilStroke?: boolean; disableRotation?: boolean; fontFamily?: string; fonts?: UserFonts; handToolKey?: string; invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>; loggerOptions?: LoggerOptions; onWhiteSetupFailed?: (error: Error) => void; onlyCallbackRemoteStateModify?: boolean; plugins?: Plugins; preloadDynamicPPT?: boolean; reconnectionOptions?: Partial<ReconnectionOptions> | false; region?: string; renderEngine?: RenderEngine; screenType?: ScreenType; urlInterrupter?: (url: string) => string; useMobXState?: boolean; wrappedComponents?: WrappedComponents }

WhiteWebSdk 对象的配置。
Note
成功初始化 WhiteWebSdk 后，无法再调用 WhiteWebSdkConfiguration 中的任何方法修改 WhiteWebSdk 的配置。

• appIdentifier: string

  白板项目的唯一标识。详见获取互动白板项目的安全密钥。

• deviceType?: DeviceType

  该客户端的设备类型，决定 SDK 如何处理鼠标事件和触碰事件。
  如果填写错误，会导致 SDK 对设备输入的响应行为不符合预期。如果不填，SDK 会根据内在逻辑自动判断设备的类型。

• disableCurveAnimes?: boolean

  是否关闭新铅笔工具（pencil）的补间动画功能：

  • true：关闭补间动画功能。关闭该功能后，会缩短延时，但远端用户看到的笔迹绘制过程可能出现卡顿。

  • false：（默认）开启补间动画功能。开启后，当本地用户使用 pencil 在白板上绘制或书写时，SDK 会自动在关键帧之间插入帧，使远端用户看到的书写或绘制过程更加流畅，但会因此增加延时。

  note

  该属性仅在 disableNewPencil 设为 fasle 时生效。

• disableNewPencilStroke?: boolean

  是否关闭新铅笔的笔锋效果：

  • true：关闭笔锋效果。

  • false：（默认）开启笔锋效果。

  note

  该属性仅在 disableNewPencil 设为 fasle 时生效。

• disableRotation?: boolean

  是否关闭图片旋转：

  • true：禁止图片旋转。

  • false：（默认）开启图片旋转。开启后，可对选中的图片任意旋转。

• fontFamily?: string

  文字工具（currentApplianceName="text"）的字体。若不传，SDK 会使用浏览器的默认字体。

• fonts?: UserFonts

  自定义字体。
  为显示动态 PPT 中的非常规字体，你需要先将字体文件上传到自己的业务服务器或云存储中并生成 URL 地址，然后在初始化 WhiteWebSdk 时，将 URL 地址传给 fonts 属性。详见 UserFonts。

• handToolKey?: string

  抓手工具对应的快捷键。
  按下该键时，会自动切换成抓手工具（currentApplianceName="hand"）；松开后，切回原来的工具。如果不传，则关闭该快捷键功能。

• invisiblePlugins?: ReadonlyArray<InvisiblePluginClass<string, any, any>>

  不可见插件。

• loggerOptions?: LoggerOptions

  SDK 上报日志的选项，详见 LoggerOptions。

• onWhiteSetupFailed?: (error: Error) => void

  WhiteWebSdk 初始化失败的回调。

  example

  JavaScript

  const whiteWebSdk = new WhiteWebSdk({
      appIdentifier: "$APP_IDENTIFIER",
      onWhiteSetupFailed: function(error) {
          console.error(error);
      },
  });  

  该回调仅用于网络或鉴权失败时的错误处理。如果是因为参数原因初始化失败，会在调用 new WhiteWebSdk({...}) 时提示发生错误。

  • error: Error

  错误信息。

• onlyCallbackRemoteStateModify?: boolean

  是否开启仅接收远端用户状态改变回调：

  • true：（默认）开启。开启该功能后，本地用户仅会接收到远端用户状态改变的回调，自身状态的改变不会触发回调。

  • false：关闭。关闭该功能后，本地用户会接收到远端用户状态改变的回调，也会接收到自身状态改变的回调。

• plugins?: Plugins

  组件插件。

• preloadDynamicPPT?: boolean

  是否在加载动态 PPT 首页时，一次性加载动态 PPT 中的所有图片资源：

  • true：一次性加载所有动态 PPT。

  • false: （默认）不一次性加载所有动态 PPT。

  Note
  Agora 不推荐设置 preloadDynamicPPT(true)，这样会使 PPT 显示缓慢。

• reconnectionOptions?: Partial<ReconnectionOptions> | false

  断线重连设置。默认开启自动断线重连。
  如果要关闭断线重连，你可以将 reconnectionOptions 设为 false 或将 disableReconnect 设为 true。 详见《实时房间状态管理》。

• region?: string

  数据中心，支持传入以下值：

  region	数据中心	服务区
  us-sv	美国硅谷	北美洲、南美洲
  sg	新加坡	新加坡、东亚、东南亚
  in-mum	印度孟买	印度
  eu	欧洲（法兰克福）	欧洲
  cn-hz	中国杭州	其他数据中心服务区未覆盖的地区

  Note
  该方法设置的数据中心必须与创建房间时设置的数据中心一致；否则，SDK 将无法连接到房间。

• renderEngine?: RenderEngine

  白板上绘画的渲染模式。默认为 Canvas。

• screenType?: ScreenType

  该客户端的屏幕类型，用于调整手势识别参数。默认为 Desktop。

• urlInterrupter?: (url: string) => string

  将白板中图片等资源的 URL 拦截并替换。
  例如，你可以使用如下代码给所有图片的 URL 增加尾缀：

  example

  JavaScript

  const whiteWebSdk = new WhiteWebSdk({
      appIdentifier: "$APP_IDENTIFIER",
      urlInterrupter: function(url) {
          return url + "?token=bm1n4pisugWrWK";
      },
  });  

  • url: string

  图片等资源原来的 URL。

• useMobXState?: boolean

  是否用 MobX 监听 displayer.state：

  • true：用 MobX 监听 displayer.state。此时 displayer.state 会变成 MobX observable object，详见 Creating observable state。

  • false：不用 MobX 监听 displayer.state。

• wrappedComponents?: WrappedComponents

  由 React.ComponentType 类型组成的数组，用于包装白板的界面。默认值为 []。
  你可以使用如下代码对白板的界面进行自定义包装：

  example

  JavaScript

  import React from "react";
  class WrappedComponent extends React.Component {
      render() {
          return (
              <div>
                  <span>hello world</span>
                  {this.props.children}
              </div>
          );
      }
  }
  const whiteWebSdk = new WhiteWebSdk({
      appIdentifier: "$APP_IDENTIFIER",
      wrappedComponents: [WrappedComponent],
  });  

WorldViewRectangle

WorldViewRectangle: { height: number; originX: number; originY: number; width: number }

配置视觉矩形。
视觉矩形是用户的视角必须容纳的区域。设置好视觉矩形后，SDK 会自动将视角会调整到刚好可以完整展示视觉矩形所表示的范围。
你可以根据要展示的 PPT 幻灯片或图像的尺寸设置视觉矩形，以确保相同的内容在不同尺寸的屏幕上都可以完整显示。

• height: number

  视觉矩形的高度。
  视觉矩形的高度不能小于实际展示内容的宽度，否则用户将看不见超出的部分。

• originX: number

  视觉矩形左上角在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 X 轴坐标。

• originY: number

  视觉矩形左上角在世界坐标系（以白板初始化时的中心点为原点的坐标系）中的 Y 轴坐标。

• width: number

  视觉矩形的宽度。
  视觉矩形的宽度不能小于实际展示内容的宽度，否则用户将看不见超出的部分。

WrappedComponents

WrappedComponents: ReadonlyArray<ComponentType<{}>>

由 React.ComponentType 类型组成的数组，用于包装白板的界面。默认值为 []。

Variables

AdminObserverId

AdminObserverId: number

AkkoVersion

AkkoVersion: any

DefaultHotKeys

DefaultHotKeys: Partial<HotKeys>

DisplayerConsumer

DisplayerConsumer: Consumer<Displayer>

PlayerConsumer

PlayerConsumer: Consumer<Player | undefined>

RoomConsumer

RoomConsumer: Consumer<Room | undefined>

WhiteVersion

WhiteVersion: string

Functions

contentModeAspectFill

contentModeAspectFill(): ContentMode

等比例缩放视角，使视角边界的短边正好顶住与其垂直的屏幕的两边，以保证视角边界铺满屏幕。

返回值

ContentMode

视角的实时缩放比例。

contentModeAspectFillScale

contentModeAspectFillScale(scale: number): ContentMode

等比例缩放视角，使视角边界的短边正好顶住与其垂直的屏幕的两边，以保证视角边界铺满屏幕；在此基础上再将视角边界缩放指定的倍数。

参数

参数名	描述
scale: number	在等比例缩放的基础上再缩放视角边界的倍数。

返回值

ContentMode

视角的实时缩放比例。

contentModeAspectFit

contentModeAspectFit(): ContentMode

等比例缩放视角，使视角边界的长边正好顶住与其垂直的屏幕的两边，以保证在屏幕上完整展示视角边界。

返回值

ContentMode

实时缩放比例。

contentModeAspectFitScale

contentModeAspectFitScale(scale: number): ContentMode

等比例缩放视角，使视角边界的长边正好顶住与其垂直的屏幕的两边，以保证在屏幕上完整展示视角边界；在此基础上，再将视角边界缩放指定的倍数。

参数

参数名	描述
scale: number	在等比例缩放的基础上再缩放视角边界的倍数。

返回值

ContentMode

实时缩放比例。

contentModeAspectFitSpace

contentModeAspectFitSpace(space: number): ContentMode

等比例缩放视角，使视角边界的长边正好顶住与其垂直的屏幕的两边；在此基础上，在视角边界的四周填充指定的空白空间。

参数

参数名	描述
space: number	在等比例缩放的基础上再填充的空白空间，单位为像素。

返回值

ContentMode

实时缩放比例。

contentModeScale

contentModeScale(scale: number): ContentMode

按指定的比例缩放视角边界。

参数

参数名	描述
scale: number	指定的缩放比例。

返回值

ContentMode

实时缩放比例。

createPlugins

createPlugins<C_MAP>(plugins: Readonly<{}>): Plugins<C_MAP>

创建插件。

参数

参数名	描述
plugins: Readonly<{}>	创建的插件。

返回值

Plugins<C_MAP>

injectCustomStyle

injectCustomStyle(icons: UserCursorIcons): void

添加自定义的图标。

参数

参数名	描述
icons: UserCursorIcons	自定义的图标。

返回值

void

isPlayer

isPlayer(displayer: Displayer): boolean

判断 Displayer 对象是否为 Player 对象。

参数

参数名	描述
displayer: Displayer	Displayer 对象。

返回值

boolean

该 Displayer 对象是否为 Player 对象：

• true：该 Displayer 对象是 Player 对象。
• false：该 Displayer 对象不是 Player 对象。

isRoom

isRoom(displayer: Displayer): boolean

判断 Displayer 对象是否为 Room 对象。

参数

参数名	描述
displayer: Displayer	Displayer 对象。

返回值

boolean

Displayer 对象是否为 Room 对象：

• true：该 Displayer 对象是 Room 对象。
• false：该 Displayer 对象不是 Room 对象。

setAsyncModuleLoadMode

setAsyncModuleLoadMode(mode: AsyncModuleLoadMode): void

设置异步模块的加载模式。

参数

参数名	描述
mode: AsyncModuleLoadMode	异步模块的加载模式，详见 AsyncModuleLoadMode。

返回值

void