# 背景图加载与恢复 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/appliance-plugin/background-image-recovery/harmonyos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 当前 SDK 提供 Appliance Plugin 背景图加载状态、失败恢复及插件初始化进度能力。使用背景图查询和恢复前,需同时开启 `useMultiViews=true` 与 `enableAppliancePlugin=true`。 ## 配置 [#配置-1] ```typescript // 创建 Whiteboard 组件前配置。 options.backgroundImageLoadOptions = { maxRetries: 3, timeoutMs: 15000, retryIntervalMs: 1000 }; ``` `controller.hasBackgroundImage(params): Promise` 查询;`controller.reloadBackgroundImage(params): Promise` 恢复。事件通过 `callbacks.onBackgroundImageLoad` / `onApplianceInitLoadingChange` 接收。 | 配置 | 范围 | 默认值 | | --- | --- | --- | | `maxRetries` | -1(无限重试)或整数 0~10 | 3 | | `timeoutMs` | 1000~120000 毫秒 | 15000 | | `retryIntervalMs` | 0~30000 毫秒 | 1000 | ## 配置插件背景图加载 [#配置插件背景图加载-1] 应用可对房间中的插件背景资源配置显示、加载重试、存在性查询和失败恢复。在创建 Whiteboard 组件前启用背景线程: ```typescript options.appliancePluginOptions = { extras: { useBackgroundThread: true } }; ``` 加载重试策略通过 `WhiteboardOptions.backgroundImageLoadOptions` 设置;已有其他 extras 字段时,将 `useBackgroundThread` 合并到同一个配置对象。 ## 插入普通图片(Native 接口) [#插入普通图片native-接口] 在入房成功、房间可写时,可使用 `controller.insertImage(...)` 插入普通图片: ```typescript import { ImageInformation } from '@shengwang/whiteboard'; import { util } from '@kit.ArkTS'; const image: ImageInformation = { uuid: util.generateRandomUUID(), url: 'https://example.com/image.png', centerX: 0, centerY: 0, width: 1280, height: 720 }; controller.insertImage(image); ``` 图片位置和尺寸使用白板世界坐标,`url` 为可访问的图片地址。该方法同时提交图片区域和图片 URL,无需另行调用上传完成方法。 该方式插入的是普通图片元素,不会自动转换为 Appliance Plugin 专用背景图。下方 `hasBackgroundImage` 与 `reloadBackgroundImage` 针对插件管理的背景资源,不用于查询或重载这个普通图片元素。 ## 查询与恢复参数 [#查询与恢复参数-1] 查询参数为 `viewId`、`scenePath`、`imageUrl` 和背景图来源列表 `sources`,当前填写 `['appliance']`。恢复参数为必填 `source`(当前填写 `'appliance'`)、`viewId` 与可选 `scenePath`、`url`;仅恢复当前聚焦场景此前失败的资源。`appliance` 表示 Appliance Plugin 管理的背景图。 恢复结果为 `accepted: boolean`、`reloadedCount: number`,可选 `reason` 为 `viewNotFound`、`sceneNotFocused`、`resourceNotFound`、`alreadyLoading`。`accepted=true` 只表示已触发加载;成功与否结合加载事件判断。 ```typescript // 入房成功后的异步函数体,需处理 Promise rejection。 const exists: boolean = await controller.hasBackgroundImage({ viewId: 'mainView', scenePath: '/scene/page1', imageUrl: 'https://example.com/background.png', sources: ['appliance'] }); const result = await controller.reloadBackgroundImage({ source: 'appliance', viewId: 'mainView', scenePath: '/scene/page1' }); // result.accepted 只表示请求已接收。 ``` ## 回调 payload [#回调-payload-1] ```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/harmonyos/overview)。 恢复参数中的可选 `url` 是替换重载地址,会替换目标场景中所有匹配失败资源的地址,不是按 URL 筛选某张图片;省略时使用各资源原地址。