背景图加载与恢复

适用于 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 图片接口，并设置 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

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。

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

适用于 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。

加载策略

Objective-C

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。

查询和恢复插件背景图

Objective-C

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 筛选某张图片；省略时使用各资源原地址。

适用于 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 事件见事件监听与元素查询。

配置

插入固定图片（Native 接口）

配置插件背景图加载

查询与恢复参数

回调 payload

加载策略

查询和恢复插件背景图

普通图片

加载策略

插入背景图

查询与恢复

加载与初始化回调

咨询电话

咨询电话

加载策略Copy Anchor Link

插入背景图Copy Anchor Link

查询与恢复Copy Anchor Link

加载与初始化回调Copy Anchor Link

咨询电话

咨询电话

加载策略

插入背景图

查询与恢复

加载与初始化回调