# 新版 API 与多窗口课件控制 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/native-api-extension/android) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 适用于 **Whiteboard Android SDK 2.16.131**。先按[加入白板房间](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb)完成 SDK 初始化。 ## 开启多窗口 [#开启多窗口] ```java 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 / 加入房间前设置。 ## 插入课件与切换焦点 [#插入课件与切换焦点] ```java // room 是 joinRoom 成功返回的 Room。 WindowAppParam app = WindowAppParam.createSlideApp("TASK_UUID", "PREFIX_URL", "课件"); app.setOriginSize(new WindowOriginSize(1280, 720)); room.addApp(app, new Promise() { @Override public void then(String appId) { // 保存 appId,后续用它查询、聚焦或关闭课件。 } @Override public void catchEx(SDKError error) { // 显示创建失败或初始化失败提示。 } }); ``` 通过 `room.focusApp(appId, Promise)` 等待焦点提交;通过 `queryApp/queryAllApps` 查询课件。`WindowAppParam.createPresentationApp(...)` 可创建内置 Presentation。自定义 App 需先调用 `whiteSdk.registerApp(...)`,再通过 `addApp` 添加。 ## 统一页面控制 [#统一页面控制] ```java room.dispatchDocsEvent(WindowDocsEvent.ScalePage(1.5).withTarget("mainView"), new Promise() { @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() { @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 配置 [#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](/zh-CN/api-reference/whiteboard/whiteboard-sdk/android/overview)。本地日志见[本地日志](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/local-log),教具与扩展功能见[教具插件介绍](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/overview),背景图诊断与恢复见[背景图加载与恢复](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/background-image-recovery)。 - `RoomParams.appliancePluginOptions` 的 Java 类型是 `AppliancePluginOptions`,通过 `setExtras(Map)` 配置 cursor、syncOpt、bezier、textEditor 和运行时兼容选项。 - `RoomParams.undoCacheScenesCount` 在入房前设置。 - `WhiteboardViewOptions.enableAssetsHttps` 控制内置资源使用 HTTPS 方案。 - `WhiteSdkConfiguration.SlideAppOptions.resourceMaxRetries` 与 `SlideListener.onSlideResourceMaxRetries` 用于资源加载重试和耗尽通知。 - `AudioEffectImplement.setEffectSoundId/setEffectDurationUpdate` 用于更新音效混音状态和总时长。 - `Room.getSyncedStore()` 需初始化时 `config.setEnableSyncedStore(true)`;通过 SyncedStore 公共方法连接、查询、写入并监听存储。