Kivicube文档

简体中文

English

主题

下载/加载/扫描 ​

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

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

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

下载进度 ​

隐藏默认下载 UI ​

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

自己接管下载进度 ​

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

加载状态 ​

隐藏默认加载 UI ​

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

自己接管加载态 ​

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

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

扫描状态 ​

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

隐藏默认扫描 UI ​

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

宿主层自定义扫描提示 ​

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

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

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

三类状态的推荐组合 ​

轻定制 ​

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

中度定制 ​

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

重度定制 ​

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

注意 ​

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

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