背景图加载与恢复

适用于 Appliance Plugin 1.1.45。先完成启用插件，开启 extras.useBackgroundThread=true。

加载策略

初始化时设置 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 事件见事件监听与元素查询。