开关一个场景/合辑

完整函数签名见：

• 插件 API / openKivicubeScene
• 插件 API / openKivicubeCollection

打开

场景

打开场景有两种方式：自动打开和手动打开。

自动打开

当页面里存在如下结构时，插件脚本会自动打开：

<script src="https://www.kivicube.com/lib/iframe-plugin.js"></script>
<iframe id="kivicubeScene" scene-id="7A43keFojH0v98xvFP2w52aF8Y67Zbb5"></iframe>

自动打开的前提是：

• iframe.id === "kivicubeScene"
• 已声明有效的 scene-id
• 该 iframe 在 DOMContentLoaded 触发之前就已存在

手动打开

<script src="https://www.kivicube.com/lib/iframe-plugin.js"></script>

<iframe id="sceneHost"></iframe>

<script>
  const iframe = document.getElementById('sceneHost');

  kivicubeIframePlugin.openKivicubeScene(iframe, {
    sceneId: '7A43keFojH0v98xvFP2w52aF8Y67Zbb5',
    hideLogo: true,
    hideTitle: true,
    cameraPosition: 'back',
  });
</script>

openKivicubeScene() 的特点：

• 第一个参数必须是 HTMLIFrameElement对象
• 第二个参数是属性对象，会覆盖 iframe 标签上已写的同名属性
• 执行后插件会自动补齐 iframe.id、iframe.allow、iframe.src
• 返回值是一个 Promise，结果中包含 { id, allow, src }

仅获取拼装后的地址

还提供了第三个参数 modifyIframe = true。如果传 false，可以只拿到最终生成的 src 和 allow，而不立即写回到 iframe 元素上：

const result = await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId: '7A43keFojH0v98xvFP2w52aF8Y67Zbb5',
}, false);

console.log(result.src, result.allow);

这个用法更适合调试或做自定义封装(Vue/React组件)，常规接入保持默认值即可。

合辑

合辑与场景的方式完全对应，只是把 API 和标识换成合辑版本：

<iframe id="kivicubeCollection" collection-id="b46rfc"></iframe>

或手动打开：

await kivicubeIframePlugin.openKivicubeCollection(iframe, {
  collectionId: 'b46rfc',
  hideLogo: true,
  hideGyroscopePermission: true,
});

约束区别主要有两点：

• 合辑 ID 为 6 位
• 合辑支持 hideGyroscopePermission，场景不支持

打开后该做什么

通常你应在 iframe 上监听 ready 事件：

iframe.addEventListener('ready', (event) => {
  console.log(event.detail);
});

对于场景，event.detail.api 会提供可调用的高级 API。

对于合辑，event.detail.api 也会提供可调用的高级 API，和场景的高级API提供的接口不一样。

关闭

场景

推荐做法是：

1. 把 iframe 切换到一个空白页【适合后续还会打开其他场景】
2. 调用销毁方法清理内部资源

iframe.src = 'https://www.kivicube.com/lib/empty.html';
kivicubeIframePlugin.destroyKivicubeScene(iframe);

如果你的流程就会移除这个 iframe DOM，也可以直接移除节点，但在宿主层手动调用 destroyKivicubeScene() 仍然是必须的做法。

合辑

合辑同理：

iframe.src = 'https://www.kivicube.com/lib/empty.html';
kivicubeIframePlugin.destroyKivicubeCollection(iframe);

推荐封装

在业务项目里，通常建议把“打开”和“关闭”分别封装成两个函数，避免在多个页面里重复写：

export async function openScene(iframe, sceneId) {
  return kivicubeIframePlugin.openKivicubeScene(iframe, { sceneId });
}

export function closeScene(iframe) {
  iframe.src = 'https://www.kivicube.com/lib/empty.html';
  kivicubeIframePlugin.destroyKivicubeScene(iframe);
}