# 背景图加载与恢复 (/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/background-image-recovery/web) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 适用于 **Appliance Plugin 1.1.45**。先完成[启用插件](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/overview),开启 `extras.useBackgroundThread=true`。 ## 加载策略 [#加载策略-1] 初始化时设置 `extras.backgroundImageLoadOptions`: ```typescript import type { ExtrasOptions } from '@netless/appliance-plugin'; const extras: ExtrasOptions = { useBackgroundThread: true, backgroundImageLoadOptions: { maxRetries: 3, timeoutMs: 15000, retryIntervalMs: 1000 } }; ``` `maxRetries` 为 -1 或整数 0~10,-1 表示无限重试;`timeoutMs` 范围 1000~120000 毫秒;`retryIntervalMs` 范围 0~30000 毫秒。默认分别为 3、15000、1000。当前背景图来源为 `appliance`。 ## 插入背景图 [#插入背景图] ```typescript plugin.insertBackgroundImage('mainView', { uuid: 'background-unique-id', src: 'https://example.com/background.png', centerX: 0, centerY: 0, width: 1280, height: 720, locked: true }); ``` 该 API 插入由插件管理的固定背景资源。普通可框选图片使用 SDK/插件的 `insertImage` 和 `completeImageUpload`;锁定普通图片仍不会将其转换成插件背景图。两类资源不能混用存在性查询与恢复接口。 ## 查询与恢复 [#查询与恢复] ```typescript const exists = plugin.hasBackgroundImage({ viewId: 'mainView', scenePath: '/init/1', imageUrl: 'https://example.com/background.png', sources: ['appliance'] }); const result = await plugin.reloadBackgroundImage({ source: 'appliance', viewId: 'mainView', scenePath: '/init/1' }); console.log(exists, result.accepted, result.reloadedCount, result.reason); ``` 查询按 View、场景和原始 URL 匹配。恢复针对当前聚焦场景此前失败的资源;可选 `url` 是替换重载地址,会用于该目标场景所有匹配的失败资源,不用于筛选某一张图片;省略时按各资源原地址恢复。`accepted` 表示请求被接受,`reloadedCount` 表示触发重载数量,加载结果需继续观察回调。 ## 加载与初始化回调 [#加载与初始化回调] 通过 `ApplianceAdaptor.callbacks.onBackgroundImageLoadEvent` 和 `onInitLoadingChange` 监听;Fastboard 使用 `appliancePluginAdaptor.callbacks`。背景回调包含 state(success/failed/cancelled)、source、resourceId、resourceUrl、viewId、scenePath。初始化包含 loading、phase、status;ready/success 用于插件就绪判断。 这两个回调属于 adaptor callbacks。插件 `PublicListener` 事件见[事件监听与元素查询](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/events-and-query)。