下载/加载/扫描

Kivicube 在运行过程中，默认会展示三类状态 UI：

• 下载素材
• 加载场景
• 扫描识别

宿主页面可以选择保留默认 UI，也可以通过属性与事件自行接管。

下载进度

隐藏默认下载 UI

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideDownload: true,
});

自己接管下载进度

iframe.addEventListener('downloadAssetProgress', (event) => {
  const progress = event.detail;
  updateProgressBar(progress);
});

加载状态

隐藏默认加载 UI

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideLoading: true,
});

自己接管加载态

iframe.addEventListener('loadSceneStart', () => {
  showLoading();
});

iframe.addEventListener('loadSceneEnd', () => {
  hideLoading();
});

扫描状态

图像追踪和云识别类场景在未识别到目标时，会展示默认扫描 UI。

隐藏默认扫描 UI

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideScan: true,
});

宿主层自定义扫描提示

iframe.addEventListener('loadSceneEnd', () => {
  showScanHint();
});

iframe.addEventListener('tracked', () => {
  hideScanHint();
});

iframe.addEventListener('lostTrack', () => {
  showScanHint();
});

三类状态的推荐组合

轻定制

• 保留默认下载和加载
• 自定义扫描文案

中度定制

• 隐藏下载和加载
• 用宿主自己的进度条和首页内容
• 识别态也统一用宿主品牌样式

重度定制

• 隐藏所有默认流程 UI
• 宿主自己维护完整状态机
• 通过事件来驱动每一步切换

注意

当你隐藏默认 UI 后，宿主层就需要自己承担这些职责：

• 给用户明确反馈“当前在加载/下载/等待识别”
• 避免页面看起来像卡住
• 正确的管理自定义UI状态