# 背景图加载与恢复 (/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)。