背景图加载与恢复

  • HarmonyOS

更新时间

当前 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~103
timeoutMs1000~120000 毫秒15000
retryIntervalMs0~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 筛选某张图片;省略时使用各资源原地址。