高级API

完整签名和方法总表请直接参考

场景高级 API 用于在宿主页面中直接操作 iframe 的场景内容。

合辑高级 API 用于在宿主页面中直接控制 iframe 的场景整体，对场景进行打开或关闭，不能直接操作场景内容。

如果你想在合辑中操作场景内容(增删改)，需要先打开一个场景，再通过场景的高级API去操作。

你可以用它来：

读取或调整“立即体验”按钮的样式和布局
获取场景对象并修改位置、旋转、显隐等
动态创建图片、模型、视频、灯光、组合等
控制视频、GIF、动画播放等
调整相机、色调映射、环境贴图、各向异性等
监听对象级事件，例如点击、播放、暂停、结束等
打开场景、关闭场景、打开云识别扫描、停止扫描等。

注意水印

当调用了任何一个API时，如果使用插件的域名，未被授权，则会出现开发者水印。

获取高级API对象

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

detail.api 就是高级 API 对象。场景和合辑都是一样的方式。

而在合辑中获取场景高级API：

iframe.addEventListener("sceneReady", (event) => {
  const { detail } = event;
  const { api } = detail;
  console.log(api);

高级API的通用特性

所有API都是async函数

因为和iframe之间通信机制的天然异步性，导致所有api调用、属性获取、属性设置等实现，都是异步。

因此，在开发时，一定要对所有api调用使用await语法。除非不在意结果。

const image = await api.getObject("object-name");
await api.setPosition(image, 1, 0, 0);

获取到的对象都只是句柄(Handle)

也可理解为指针，只是一个对象引用，没有任何属性和方法可用，不能直接控制对象。

const image = await api.getObject("object-name");

image.position.set(1, 0, 0); // ❌ 错误

await api.setPosition(image, 1, 0, 0); // ✅ 正确

因此你不能直接改 image.position.x，而必须通过 api.setPosition() 这类方法间接操作。

差异说明

目前detail.api提供的都是较为底层的API，使用起来不那么直观。

而后续会增加类似我们小程序插件中提供的对象级属性、API支持。

这也是为什么event.detail对象不是view对象，而是通过detail.api获取，和小程序插件中不一致的原因。

使用URL新增内容时，需要跨域支持

我们支持在场景编辑器中搭建好内容的基础上，使用高级API对内容进行增加、删除或修改等操作。

而在新增内容时，需要传递文件，支持几种传递方式：ArrayBuffer、Blob、File或者URL。

如果传递 URL 给插件，则需要确保 URL 所在服务器允许 https://www.kivicube.com 跨域访问。

例如：

const image = await api.createImage("https://your.domain.com/path/to/image.jpg");
await api.add(image);

此时 your.domain.com 所在服务器需要对 Kivicube 域名开放跨域访问。

如果你使用nginx，可增加如下所示代码：

nginx

server {
  # 储存素材文件的目录
  location /path/to {
    add_header Access-Control-Allow-Origin "https://www.kivicube.com" always;
  }
}

如果你使用阿里云OSS，可参考https://help.aliyun.com/zh/oss/user-guide/cors-settings
如果你使用腾讯云COS，可参考https://cloud.tencent.com/document/product/436/13318
如果你使用七牛云Kodo，可参考https://developer.qiniu.com/kodo/8539/set-the-cross-domain-resource-sharing
如果你使用AWS S3，可参考https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html

核心要求是响应头中包含：

text

Access-Control-Allow-Origin: https://www.kivicube.com

如果传递ArrayBuffer、Blob、File(意味着需要使用者自行进行文件下载)，此时可忽略Cors配置【假设使用者都是同域】。

const response = await fetch("https://your.domain.com/path/to/image.jpg");
if (response.ok) {
  const imageAb = await response.arrayBuffer();
  const image = await api.createImage(imageAb);
  await api.add(image);
}

Scene API能力总览

立即体验按钮

参考：Scene API / 立即体验按钮

getStartButtonRect()
setStartButtonRect(rect)

对象查询与基础属性

参考：Scene API / 对象查询与基础属性

getObject(name)
getAllObject()
getObjectName() / setObjectName()
getObjectVisible() / setObjectVisible()
getRenderOrder() / setRenderOrder()
getDisableClick() / setDisableClick()
getSize()
lookAt()
getPosition() / setPosition()
getRotation() / setRotation()
getQuaternion() / setQuaternion()
getScale() / setScale()

层级和生命周期

参考：Scene API / 对象层级与生命周期

addChild() / removeChild()
getChildren() / getChildByProperty()
add()
remove()
destroyObject()
clear()

动态创建内容

参考：Scene API / 动态创建内容

createImage()
createAnimatedImage()
createGltfModel()
createVideo()
createAlphaVideo()
createKeyingVideo()
createPanorama()
createGroup()
createAmbientLight()
createDirectionalLight()
createEnvMapByHDR()

媒体与动画控制

Scene API / 动图 - getAnimatedImagePaused() / playAnimatedImage() / pauseAnimatedImage() / stopAnimatedImage()
Scene API / 视频 - getVideoDuration() / getVideoPaused() / getVideoCurrentTime() / setVideoCurrentTime() / getVideoLoop() / setVideoLoop() / playVideo() / pauseVideo() / stopVideo() / playbackVideo()
Scene API / 音频 - getAudioDuration() / getAudioPaused() / getAudioCurrentTime() / setAudioCurrentTime() / getAudioLoop() / setAudioLoop() / playAudio() / pauseAudio() / stopAudio() / playbackAudio()
Scene API / 动画 - playAnimation() / pauseAnimation() / stopAnimation() / playbackAnimation() / getAnimationNames() / isAnimationLoop() / getAnimationIsRunningNames()

渲染与光照

参考：Scene API / 渲染与材质、 Scene API / 光照

setEnableMask() / setDisableMask()
setGLState()
setAnisotropy()
setObjectAlpha()
getDefaultAmbientLight()
getDefaultDirectionalLightLeft() / getDefaultDirectionalLightRight()
getDirectionalLightTarget()
setLightColor() / setLightIntensity()
setToneMapping()
useEnvMapForObj()

相机与交互

参考：Scene API / 相机与拍照

getDefaultCamera()
getCameraFov() / setCameraFov()
getCameraAspect() / setCameraAspect()
getCameraNear() / setCameraNear()
getCameraFar() / setCameraFar()
updateCameraProjectionMatrix()
getCameraWorldDirection()
dispatchTouchEvent(x, y)
switchCamera(position)
takePhoto()
skipCloudar()

事件

参考：Scene API / 事件监听

on(eventName, callback, target?)
off(eventName, callback, target?)

Collection API能力总览

立即体验按钮

参考：Collection API / 立即体验按钮

getStartButtonRect()
setStartButtonRect(rect)

场景管理

参考：Collection API / 场景管理

backToScan()
openScene(sceneId)
closeCurrentScene()

云识别

参考：Collection API / 云识别

startCloudar(collectionId, sceneIdList)
stopCloudar()

相机相关

参考：Collection API / 相机

takePhoto()

运行时事件

注意：仅场景高级API支持

api.on() 与 api.off() 当前可用的是：

无 target 时：暂仅支持objectClick - 一次性监听所有的对象被点击
指定 target 时：
- click - 被点击
- play - 音频/视频/动画/动图等播放
- pause - 音频/视频/动画/动图等暂停
- ended - 音频/视频/动画/动图等自然播放完毕
- replay - 视频/动画/动图等重新播放
- 对象的其他特殊事件，详见「内容和素材」中说明。

示例：

const model = await api.getObject('rabbit');

function handleClick(payload) {
  console.log('对象被点击', payload);
}

await api.on('click', handleClick, model);

高级API ​

获取高级API对象 ​

高级API的通用特性 ​

所有API都是async函数 ​

获取到的对象都只是句柄(Handle) ​

使用URL新增内容时，需要跨域支持 ​

Scene API能力总览 ​

立即体验按钮 ​

对象查询与基础属性 ​

层级和生命周期 ​

动态创建内容 ​

媒体与动画控制 ​

渲染与光照 ​

相机与交互 ​

事件 ​

Collection API能力总览 ​

立即体验按钮 ​

场景管理 ​

云识别 ​

相机相关 ​

运行时事件 ​

推荐阅读路径 ​

高级API

获取高级API对象

高级API的通用特性

所有API都是async函数

获取到的对象都只是句柄(Handle)

使用URL新增内容时，需要跨域支持

Scene API能力总览

立即体验按钮

对象查询与基础属性

层级和生命周期

动态创建内容

媒体与动画控制

渲染与光照

相机与交互

事件

Collection API能力总览

立即体验按钮

场景管理

云识别

相机相关

运行时事件

推荐阅读路径