新版 API 与多窗口课件控制
- Android
更新时间不可用
适用于 Whiteboard Android SDK 2.16.131。先按加入白板房间完成 SDK 初始化。
开启多窗口
WhiteSdkConfiguration config = new WhiteSdkConfiguration("APP_IDENTIFIER", true);
config.setRegion(Region.cn);
config.setUseMultiViews(true);
config.setEnableAppliancePlugin(true);
WindowParams windows = new WindowParams()
.setUseBoxesStatus(false)
.setForceMaximized(true)
.setLazySetupInMaximizedMode(true)
.setMaxCachedAppsInMaximizedMode(4)
.setOriginSize(new WindowOriginSize(1280, 720))
.setPageScaleRange(new PageScaleRange().setMinScale(0.5).setMaxScale(4.0));
RoomParams params = new RoomParams("ROOM_UUID", "ROOM_TOKEN", "CLIENT_UID");
params.setRegion(Region.cn);
params.setWindowParams(windows);
params.setWritable(true);
// config 传给 WhiteSdk 构造函数，params 传给 joinRoom。以上类型的 import：com.herewhite.sdk.WhiteSdkConfiguration、com.herewhite.sdk.RoomParams，其余类型位于 com.herewhite.sdk.domain。这些配置必须在创建 SDK / 加入房间前设置。
插入课件与切换焦点
// room 是 joinRoom 成功返回的 Room。
WindowAppParam app = WindowAppParam.createSlideApp("TASK_UUID", "PREFIX_URL", "课件");
app.setOriginSize(new WindowOriginSize(1280, 720));
room.addApp(app, new Promise<String>() {
@Override public void then(String appId) {
// 保存 appId，后续用它查询、聚焦或关闭课件。
}
@Override public void catchEx(SDKError error) {
// 显示创建失败或初始化失败提示。
}
});通过 room.focusApp(appId, Promise<Boolean>) 等待焦点提交；通过 queryApp/queryAllApps 查询课件。WindowAppParam.createPresentationApp(...) 可创建内置 Presentation。自定义 App 需先调用 whiteSdk.registerApp(...)，再通过 addApp 添加。
统一页面控制
room.dispatchDocsEvent(WindowDocsEvent.ScalePage(1.5).withTarget("mainView"),
new Promise<DispatchDocsEventResult>() {
@Override public void then(DispatchDocsEventResult result) {
if (!result.isAccepted()) {
String reason = result.getReason();
String message = result.getMessage();
}
}
@Override public void catchEx(SDKError error) {
// 处理 Bridge/异步异常。
}
});
whiteSdk.setUnifiedPageStateListener(new UnifiedPageStateListener() {
@Override public void onUnifiedPageStateChange(UnifiedPageStateChange state) {
// 观察实际页码、相对倍率，或异步命令失败。
}
});
room.getPageState(new WindowPageStateOptions().withTarget("mainView"),
new Promise<UnifiedPageState>() {
@Override public void then(UnifiedPageState state) {}
@Override public void catchEx(SDKError error) {}
});Promise 和结果类型位于 com.herewhite.sdk.domain；UnifiedPageStateListener 位于 com.herewhite.sdk.window。统一控制与状态类型自 2.16.130 提供，focusApp 的 Promise 重载及 lazy 配置自 2.16.131 提供。
旧 SlideListener.onSlidePageStateChanged(appId, page, pageCount) 与 Room.querySlidePageState(...) 继续可用。主白板 nextPage/prevPage 与课件事件控制要按目标选择；不要用场景零基索引作为统一事件页码。
页面事件和返回结果
| 字段 / 事件 | 类型与含义 |
|---|---|
target 输入 | 可选字符串：mainView 或具体 appId；省略时跟随当前焦点，无焦点时回退 MainView |
prevPage / nextPage | 前一页 / 后一页 |
prevStep / nextStep | 前一步 / 后一步；用于具有步骤能力的课件 |
jumpToPage | options.page：从 1 开始的整数页码 |
scalePage | options.scale：正数相对倍率，1 表示适配尺寸；DocsViewer 不支持此事件 |
accepted | 布尔值，表示命令是否被接收，不表示渲染完成 |
reason / message | 被拒绝时的原因码和说明 |
原因码为 invalidEvent、invalidOptions、targetNotFound、targetNotSupported、eventNotSupported、notWritable、stateUnavailable、outOfRange、commandFailed。
状态查询返回 target（mainView、DocsViewer、Slide 或 Presentation）、可选 appId、1-based page/pageCount 与可选 scale。实际观察回调还可包含 status: pending/success、changeType: page/scale；异步失败包含 status: failure、event、reason: commandFailed 和可选 message。
参考尺寸与缩放
WindowParams.originSize 作用于 MainView。实时房间可写端传入新的参考尺寸时，会重置并同步 MainView 的 origin/active camera-size contract。Slide/Presentation 必须在 WindowAppParam.originSize 单独传入，并序列化为 attributes.originSize，不会从 MainView 配置隐式继承。
width/height 应为正数。pageScaleRange.minScale/maxScale 是可选的相对适配倍率边界，未配置的边界不增加业务限制。fitOriginSizeAndCamera() 恢复 MainView 参考尺寸与初始相机，不改变课件 App 的参考尺寸。
最大化与本地缓存
| 配置 | 默认与生效条件 |
|---|---|
forceMaximized | 默认关闭；可写端开启后同步房间级强制最大化，支持协议的客户端不能进入 normal |
lazySetupInMaximizedMode | 默认关闭；仅在房间已 forceMaximized 且处于 maximized/minimized 时按焦点初始化，否则使用 eager |
maxCachedAppsInMaximizedMode | 默认 4；本地 App runtime LRU 容量，不是房间 App 数量上限 |
useBoxesStatus | 每个窗口独立状态，与 forceMaximized 不能同时生效；继承房间强制最大化或有效 lazy 模式时忽略本地独立窗口状态，否则同时请求两者时独立窗口状态优先 |
Slide 从 LRU 移出或最小化后可以保留 runtime，播放器按焦点/活动状态协调资源，因此缓存容量不能直接解释为 Slide runtime 的销毁数量。
focusApp 的布尔结果只表示共享 focus、Box 焦点、zIndex 的最终提交状态。setup 失败或超时只记录日志，不单独决定返回值。addApp 在创建失败或未取得 ID 时走本端错误路径；lazy 模式或最小化状态可先返回 ID。eager 模式尝试等待 setup，但 setup 失败可仅记录日志，仍可能返回 ID，因此成功返回不保证初始化和渲染成功。closeApp 当前 Native 层收到完成回调后固定返回 true，不能据此设计 false 业务失败分支。
Slide 配置
| 字段 | 默认 / 可选值 |
|---|---|
enableScale | 默认 false；允许内容缩放 |
enableGlobalClick | 默认 true；允许点击画面执行下一步 |
syncEventQueuePolicy | 默认 fifo；latest-pending-render 需显式开启，非 interactive 模式仍走 FIFO |
navigationButtonMode | 默认 page；step 按动画步骤，仅控制底部前后按钮 |
resolution | 默认 1，可显式覆盖 |
maxResolutionLevel | 0~4；常见运行时默认 2，Android WebView ≤69 默认 1 |
minFPS/maxFPS | 常见运行时 15/30；Android WebView ≤89 默认 5/15。ArkWeb 使用 15/30 |
这里的性能默认值来自当前内嵌 Bridge 的 WebView UA 判断。显式 Native 参数优先；不能把 app-slide 的基础默认值直接当作 Native 的最终默认值。
更多公开接口
完整方法、getter/setter、模型字段和回调见客户端 API。本地日志见本地日志，教具与扩展功能见教具插件介绍，背景图诊断与恢复见背景图加载与恢复。
RoomParams.appliancePluginOptions的 Java 类型是AppliancePluginOptions，通过setExtras(Map<String, Object>)配置 cursor、syncOpt、bezier、textEditor 和运行时兼容选项。RoomParams.undoCacheScenesCount在入房前设置。WhiteboardViewOptions.enableAssetsHttps控制内置资源使用 HTTPS 方案。WhiteSdkConfiguration.SlideAppOptions.resourceMaxRetries与SlideListener.onSlideResourceMaxRetries用于资源加载重试和耗尽通知。AudioEffectImplement.setEffectSoundId/setEffectDurationUpdate用于更新音效混音状态和总时长。Room.getSyncedStore()需初始化时config.setEnableSyncedStore(true)；通过 SyncedStore 公共方法连接、查询、写入并监听存储。