属性

完整类型定义见插件 API。

所有属性名称，当在iframe标签上书写时，应使用全小写，单词用短横线连接方式(kebab-case)。

而在 JS 中书写时，应使用驼峰式(camelCase)。

html

<iframe
  id="kivicubeScene"
  scene-id="7A43keFojH0v98xvFP2w52aF8Y67Zbb5"
  hide-logo
></iframe>

布尔属性可省略 ="true"。

目前同时兼容三种写法：

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

但文档仍推荐使用标准的 HTML 写法，也就是 kebab-case。

注意：属性只在打开时读取一次。 场景或合辑开始打开后，再修改 iframe 上的属性不会生效；如需重新应用，必须重新执行 openKivicubeScene() 或 openKivicubeCollection()。

javascript

kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId: "7A43keFojH0v98xvFP2w52aF8Y67Zbb5",
  hideLogo: true,
})

注意水印

当属性被指定为非默认值时，如果使用插件的域名，未被授权，则会出现开发者水印。

场景属性

sceneId

类型	约束	默认值	示例值
string	32位字符，必填。	无	rDM7kXvo1UJKHnQUR46s7neoCSutDul9

用以指定打开的场景

获取方式：

1.登录平台 - https://cloud.kivicube.com/scenes

2.然后按图示步骤获取：

获取场景id图示

hideLogo

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏场景首页的Logo

hideTitle

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏首页标题。

hideDownload

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏素材下载进度。

cameraPosition

类型	约束	默认值	示例值
string	`front` / `back`	back	front

指定首次打开时优先使用的摄像头。

hideLoading

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏“加载场景”阶段的默认加载 UI。

hideStart

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否强制隐藏“立即体验”按钮。开启后，素材下载完成会直接进入场景。

注意

强制隐藏可能导致视频、音频自动播放能力受浏览器限制而失效，从而无法播放音频、视频。也可能导致部分设备无法打开摄像头。

如果你只是想调整“立即体验”按钮的位置、大小，或在宿主页覆盖一个自定义按钮，优先参考立即体验按钮中的 getStartButtonRect() / setStartButtonRect()，通常不需要先打开 hideStart。

hideScan

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏默认扫描 UI 和提示文案。

hideTakePhoto

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏默认拍照按钮。

hideBackground

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏场景背景。这个属性主要对 3D互动 场景有意义。

disableOpenUrl

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否禁用场景内“打开网页”行为。开启后，场景中的跳转动作不会执行，但宿主层仍然可以监听 openUrl 事件来决定是否自行处理。

合辑属性

合辑支持的大部分属性和场景一致，只是id从 sceneId 换成 collectionId，并额外支持 hideGyroscopePermission。

collectionId

类型	约束	默认值	示例值
string	6位字符，必填。	无	b46rfc

用于指定打开的合辑。

hideGyroscopePermission

类型	约束	默认值	示例值
boolean	选填	false	true、false

仅合辑支持。用于隐藏陀螺仪授权引导弹窗。

这个属性主要用于合辑中无陀螺仪需求时，期望不进行权限申请的情况。

其余属性和场景一致

场景与合辑的属性差异

属性	场景	合辑
`sceneId`	支持	不支持
`collectionId`	不支持	支持
`hideGyroscopePermission`	不支持	支持

其余属性两者完全一致。

属性 ​

场景属性 ​

sceneId ​

hideLogo ​

hideTitle ​

hideDownload ​

cameraPosition ​

hideLoading ​

hideStart ​

hideScan ​

hideTakePhoto ​

hideBackground ​

disableOpenUrl ​

合辑属性 ​

collectionId ​

hideGyroscopePermission ​

其余属性和场景一致 ​

场景与合辑的属性差异 ​

推荐做法 ​

属性