背景图加载与恢复

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