背景图加载与恢复

当前 SDK 提供 Appliance Plugin 背景图加载状态、失败恢复及插件初始化进度能力。使用背景图查询和恢复前，需同时开启 useMultiViews=true 与 enableAppliancePlugin=true。

配置

TypeScript

// 创建 Whiteboard 组件前配置。
options.backgroundImageLoadOptions = {
  maxRetries: 3, timeoutMs: 15000, retryIntervalMs: 1000
};

controller.hasBackgroundImage(params): Promise<boolean> 查询；controller.reloadBackgroundImage(params): Promise<ReloadBackgroundImageResult> 恢复。事件通过 callbacks.onBackgroundImageLoad / onApplianceInitLoadingChange 接收。

配置	范围	默认值
maxRetries	-1（无限重试）或整数 0~10	3
timeoutMs	1000~120000 毫秒	15000
retryIntervalMs	0~30000 毫秒	1000

配置插件背景图加载

应用可对房间中的插件背景资源配置显示、加载重试、存在性查询和失败恢复。在创建 Whiteboard 组件前启用背景线程：

TypeScript

options.appliancePluginOptions = {
  extras: { useBackgroundThread: true }
};

加载重试策略通过 WhiteboardOptions.backgroundImageLoadOptions 设置；已有其他 extras 字段时，将 useBackgroundThread 合并到同一个配置对象。

插入普通图片（Native 接口）

在入房成功、房间可写时，可使用 controller.insertImage(...) 插入普通图片：

TypeScript

import { ImageInformation } from '@shengwang/whiteboard';
import { util } from '@kit.ArkTS';

const image: ImageInformation = {
  uuid: util.generateRandomUUID(),
  url: 'https://example.com/image.png',
  centerX: 0,
  centerY: 0,
  width: 1280,
  height: 720
};
controller.insertImage(image);

图片位置和尺寸使用白板世界坐标，url 为可访问的图片地址。该方法同时提交图片区域和图片 URL，无需另行调用上传完成方法。

该方式插入的是普通图片元素，不会自动转换为 Appliance Plugin 专用背景图。下方 hasBackgroundImage 与 reloadBackgroundImage 针对插件管理的背景资源，不用于查询或重载这个普通图片元素。

查询与恢复参数

查询参数为 viewId、scenePath、imageUrl 和背景图来源列表 sources，当前填写 ['appliance']。恢复参数为必填 source（当前填写 'appliance'）、viewId 与可选 scenePath、url；仅恢复当前聚焦场景此前失败的资源。appliance 表示 Appliance Plugin 管理的背景图。

恢复结果为 accepted: boolean、reloadedCount: number，可选 reason 为 viewNotFound、sceneNotFocused、resourceNotFound、alreadyLoading。accepted=true 只表示已触发加载；成功与否结合加载事件判断。

TypeScript

// 入房成功后的异步函数体，需处理 Promise rejection。
const exists: boolean = await controller.hasBackgroundImage({
  viewId: 'mainView',
  scenePath: '/scene/page1',
  imageUrl: 'https://example.com/background.png',
  sources: ['appliance']
});
const result = await controller.reloadBackgroundImage({
  source: 'appliance',
  viewId: 'mainView',
  scenePath: '/scene/page1'
});
// result.accepted 只表示请求已接收。

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