Room
是实时房间的实例对象,通过 WhiteWebSdk
的实例构造(参考《构造 Room 与 Player 对象》)。它实现了 Displayer
接口(参考《Displayer》),具体定义如下。
interface Room extends Displayer {
readonly uuid: string;
readonly session?: string;
readonly roomToken: string;
readonly phase: RoomPhase;
readonly state: RoomState;
readonly isWritable: boolean;
readonly canUndoSteps: number;
readonly canRedoSteps: number;
disableDeviceInputs: boolean;
disableEraseImage: boolean;
disableSerialization: boolean;
timeDelay: number;
setWritable(isWritable: boolean): Promise<void>;
setGlobalState(modifyState: Partial<GlobalState>): GlobalState;
setMemberState(modifyState: Partial<MemberState>): MemberState;
setViewMode(viewMode: ViewMode): void;
setScenePath(scenePath: string): void;
setSceneIndex(index: number): void;
dispatchMagixEvent(event: string, payload: any): void;
putScenes(path: string, scenes: ReadonlyArray<SceneDefinition>, index?: number): void;
cleanCurrentScene(retainPpt?: boolean): void;
removeScenes(path: string): void;
moveScene(originalPath: string, targetPath: string): void;
insertImage(imageInfo: ImageInformation): void;
completeImageUpload(uuid: string, src: string): void;
duplicate(): void;
copy(): void;
paste(): void;
undo(): number;
redo(): number;
delete(): void;
pptNextStep(): void;
pptPreviousStep(): void;
disconnect(): Promise<void>;
}
房间的 uuid
,用于唯一标识该房间。
房间当前的 Session 的 uuid
。会被上报作为日志字段(如果开启了自动日志上报功能)。如果当前尚未与服务器建立连接,则为 undefined
。
房间 Token,即加入房间时传入的字段。
房间状态,其类型 RoomPhase
定义如下。
enum RoomPhase {
// 正在连接
Connecting = "connecting",
// 连接成功
Connected = "connected",
// 正在重连
Reconnecting = "reconnecting",
// 正在断开连接
Disconnecting = "disconnecting",
// 已断开连接
Disconnected = "disconnected",
}
阅读《实时房间状态管理》 以了解更多。
业务状态,其类型为 RoomState
。阅读 《房间与回放的业务状态管理》 、《房间业务状态管理》 以了解更多。
当前是否「可写」。
可撤销步骤。即此时此刻,还可以调用多少次 room.undo()
方法。
可重做步骤。即此时此刻,还可以调用多少次 room.redo()
方法。
是否禁止设备输入。即通过鼠标、键盘、触摸屏幕来操作教具。可修改。
是否禁止橡皮工具擦出白板上的图片(不影响白板中的 PPT 背景)。可修改。
是否禁止如下方法(默认值是 true
)。可修改。
room.redo
room.undo
room.duplicate
room.copy
room.paste
房间内所有人的
white-web-sdk
的版本必须不低于2.9.3
时,才能将该值设为false
。房间内任何一个人将该值设为false
,都会导致房间内低于2.9.3
的用户前端报错且不能正常使用。
主动延迟接收的远端消息,单位是毫秒,默认值 0
。将该值设置成大于 0
的数字,可以人为造成类似网络时延的效果。可修改。
setWritable(isWritable: boolean): Promise<void>;
修改 room.isWritable
的值。该操作会向服务器发起请求,因此会返回一个 Promise
对象。注意通过 .catch()
的方式处理异常流程,因为请求可能被服务器拒绝,或失败。
setGlobalState(modifyState: Partial<GlobalState>): GlobalState;
用于修改房间的 globalState
的字段。可以通过如下方法修改特定字段。
room.setGlobalState({
foobar: "hello world",
});
也可以通过将某个字段置为 undefined
,来删掉该字段。
room.setGlobalState({
foobar: undefined,
});
setMemberState(modifyState: Partial<MemberState>): MemberState;
用于修改房间的 memberState
的字段。可以通过如下方法修改特定字段。
room.setMemberState({
foobar: "hello world",
});
也可以通过将某个字段置为 undefined
,来删掉该字段。
room.setMemberState({
foobar: undefined,
});
setViewMode(viewMode: ViewMode): void;
修改房间的 room.state.broadcastState.mode
的值。会改变自己或房间内其他人的视角模式。
setScenePath(scenePath: string): void;
修改当前场景地址,会将切换当前房间的场景。
setSceneIndex(index: number): void;
修改当前场景的索引号,会将切换当前房间的场景。
dispatchMagixEvent(event: string, payload: any): void;
向房间内广播自定义事件。其中,第一参数 event
是事件的名称,房间内其他成员可以通过它注册监听事件。第二参数 payload
是负载,可以是任意类型的值,可根据具体业务自行设计。
putScenes(path: string, scenes: ReadonlyArray<SceneDefinition>, index?: number): void;
在房间中插入场景。参考《插入新场景|场景管理》。
removeScenes(path: string): void;
在房间中删除场景。参考《删除场景|场景管理》。
moveScene(originalPath: string, targetPath: string): void;
在房间中移动场景。参考《移动场景|场景管理》。
cleanCurrentScene(retainPpt?: boolean): void;
清理当前场景内所有内容。第一参数 retianPpt
表明是否保留 PPT 背景不被清理,默认值是 true
。
insertImage(imageInfo: ImageInformation): void;
在当前场景中插入图片。参数类型为 ImageInformation
,其定义如下。
type ImageInformation = {
// 图片的 uuid
readonly uuid: string;
// 插入的图片的中心点在世界坐标系中的 x 轴坐标
readonly centerX: number;
// 插入的图片的中心点在世界坐标系中的 y 轴坐标
readonly centerY: number;
// 插入的图片的在世界坐标系中的宽
readonly width: number;
// 插入的图片的在世界坐标系中的高
readonly height: number;
// 是否锁定图片让其无法被橡皮擦出或被选择工具框选
readonly locked: boolean;
};
该操作往往需要和 room.completeImageUpload
配合使用,具体例子可参考《插入图片|教具》。
completeImageUpload(uuid: string, src: string): void;
设置图片资源。第一参数 uuid
是图片的唯一标识符,应该与 room.insertImage
中传入的 uuid
字段相同。第二参数 src
是图片资源的 URL。具体例子可参考《插入图片|教具》。
复刻当前选择工具所选的所有组键件。只有在 room.disableSerialization
为 false
的时候可调用。
复制当前选择工具所选的所有组键件。只有在 room.disableSerialization
为 false
的时候可调用。
粘贴上一次复制的组件。只有在 room.disableSerialization
为 false
的时候可调用。
撤回上一个动作。只有在 room.disableSerialization
为 false
的时候可调用。
重做上一个动作。只有在 room.disableSerialization
为 false
的时候可调用。
删除当前选择工具所选的所有组件。
pptNextStep(): void;
PPT 翻页到下一页。如果当前 PPT 没有动画,则切换到顺位索引 +1 的场景,如果有动画,则播放下一个动画。
pptPreviousStep(): void;
PPT 翻页到前一页。如果当前 PPT 没有动画,则切换到顺位索引 -1 的场景,如果有动画,则切换到上一个动画播放完毕的样子。
disconnect(): Promise<void>;
令房间断开连接。这是一个异步方法,会返回 Promise
对象。