Kivicube文档

简体中文

English

主题

插件 API ​

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

全局对象 ​

当你引入：

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

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

js
window.kivicubeIframePlugin

常见调用通常写成：

js
kivicubeIframePlugin.openKivicubeScene(...)

打开场景 ​

ts
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组件封装。

返回值 ​

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

销毁场景 ​

ts
destroyKivicubeScene(iframe: HTMLIFrameElement): void

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

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

打开合辑 ​

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

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

销毁合辑 ​

ts
destroyKivicubeCollection(iframe: HTMLIFrameElement): void

属性对象 ​

SceneOpenProps ​

ts
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 ​

ts
interface CollectionOpenProps {
  collectionId: string;
  hideLogo?: boolean;
  hideTitle?: boolean;
  hideDownload?: boolean;
  cameraPosition?: 'front' | 'back';
  hideLoading?: boolean;
  hideScan?: boolean;
  hideBackToScan?: 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 上的同名属性。

自动打开规则 ​

场景 ​

如果页面存在：

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

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

合辑 ​

如果页面存在：

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

则会自动执行 openKivicubeCollection()。

自动写入的 allow 权限 ​

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

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

相关 Guide ​