Collection API

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

获取方式

获取合辑高级 API

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

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

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

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

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

适用范围

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

它负责：

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

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

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

通用约定

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

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 完整签名

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>;
}

立即体验按钮

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

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

场景管理

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

openScene(sceneId)

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

await api.openScene('7A43keFojH0v98xvFP2w52aF8Y67Zbb5');

参数

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

说明

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

closeCurrentScene()

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

await api.closeCurrentScene();

说明

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

backToScan()

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

await api.backToScan();

说明

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

云识别

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

startCloudar(collectionId?, sceneList?)

开始云识别扫描流程。

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

参数

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

返回值

Promise<string>

返回识别命中的场景 ID。

说明

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

stopCloudar()

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

await api.stopCloudar();

说明

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

拍照

takePhoto(): Promise<string>

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

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

返回值

Promise<string>

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

说明

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

和 Scene API 的关系

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

CollectionApi

适合：

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

SceneApi

适合：

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

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

let collectionApi = null;
let sceneApi = null;

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

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

相关 Guide

• 高级API
• 事件
• 立即体验按钮
• 开关一个场景/合辑