# 预加载 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/preload) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" /> 适用于 **Whiteboard Android SDK 2.16.134**,使用已公开的 `WhiteboardView`、`WhiteSdk` 和 `joinRoom` 接口。 预加载将白板内嵌页面加载、Bridge 握手和 SDK 初始化提前到候课阶段。用户进入课堂时,复用同一组 View 与 SDK,再提交房间参数。候课阶段不调用 `joinRoom`,不创建房间会话。 ## 接入流程 [#接入流程] 1. 在主线程创建并持有 `WhiteboardView`,放入有实际尺寸的候课容器。 2. 确定 SDK 配置并创建 `WhiteSdk`,由 SDK 启动初始化。多窗口、教具插件和动态配置地址应在此时配置。 3. 用户进入课堂时显示原 View,在同一 SDK 上调用 `joinRoom`。 4. 退出时等待 `leaveRoom` 成功,再决定保留实例或销毁 View。 本例在同一个 Activity 内切换候课和课堂容器。只创建空 WebView、进入课堂时重新创建 View 或重新加载页面,都不能保留这组实例的准备结果。 ## 候课阶段:提前创建 [#候课阶段提前创建] 以下字段和方法位于业务 Activity 中;容器由业务布局提供。示例使用 `com.herewhite.sdk` 下的 SDK 类型、`com.herewhite.sdk.domain` 下的 `Promise`、`RoomParams`、`Region`、`WindowParams` 和 `SDKError`。 ```java private WhiteboardView whiteboardView; private WhiteSdk whiteSdk; private Room room; private boolean joining; private void preload(FrameLayout waitingContainer, String appIdentifier) { if (whiteSdk != null) return; whiteboardView = new WhiteboardView(this); waitingContainer.addView(whiteboardView, new FrameLayout.LayoutParams( ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)); WhiteSdkConfiguration config = new WhiteSdkConfiguration(appIdentifier, true); config.setRegion(Region.cn); config.setUseMultiViews(true); config.setEnableAppliancePlugin(true); whiteSdk = new WhiteSdk(whiteboardView, this, config); // 此处不入房;可以用候课内容覆盖白板区域。 } ``` 构造方法返回只表示 Native 对象已创建。当前版本没有可等待的 SDK 预加载完成接口,不要据此显示“白板已就绪”,也不要用固定延时判断完成。用户提前进入课堂时,仍按正常流程调用 `joinRoom`,由入房结果判断是否成功。 ## 进入课堂:复用并入房 [#进入课堂复用并入房] ```java private void enterClass(FrameLayout classroomContainer, String roomUuid, String roomToken, String userId) { if (whiteSdk == null || joining || room != null) return; joining = true; ViewGroup parent = (ViewGroup) whiteboardView.getParent(); if (parent != null) parent.removeView(whiteboardView); classroomContainer.addView(whiteboardView, new FrameLayout.LayoutParams( ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)); RoomParams params = new RoomParams(roomUuid, roomToken, userId); params.setRegion(Region.cn); params.setWritable(true); params.setWindowParams(new WindowParams()); whiteSdk.joinRoom(params, new Promise() { @Override public void then(Room joinedRoom) { joining = false; room = joinedRoom; whiteboardView.post(() -> { if (room == joinedRoom) joinedRoom.refreshViewSize(); }); } @Override public void catchEx(SDKError error) { joining = false; Log.e("Whiteboard", "加入房间失败", error); } }); } ``` 示例省略房间事件监听;需要监听时使用带 `RoomListener` 的重载,参见[加入白板房间](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb)。容器尺寸变化后调用 `refreshViewSize`,应等新布局生效。示例没有重新构造 SDK,也没有调用 `loadUrl` 或 `reload`。 ## 退出与资源回收 [#退出与资源回收] ```java private void leaveClass() { if (whiteSdk == null || joining || room == null) return; whiteSdk.leaveRoom(new Promise() { @Override public void then(Object ignored) { room = null; // 退出已确认。可保留同一组实例,之后串行加入下一个房间。 // 若最终不用,再从父容器移除 View,调用 destroy() 并清理引用。 } @Override public void catchEx(SDKError error) { Log.e("Whiteboard", "退出未确认,暂停复用或销毁流程", error); } }); } ``` 退出等待期间应禁用重复进入和退出操作。页面主动退出时先等待上述回调,再结束 Activity;系统强制销毁无法保证异步退房完成。不要将使用 Activity Context 的 View 放入全局静态池,或在旧 Activity 销毁后交给新 Activity 继续使用。 ## 能力边界 [#能力边界] 预加载不包含房间鉴权、房间状态同步、WindowManager 挂载、课件下载或可见首帧。启用[动态配置](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/dynamic-config)后,远端配置仍在每次入房前读取;SDK 提前创建不代表配置已下载。课件资源策略见[课件按需加载](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/courseware-lazy-loading)。 `prepareWhiteConnection` 是独立的网络接入准备辅助接口,不保留本页所需的 View 与 SDK,不能替代上述流程。收益应分别记录候课初始化、点击进入到入房成功、点击进入到可见首帧,按目标设备实测;完全隐藏、零尺寸和后台 WebView 的调度不能作为完成保证。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" /> 适用于 **Whiteboard iOS SDK 2.16.147**,使用已公开的初始化方法和 `joinRoomWithConfig:callbacks:completionHandler:`。 在候课阶段创建 `WhiteBoardView` 和 `WhiteSDK`,可以提前加载内嵌页面、完成 Bridge 握手并启动 SDK 初始化。用户进入课堂时复用原有对象,再加入业务房间。候课阶段不传入房间凭据、不调用入房方法。 ## 候课阶段:创建并持有实例 [#候课阶段创建并持有实例] 以下代码位于同一业务 UIViewController 中,两阶段均在主线程执行。业务会话必须同时强持有 View 与 SDK:SDK 对白板 View 的引用为弱引用,只保留 SDK 不足以保证预加载实例存活。 ```objc @property(nonatomic, strong) WhiteBoardView *board; @property(nonatomic, strong) WhiteSDK *sdk; @property(nonatomic, strong) WhiteRoom *room; @property(nonatomic, assign) BOOL joining; ``` ```objc - (void)preloadInContainer:(UIView *)waitingContainer appIdentifier:(NSString *)appIdentifier { if (self.sdk) return; WhiteSdkConfiguration *config = [[WhiteSdkConfiguration alloc] initWithApp:appIdentifier]; config.region = WhiteRegionCN; config.useMultiViews = YES; config.enableAppliancePlugin = YES; self.board = [[WhiteBoardView alloc] init]; self.board.frame = waitingContainer.bounds; self.board.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight; [waitingContainer addSubview:self.board]; self.sdk = [[WhiteSDK alloc] initWithWhiteBoardView:self.board config:config commonCallbackDelegate:nil]; // 不调用 joinRoom;可用候课界面覆盖这个有实际尺寸的 View。 } ``` 如需公共回调,传入业务实现的 `WhiteCommonCallbackDelegate`,并由会话持有该代理。SDK 的代理引用同样为弱引用。 当前正式版没有公开可等待的 SDK 预加载完成接口。初始化返回、页面加载完成、等待固定秒数,都不能证明本地 SDK 及网络准备全部完成。功能分支新增的 `prepareWithCompletionHandler:`、`prepareWithTimeout:completionHandler:` 尚未发布,不属于本页 2.16.147 示例。 ## 进入课堂:复用 View 与 SDK [#进入课堂复用-view-与-sdk] ```objc - (void)enterClassInContainer:(UIView *)classroomContainer roomUuid:(NSString *)roomUuid roomToken:(NSString *)roomToken uid:(NSString *)uid { if (!self.sdk || self.joining || self.room) return; self.joining = YES; [self.board removeFromSuperview]; self.board.frame = classroomContainer.bounds; [classroomContainer addSubview:self.board]; [classroomContainer layoutIfNeeded]; WhiteRoomConfig *roomConfig = [[WhiteRoomConfig alloc] initWithUuid:roomUuid roomToken:roomToken uid:uid]; roomConfig.region = WhiteRegionCN; roomConfig.isWritable = YES; roomConfig.windowParams = [WhiteWindowParams new]; __weak typeof(self) weakSelf = self; [self.sdk joinRoomWithConfig:roomConfig callbacks:nil completionHandler:^(BOOL success, WhiteRoom *room, NSError *error) { __strong typeof(weakSelf) self = weakSelf; if (!self) return; self.joining = NO; if (!success) { NSLog(@"加入房间失败:%@", error); return; } self.room = room; [room refreshViewSize]; }]; } ``` 需要房间事件时传入当前课堂的 `WhiteRoomCallbackDelegate`,参见[加入白板房间](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb)。候课和课堂也可共用父容器,只切换覆盖内容。跨 UIViewController 时应由独立会话对象持有并转移同一 View 与 SDK,管理代理和旧控制器的释放;仅传递配置并重新创建 View 不会复用预加载结果。 SDK 配置应在候课前确定并保持不变。2.16.147 保存配置对象,候课后再修改可能改变后续初始化参数;不能把新功能分支的不可变配置快照行为当作正式版承诺。 ## 退出与复用 [#退出与复用] ```objc [self.sdk leaveRoomWithCompletionHandler:^(NSError *error) { if (error) { NSLog(@"退出未确认,停止后续复用或销毁:%@", error); return; } self.room = nil; // 可保留 board / sdk,下一次进入课堂时串行入房。 // 最终不用时,再移除 View、清理代理并释放强引用。 }]; ``` 退出过程中禁用重复入房操作。先确认异步退出成功,再执行页面跳转或最终资源释放;不要在发起退出后立即释放 View,也不要仅凭旧 `disconnect` 的无错误参数回调认定关闭成功。 ## 能力边界 [#能力边界-1] 预加载不表示房间已连接、WindowManager 已挂载、课件已下载或首帧可见。启用[动态配置](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/dynamic-config)后仍在入房时加载远端参数,不能把初始化返回作为动态配置已生效的信号。课件策略见[课件按需加载](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/courseware-lazy-loading)。 `prepareWhiteConnectionForAppId:region:expireSeconds:attachingSuperView:` 创建的是独立临时 View,用于网络接入准备,不能替代本页的同 View、同 SDK 流程。完全离屏、零尺寸、隐藏或后台 WKWebView 的调度与内存开销应在目标设备验证,不承诺固定的入房提速数值。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="harmonyos" /> 从 **Whiteboard HarmonyOS SDK 0.2.12** 起,支持通过 `autoJoin`、`prepare()`、手动 `joinRoom()` 及分离的 SDK/Room 配置类型接入预加载。 预加载让同一个白板 Web 节点在候课阶段完成页面加载、Bridge 握手和本地 SDK 构造,进入课堂时再加入房间。仅创建 `WhiteboardController` 不会加载页面,必须挂载并持续保留实际 `Whiteboard` 组件。 ## 配置与调用顺序 [#配置与调用顺序] 1. 用 `WhiteboardSdkOptions` 设置 AppIdentifier、多窗口、教具插件及动态配置地址,不传房间凭据。 2. 挂载 `Whiteboard`,设置 `autoJoin: false`;默认值为 `true`,旧接入仍会自动入房。 3. 调用 `controller.prepare()` 等待本地 SDK 准备完成。 4. 用户进入课堂时传入 `WhiteboardRoomOptions`,调用 `controller.joinRoom()`。 5. 退出时等待 `controller.leaveRoom()` 成功,再跳转页面或复用同一组件。 ## 接入示例 [#接入示例] 示例把候课和课堂放在同一个页面,切换状态时始终保留原 `Whiteboard` 节点。房间信息为占位值,应由业务服务取得,Room Token 不应写死在客户端。 ```ts import { Whiteboard, WhiteboardCallbacks, WhiteboardController, WhiteboardSdkOptions, WhiteboardRoomOptions, WindowParams, Region } from '@shengwang/whiteboard'; @Entry @Component struct PreloadPage { private controller: WhiteboardController = new WhiteboardController(); private sdkOptions: WhiteboardSdkOptions = { appIdentifier: 'YOUR_APP_IDENTIFIER', useMultiViews: true, enableAppliancePlugin: true }; private callbacks: WhiteboardCallbacks = new WhiteboardCallbacks(); private disposed: boolean = false; @State prepared: boolean = false; @State joined: boolean = false; @State busy: boolean = false; @State status: string = '正在准备白板'; aboutToAppear(): void { this.controller.prepare(15000).then(() => { if (this.disposed) return; this.prepared = true; this.status = '白板已准备,等待进入课堂'; }).catch((error: Error) => { if (!this.disposed) this.status = error.message; }); } private async enterClass(): Promise { if (this.disposed || this.busy || this.joined || !this.prepared) return; this.busy = true; this.status = '正在加入房间'; const room: WhiteboardRoomOptions = { roomUuid: 'YOUR_ROOM_UUID', roomToken: 'YOUR_ROOM_TOKEN', uid: 'YOUR_USER_ID', region: Region.CN_HZ, writable: true, windowParams: new WindowParams() }; try { await this.controller.joinRoom(room); if (!this.disposed) { this.joined = true; this.status = '已进入课堂'; } } catch (error) { if (!this.disposed) this.status = (error as Error).message; } finally { this.busy = false; } } private async leaveClass(): Promise { if (this.busy || !this.joined) return; this.busy = true; try { await this.controller.leaveRoom(); this.joined = false; this.status = '已退出课堂,可保留组件再次入房'; // 如需返回上一页,在成功退出后执行路由跳转。 } catch (error) { this.status = '退出未确认:' + (error as Error).message; } finally { this.busy = false; } } aboutToDisappear(): void { this.disposed = true; this.controller.cancelPreparation(); // 此处取消准备等待;已入房时应先通过受控退出流程等待 leaveRoom。 } build() { Column() { Text(this.status).padding(12) Row() { Button('进入课堂') .enabled(this.prepared && !this.busy && !this.joined) .onClick(() => { this.enterClass(); }) Button('退出课堂') .enabled(this.joined && !this.busy) .onClick(() => { this.leaveClass(); }) } Whiteboard({ options: this.sdkOptions, controller: this.controller, callbacks: this.callbacks, autoJoin: false }).layoutWeight(1) }.width('100%').height('100%') } } ``` `options` 是组件的实际配置字段。不要改写为不存在的 `sdkOptions` 组件参数,也不要在 `if (joined)` 条件中重新创建白板。仅保留 Controller、销毁后重新挂载 Web 节点,不会保留原 document 的预加载结果。 ## 准备状态与错误处理 [#准备状态与错误处理] | 接口 | 行为 | | --- | --- | | prepare(timeoutMs = 15000) | 返回 Promise<PreparationInfo>;单位为毫秒,包含等待组件挂载和 SDK 初始化的时间。可在组件挂载前调用。 | | getPreparationInfo() | 返回当前准备信息;未绑定组件时可为 undefined。ready 表示本地 SDK 已构造,setupCount 记录当前 View 的初始化调用次数。 | | cancelPreparation() | 取消等待并使准备命中失效,忽略迟到结果;不会退出已加入的房间。 | | joinRoom(roomOptions) | 使用本次房间参数入房;同一个实际节点和相同 SDK 配置可复用准备结果。 | | leaveRoom() | 等待退出确认;失败时保留错误,暂停复用与销毁流程。 | 准备失败或超时应显示错误并提供显式重试入口,不能仍显示“准备完成”。宿主 Web 节点失效、页面重载或组件卸载后,原准备结果失效;应重新准备并更新业务侧状态。不要在入房或活跃房间期间更换 SDK 配置来抢占当前实例。 SDK 配置和房间参数分别做 JSON 快照。SDK 配置在准备前确定;正式入房时再传本次房间身份。预加载时设置 `autoJoin: false`,无需传入空房间号或占位 Token。 ## 完成与性能边界 [#完成与性能边界] `prepare()` 成功只证明当前实际 Web 节点中的本地 JS SDK 已构造,没有加入房间。它不代表远端[动态配置](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/dynamic-config)加载、鉴权连接、多窗口挂载、课件下载或首帧可见;这些阶段仍在后续完成。课件资源策略参见[课件按需加载](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/courseware-lazy-loading)。 建议分别记录准备请求、准备完成、点击进入、入房成功和可见首帧。后台、隐藏、跨路由和内存回收场景需另行验证,不能将示例中的准备状态作为固定性能收益保证。 <_PlatformProcessedMarker close="true" />