插件 API

本页描述宿主页面直接调用的全局插件接口。

全局对象

当你引入：

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

宿主页面可直接使用全局对象：

window.kivicubeIframePlugin

常见调用通常写成：

kivicubeIframePlugin.openKivicubeScene(...)

打开场景

openKivicubeScene(
  iframe: HTMLIFrameElement,
  props?: SceneOpenProps,
  modifyIframe?: boolean,
): Promise<{
  id: string;
  allow: string;
  src: string;
}>

参数

iframe

承载 Kivicube 内容的 iframe DOM。

props

场景打开参数，见下方 SceneOpenProps。

modifyIframe

是否立即把生成后的 id、allow、src 写回到 iframe。

• 默认 true
• 为 false 时，只返回计算结果，不修改 DOM，适用于Vue/React组件封装。

返回值

interface OpenResult {
  id: string;
  allow: string;
  src: string;
}

销毁场景

destroyKivicubeScene(iframe: HTMLIFrameElement): void

它会清理当前 iframe 对应的内部资源。常与把 iframe.src 切到空白页一起使用。

注意：如果要在同一页面切换多个场景，销毁上一个场景时，一定要调用destroyKivicubeScene方法

打开合辑

openKivicubeCollection(
  iframe: HTMLIFrameElement,
  props?: CollectionOpenProps,
  modifyIframe?: boolean,
): Promise<{
  id: string;
  allow: string;
  src: string;
}>

与 openKivicubeScene() 基本一致，只是 props 换成合辑版本。

销毁合辑

destroyKivicubeCollection(iframe: HTMLIFrameElement): void

属性对象

SceneOpenProps

interface SceneOpenProps {
  sceneId: string;
  hideLogo?: boolean;
  hideTitle?: boolean;
  hideDownload?: boolean;
  cameraPosition?: 'front' | 'back';
  hideLoading?: boolean;
  hideScan?: boolean;
  hideTakePhoto?: boolean;
  hideBackground?: boolean;
  hideStart?: boolean;
  disableOpenUrl?: boolean;
}

CollectionOpenProps

interface CollectionOpenProps {
  collectionId: string;
  hideLogo?: boolean;
  hideTitle?: boolean;
  hideDownload?: boolean;
  cameraPosition?: 'front' | 'back';
  hideLoading?: boolean;
  hideScan?: boolean;
  hideTakePhoto?: boolean;
  hideStart?: boolean;
  hideGyroscopePermission?: boolean;
  disableOpenUrl?: boolean;
}

HTML 属性读取规则

插件会从 iframe 上读取支持的属性，并同时兼容：

• kebab-case：hide-logo
• camelCase：hideLogo
• data 属性：data-hide-logo

调用 openKivicubeScene() / openKivicubeCollection() 时，JS 传入的 props 会覆盖 HTML 上的同名属性。

自动打开规则

场景

如果页面存在：

<iframe id="kivicubeScene" scene-id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"></iframe>

并且该节点在 DOMContentLoaded 触发前已存在，插件会自动执行 openKivicubeScene()。

合辑

如果页面存在：

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

则会自动执行 openKivicubeCollection()。

自动写入的 allow 权限

插件会自动写入需要的权限：

xr-spatial-tracking;camera;microphone;autoplay;fullscreen;gyroscope;accelerometer

相关 Guide

• 开关一个场景/合辑
• 属性
• 权限处置