Kivicube文档

简体中文

English

主题

Collection API ​

本页描述合辑页运行时可用的高级 API。

获取方式 ​

获取合辑高级 API ​

js
iframe.addEventListener('ready', (event) => {
  const api = event.detail.api;
  const collectionInfo = event.detail.collectionInfo;
});

此时 event.detail.api 为 CollectionApi，用于控制合辑整体流程。

获取合辑中当前场景的高级 API ​

js
iframe.addEventListener('sceneReady', (event) => {
  const api = event.detail.api;
  const sceneInfo = event.detail.sceneInfo;
});

此时 event.detail.api 为 SceneApi，和单独打开场景时拿到的场景高级 API 一致。

适用范围 ​

当前这套 API 主要适用于合辑页面。

它负责：

  • 读取或调整合辑首页“立即体验”按钮的样式和布局
  • 控制合辑内部打开哪个场景
  • 关闭当前场景
  • 在云识别合辑中开始或停止识别
  • 让合辑回到扫描态
  • 对当前已打开场景执行拍照

它不负责直接操作场景中的对象、模型、视频、灯光等内容。

如果你需要在合辑中进一步控制某个场景的运行时内容，应等待 sceneReady 事件，再使用其中的 SceneApi。

通用约定 ​

全部方法都应按异步方法处理 ​

js
await api.openScene('7A43keFojH0v98xvFP2w52aF8Y67Zbb5');
await api.closeCurrentScene();

即便某些方法最终只是触发一个流程切换，也推荐统一使用 await。

ready 和 sceneReady 中的 api 类型不同 ​

  • ready.detail.api：CollectionApi
  • sceneReady.detail.api：SceneApi

最常见的组合是：

  1. 在 ready 中拿到合辑信息和 CollectionApi
  2. 在 sceneReady 中拿到当前场景信息和 SceneApi
  3. 用 CollectionApi 切场景、回扫描、启停云识别
  4. 用 SceneApi 控制当前场景内部对象

合辑 API 不能直接操作场景内容 ​

下面这类能力不属于 CollectionApi：

  • 获取对象、修改位置、旋转、缩放
  • 新增图片、模型、视频
  • 控制灯光、色调映射、环境贴图
  • 监听对象点击、视频播放结束等对象级事件

这些都属于 SceneApi，应在 sceneReady 中获取后再调用。

CollectionApi 完整签名 ​

ts
interface CollectionApi {
  getStartButtonRect(): Promise<DOMRect | undefined>;
  setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>;

  backToScan(): Promise<void>;
  openScene(sceneId: string): Promise<void>;
  closeCurrentScene(): Promise<void>;

  startCloudar(
    collectionId?: string,
    sceneList?: string[],
  ): Promise<string>;
  stopCloudar(): Promise<void>;

  takePhoto(): Promise<string>;
}

立即体验按钮 ​

ts
getStartButtonRect(): Promise<DOMRect | undefined>
setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>

用于读取或调整合辑首页“立即体验”按钮的样式和布局。

场景管理 ​

ts
backToScan(): Promise<void>
openScene(sceneId: string): Promise<void>
closeCurrentScene(): Promise<void>

openScene(sceneId) ​

打开合辑中的某个具体场景。

js
await api.openScene('7A43keFojH0v98xvFP2w52aF8Y67Zbb5');

参数 ​

  • sceneId：要打开的场景 ID。通常应来自当前合辑的 collectionInfo.sceneList。

说明 ​

  • 适合做“场景目录”“下一场景”“指定场景跳转”等宿主层交互。
  • 如果当前场景还处于打开过程中，调用可能会被拒绝；更稳妥的做法是等待 sceneStart 之后再切换到其他场景。
  • 打开成功后，合辑会触发新的 sceneReady、下载、加载和 sceneStart 等流程事件。

closeCurrentScene() ​

关闭合辑中当前已打开的场景。

js
await api.closeCurrentScene();

说明 ​

  • 适合在宿主层主动结束当前体验，或在切到其他场景前显式清理。
  • 成功关闭时，合辑会触发 sceneDestroy 事件。
  • 如果当前没有可关闭的场景，调用可能会失败。

backToScan() ​

让合辑从当前场景返回到扫描状态。

js
await api.backToScan();

说明 ​

  • 主要用于云识别合辑。
  • 它会先关闭当前场景，再重新进入识别流程。
  • 对非云识别合辑没有实际意义。

云识别 ​

ts
startCloudar(collectionId?: string, sceneList?: string[]): Promise<string>
stopCloudar(): Promise<void>

startCloudar(collectionId?, sceneList?) ​

开始云识别扫描流程。

js
const sceneId = await api.startCloudar(
  collectionInfo.collectionId,
  collectionInfo.sceneList,
);

参数 ​

  • collectionId：可选。默认使用当前已打开的合辑 ID。
  • sceneList：可选。只有当场景列表中指定的场景扫描到后，才返回识别到。否则继续识别扫描。默认值为当前合辑中和合辑类型一致的所有场景列表。

返回值 ​

ts
Promise<string>

返回识别命中的场景 ID。

说明 ​

  • 只对云识别合辑有意义。
  • 如果传入 sceneList，则只会从这些场景中返回识别结果。
  • 一个常见用法是从候选列表中过滤掉当前已经打开的场景，避免重复识别回当前场景。

stopCloudar() ​

停止当前云识别扫描流程。

js
await api.stopCloudar();

说明 ​

  • 只对云识别合辑有意义。
  • 适合在宿主层接管识别前置流程、弹出自定义浮层、或临时暂停识别时使用。

拍照 ​

ts
takePhoto(): Promise<string>

对当前已打开的合辑场景执行拍照。

js
const photo = await api.takePhoto();
previewImg.src = photo;

返回值 ​

ts
Promise<string>

返回 data:image/png;base64,... 格式的图片地址。

说明 ​

  • 当前暂时需要有一个已经打开的场景【后续支持没有场景时也能拍照】。
  • 与场景 SceneApi.takePhoto() 基本一致：通常是当前可见内容的合成结果。

和 Scene API 的关系 ​

在合辑页面中，两类 API 会同时出现，但职责不同：

CollectionApi ​

适合：

  • 读取或调整合辑首页“立即体验”按钮区域
  • 打开合辑中的某个场景
  • 关闭当前场景
  • 回到扫描态
  • 开始或停止云识别
  • 在当前场景上拍照

SceneApi ​

适合：

  • 获取对象并修改位置、旋转、缩放
  • 动态创建图片、模型、视频、灯光等
  • 控制视频、动图、动画
  • 调整相机、渲染与材质
  • 监听对象级事件

因此，对合辑的典型调用组织方式通常是：

js
let collectionApi = null;
let sceneApi = null;

iframe.addEventListener('ready', (event) => {
  collectionApi = event.detail.api;
});

iframe.addEventListener('sceneReady', (event) => {
  sceneApi = event.detail.api;
});

相关 Guide ​