# 背景图加载与恢复 (/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/background-image-recovery)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" />
适用于 **Fastboard Android 1.8.2**。本页通过 Fastboard 公开的原生 SDK 对象配置教具插件。

在创建 FastRoom 前通过 `FastRoomOptions.getSdkConfiguration()` 与 `getRoomParams()` 设置配置。下面的 fastRoomOptions 为业务创建的房间选项。

```java
import com.herewhite.sdk.WhiteSdkConfiguration;
import com.herewhite.sdk.RoomParams;

WhiteSdkConfiguration config = fastRoomOptions.getSdkConfiguration();
config.setUseMultiViews(true);
config.setEnableAppliancePlugin(true);
RoomParams params = fastRoomOptions.getRoomParams();
```

入房成功后，通过 Fastboard 的公开 getter 获取下文使用的 Native 对象：

```java
import com.herewhite.sdk.Room;
import com.herewhite.sdk.WhiteSdk;

Room room = fastRoom.getRoom();
WhiteSdk whiteSdk = fastRoom.getWhiteSdk();
```

下文的 `params`、`config` 指 FastRoomOptions 返回的配置；通过 Fastboard 创建 SDK 和加入房间。

当前 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<Boolean>)` 查询；`reloadBackgroundImage(ReloadBackgroundImageParams, Promise<ReloadBackgroundImageResult>)` 恢复。事件通过 `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<String, Object> 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<Boolean>() {
    @Override public void then(Boolean exists) { /* 更新业务状态。 */ }
    @Override public void catchEx(SDKError error) { /* 处理接口错误。 */ }
});
whiteSdk.reloadBackgroundImage(new ReloadBackgroundImageParams(
    "appliance", "mainView", "/scene/page1"), new Promise<ReloadBackgroundImageResult>() {
    @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/fastboard/android)。

恢复参数中的可选 `url` 是替换重载地址，会替换目标场景中所有匹配失败资源的地址，不是按 URL 筛选某张图片；省略时使用各资源原地址。
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" />
适用于 **Fastboard iOS 1.4.6**。本页通过 Fastboard 公开的原生 SDK 对象配置教具插件。

在创建 FastRoom 前设置配置，入房成功后使用 `fastRoom.room` 和 `fastRoom.whiteSDK`。delegate 通过 `fastRoom.commonDelegate`、`roomDelegate` 设置，避免覆盖 Fastboard 内部代理。

```swift
let config = FastRoomConfiguration(appIdentifier: appIdentifier,
    roomUUID: uuid, roomToken: roomToken, region: .CN, userUID: uid)
config.whiteSdkConfiguration.useMultiViews = true
config.whiteSdkConfiguration.enableAppliancePlugin = true
let pluginOptions = WhiteAppliancePluginOptions()
pluginOptions.extras = ["useBackgroundThread": true]
config.whiteRoomConfig.appliancePluginOptions = pluginOptions
let fastRoom = Fastboard.createFastRoom(withFastRoomConfig: config)
```

以下 Objective-C 示例也可用于原生调用：`config` 表示 `FastRoomConfiguration.whiteSdkConfiguration`，`roomConfig` 表示 `whiteRoomConfig`，`room`、`whiteSDK` 分别来自已入房 FastRoom 的同名属性。

开启 `useMultiViews`、`enableAppliancePlugin`，并在插件 extras 中开启 `useBackgroundThread`。

## 加载策略 [#加载策略]

```objc
WhiteBackgroundImageLoadOptions *load = [WhiteBackgroundImageLoadOptions new];
load.maxRetries = 3;
load.timeoutMs = 15000;
load.retryIntervalMs = 1000;
config.backgroundImageLoadOptions = load;
```

初始化 SDK 前设置。`maxRetries` 为 -1 或 0～10，`timeoutMs` 为 1000～120000 毫秒，`retryIntervalMs` 为 0～30000 毫秒；默认分别为 3、15000、1000。当前背景图来源为 `appliance`。

## 查询和恢复插件背景图 [#查询和恢复插件背景图]

```objc
WhiteHasBackgroundImageParams *query = [WhiteHasBackgroundImageParams new];
query.viewId = @"mainView";
query.scenePath = @"/init/1";
query.imageUrl = @"https://example.com/background.png";
query.sources = @[@"appliance"];
[whiteSDK hasBackgroundImage:query completionHandler:^(BOOL exists, NSError *error) {
    NSLog(@"exists=%d error=%@", exists, error);
}];

WhiteReloadBackgroundImageParams *retry = [WhiteReloadBackgroundImageParams new];
retry.source = @"appliance";
retry.viewId = @"mainView";
retry.scenePath = @"/init/1";
[whiteSDK reloadBackgroundImage:retry completionHandler:^(WhiteReloadBackgroundImageResult *result, NSError *error) {
    NSLog(@"accepted=%d count=%ld error=%@", result.accepted, (long)result.reloadedCount, error);
}];
```

恢复针对当前聚焦场景此前失败的背景资源；`accepted` 表示请求已接收，不表示加载成功。`reloadedCount` 表示触发重载的图片数量。

通过 `WhiteCommonCallbackDelegate.onBackgroundImageLoad:`、`onApplianceInitLoadingChange:` 接收事件，参数类型分别为 `WhiteBackgroundImageLoadEvent`、`WhiteApplianceInitLoadingChangeEvent`，保留 state/source/resourceUrl/viewId/scenePath 或 loading/phase/status 等字段。

## 普通图片 [#普通图片]

原生普通图片使用 `WhiteRoom.insertImage:src:`。锁定普通图片仅限制其编辑，不能将它转为插件背景资源；因此普通图片不使用上述背景存在性查询和恢复接口。插件背景可由房间内已经启用插件的 Web 端插入后同步显示。

恢复参数中的可选 `url` 是替换重载地址，会替换目标场景中所有匹配失败资源的地址，不是按 URL 筛选某张图片；省略时使用各资源原地址。
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" />
适用于 **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)。
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>