# 背景图加载与恢复 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/background-image-recovery/android) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 当前 SDK 提供 Appliance Plugin 背景图加载状态、失败恢复及插件初始化进度能力。使用背景图查询和恢复前,需同时开启 `useMultiViews=true` 与 `enableAppliancePlugin=true`。 ## 配置 [#配置] ```java BackgroundImageLoadOptions loading = new BackgroundImageLoadOptions(); loading.setMaxRetries(3); loading.setTimeoutMs(15000); loading.setRetryIntervalMs(1000); config.setBackgroundImageLoadOptions(loading); ``` `WhiteSdk.hasBackgroundImage(HasBackgroundImageParams, Promise)` 查询;`reloadBackgroundImage(ReloadBackgroundImageParams, Promise)` 恢复。事件通过 `CommonCallback.onBackgroundImageLoad` / `onApplianceInitLoadingChange` 接收。参数和结果类型位于 `com.herewhite.sdk.domain`。 | 配置 | 范围 | 默认值 | | --- | --- | --- | | `maxRetries` | -1(无限重试)或整数 0~10 | 3 | | `timeoutMs` | 1000~120000 毫秒 | 15000 | | `retryIntervalMs` | 0~30000 毫秒 | 1000 | ## 插入固定图片(Native 接口) [#插入固定图片native-接口] 如果需求是在白板上插入不能被移动或缩放的图片,可使用 Native 图片接口,并设置 `locked=true`: ```java import java.util.UUID; import com.herewhite.sdk.domain.ImageInformation; String imageId = UUID.randomUUID().toString(); ImageInformation image = new ImageInformation(); image.setUuid(imageId); image.setCenterX(0); image.setCenterY(0); image.setWidth(1280); image.setHeight(720); image.setLocked(true); room.insertImage(image); room.completeImageUpload(imageId, "https://example.com/background.png"); ``` 在入房成功、房间可写时调用。坐标和尺寸按照白板的世界坐标填写;`locked` 只限制移动和缩放,不等于禁止擦除。需要禁止普通橡皮擦除图片时,在入房前通过 `params.setDisableEraseImage(true)` 配置。 该方式插入的是普通图片元素,不会自动转换为 Appliance Plugin 专用背景图。下方 `hasBackgroundImage` 与 `reloadBackgroundImage` 针对插件管理的背景资源,不用于查询或重载这个普通图片元素。 ## 配置插件背景图加载 [#配置插件背景图加载] 应用可对房间中的插件背景图配置显示、加载重试、存在性查询和失败恢复。在 `joinRoom` 前开启背景线程: ```java import java.util.HashMap; import java.util.Map; import com.herewhite.sdk.domain.AppliancePluginOptions; Map extras = new HashMap<>(); extras.put("useBackgroundThread", true); AppliancePluginOptions pluginOptions = new AppliancePluginOptions(); pluginOptions.setExtras(extras); params.setAppliancePluginOptions(pluginOptions); ``` 以上配置通过 `RoomParams` 设置;加载重试策略通过 `WhiteSdkConfiguration` 设置。已有其他 extras 配置时,将该字段合并到同一个配置 Map。 ## 查询与恢复参数 [#查询与恢复参数] 查询参数为 `viewId`、`scenePath`、`imageUrl` 和背景图来源列表 `sources`,当前填写 `new String[]{"appliance"}`。恢复参数为必填 `source`(当前填写 `'appliance'`)、`viewId` 与可选 `scenePath`、`url`;仅恢复当前聚焦场景此前失败的资源。`appliance` 表示 Appliance Plugin 管理的背景图。 恢复结果为 `accepted: boolean`、`reloadedCount: number`,可选 `reason` 为 `viewNotFound`、`sceneNotFocused`、`resourceNotFound`、`alreadyLoading`。`accepted=true` 只表示已触发加载;成功与否结合加载事件判断。 ```java import com.herewhite.sdk.domain.HasBackgroundImageParams; import com.herewhite.sdk.domain.Promise; import com.herewhite.sdk.domain.ReloadBackgroundImageParams; import com.herewhite.sdk.domain.ReloadBackgroundImageResult; import com.herewhite.sdk.domain.SDKError; whiteSdk.hasBackgroundImage(new HasBackgroundImageParams( "mainView", "/scene/page1", "https://example.com/background.png", new String[]{"appliance"}), new Promise() { @Override public void then(Boolean exists) { /* 更新业务状态。 */ } @Override public void catchEx(SDKError error) { /* 处理接口错误。 */ } }); whiteSdk.reloadBackgroundImage(new ReloadBackgroundImageParams( "appliance", "mainView", "/scene/page1"), new Promise() { @Override public void then(ReloadBackgroundImageResult result) { // result.isAccepted() 只表示请求已接收。 } @Override public void catchEx(SDKError error) { /* 处理接口错误。 */ } }); ``` ## 回调 payload [#回调-payload] ```json { "name": "backgroundImageLoad", "state": "failed", "source": "appliance", "resourceId": "RESOURCE_ID", "resourceUrl": "https://example.com/image.png", "viewId": "VIEW_ID", "scenePath": "/scene/page1" } ``` `state` 为 `success/failed/cancelled`。插件进度事件字段为 `name: applianceInitLoadingChange`、`loading: boolean`、`phase: plugin/worker/scene/ready`、`status: start/success/timeout/error`。终态 `loading=false/phase=ready/status=success` 表示插件初始化就绪。 这些事件可用于业务诊断和 UI,字段名称及大小写须保持一致。完整签名见[客户端 API](/zh-CN/api-reference/whiteboard/whiteboard-sdk/android/overview)。 恢复参数中的可选 `url` 是替换重载地址,会替换目标场景中所有匹配失败资源的地址,不是按 URL 筛选某张图片;省略时使用各资源原地址。