Scene API

本页描述 ready 事件中 detail.api 对应的场景运行时 API。

获取方式

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

适用范围

当前这套 API 主要适用于场景页面。

对于合辑页面，ready.detail.api 当前暂不支持。

通用约定

全部方法都应按异步方法处理

const obj = await api.getObject('rabbit');
await api.setPosition(obj, 1, 0, 0);

对象是句柄，不是原生 3D 对象

interface SceneObjectHandle {
  id: number;
}

你不能直接读取或修改其内部属性，只能继续传回 API。

立即体验按钮

getStartButtonRect(): Promise<DOMRect | undefined>
setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>

用于读取或调整场景首页“立即体验”按钮的样式和布局。

常量

api.constants = {
  no: 0,
  linear: 1,
  reinhard: 2,
  cineon: 4,
  aces_filmic: 5,
}

主要用于 setToneMapping()。

对象查询与基础属性

getObject(name: string): Promise<SceneObjectHandle | null>
getAllObject(): Promise<SceneObjectHandle[]>

getObjectName(target: SceneObjectHandle): Promise<string | null>
setObjectName(target: SceneObjectHandle, name: string): Promise<void>

getObjectVisible(target: SceneObjectHandle): Promise<boolean | null>
setObjectVisible(target: SceneObjectHandle, visible: boolean): Promise<void>

getRenderOrder(target: SceneObjectHandle): Promise<number | null>
setRenderOrder(target: SceneObjectHandle, renderOrder: number): Promise<void>

getDisableClick(target: SceneObjectHandle): Promise<boolean | null>
setDisableClick(target: SceneObjectHandle, disableClick: boolean): Promise<void>

getSize(target: SceneObjectHandle): Promise<[number, number, number]>
lookAt(target: SceneObjectHandle, x: number, y: number, z: number): Promise<void>

对象层级与生命周期

addChild(target: SceneObjectHandle, child: SceneObjectHandle): Promise<void>
removeChild(target: SceneObjectHandle, child: SceneObjectHandle): Promise<void>

getChildren(target: SceneObjectHandle): Promise<SceneObjectHandle[]>
getChildByProperty(
  target: SceneObjectHandle,
  property: string,
  value: any,
): Promise<SceneObjectHandle | null>

add(target: SceneObjectHandle): Promise<void>
remove(target: SceneObjectHandle): Promise<void>
destroyObject(target: SceneObjectHandle): Promise<void>
clear(): Promise<void>

变换属性

getPosition(target: SceneObjectHandle): Promise<[number, number, number]>
setPosition(target: SceneObjectHandle, x?: number, y?: number, z?: number): Promise<void>

getRotation(target: SceneObjectHandle): Promise<[number, number, number, string]>
setRotation(
  target: SceneObjectHandle,
  x?: number,
  y?: number,
  z?: number,
  order?: string,
): Promise<void>

getQuaternion(target: SceneObjectHandle): Promise<[number, number, number, number]>
setQuaternion(
  target: SceneObjectHandle,
  x?: number,
  y?: number,
  z?: number,
  w?: number,
): Promise<void>

getScale(target: SceneObjectHandle): Promise<[number, number, number]>
setScale(target: SceneObjectHandle, x?: number, y?: number, z?: number): Promise<void>

动态创建内容

createImage(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
createAnimatedImage(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
createGltfModel(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>

createVideo(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
createAlphaVideo(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>
interface KeyingVideoConfig {
  color?: string | number;
  similarity?: number;
  smoothness?: number;
  spill?: number;
}
createKeyingVideo(input: string | ArrayBuffer | Blob | File, config?: KeyingVideoConfig): Promise<SceneObjectHandle>

createPanorama(input: string | ArrayBuffer | Blob | File, segments?: number): Promise<SceneObjectHandle>
createEnvMapByHDR(input: string | ArrayBuffer | Blob | File): Promise<SceneObjectHandle>

createGroup(): Promise<SceneObjectHandle>
createAmbientLight(color?: string | number, intensity?: number): Promise<SceneObjectHandle>
createDirectionalLight(color?: string | number, intensity?: number): Promise<SceneObjectHandle>

渲染与材质

setEnableMask(target: SceneObjectHandle): Promise<void>
setDisableMask(target: SceneObjectHandle): Promise<void>

setGLState(
  target: SceneObjectHandle,
  prop:
    | 'side'
    | 'shadowSide'
    | 'blending'
    | 'transparent'
    | 'opacity'
    | 'alphaTest'
    | 'depthTest'
    | 'depthWrite'
    | 'colorWrite',
  value: any,
  recursive?: boolean,
): Promise<void>

setAnisotropy(
  target: SceneObjectHandle,
  num: number,
  mapType?: string,
  recursive?: boolean,
): Promise<void>

setObjectAlpha(target: SceneObjectHandle, type: string, cutOff: number): Promise<void>
useEnvMapForObj(
  target: SceneObjectHandle,
  envMap: SceneObjectHandle,
  intensity?: number,
): Promise<void>

setToneMapping(toneMapping: number, toneMappingExposure?: number): Promise<void>

光照

getDefaultAmbientLight(): Promise<SceneObjectHandle | null>
getDefaultDirectionalLightLeft(): Promise<SceneObjectHandle | null>
getDefaultDirectionalLightRight(): Promise<SceneObjectHandle | null>
getDirectionalLightTarget(light: SceneObjectHandle): Promise<SceneObjectHandle | null>

getLightColor(light: SceneObjectHandle): Promise<[number, number, number]>
setLightColor(light: SceneObjectHandle, color: string | number): Promise<void>
getLightIntensity(light: SceneObjectHandle): Promise<number>
setLightIntensity(light: SceneObjectHandle, intensity: number): Promise<void>

相机与拍照

getDefaultCamera(): Promise<SceneObjectHandle>

getCameraFov(camera: SceneObjectHandle): Promise<number | null>
setCameraFov(camera: SceneObjectHandle, fov: number): Promise<void>

getCameraAspect(camera: SceneObjectHandle): Promise<number | null>
setCameraAspect(camera: SceneObjectHandle, aspect: number): Promise<void>

getCameraNear(camera: SceneObjectHandle): Promise<number | null>
setCameraNear(camera: SceneObjectHandle, near: number): Promise<void>

getCameraFar(camera: SceneObjectHandle): Promise<number | null>
setCameraFar(camera: SceneObjectHandle, far: number): Promise<void>

updateCameraProjectionMatrix(): Promise<void>
getCameraWorldDirection(): Promise<[number, number, number]>

switchCamera(position?: 'front' | 'back'): Promise<'front' | 'back'>
takePhoto(): Promise<string>
dispatchTouchEvent(x: number, y: number): Promise<void>
skipCloudar(): Promise<void>

说明

switchCamera() 在 web3d 模式下不可用
takePhoto() 返回 data:image/png;base64,... 字符串
skipCloudar() 仅对云识别场景有意义

动图

getAnimatedImagePaused(target: SceneObjectHandle): Promise<boolean | null>
playAnimatedImage(target: SceneObjectHandle, loopCount?: number): Promise<void>
pauseAnimatedImage(target: SceneObjectHandle): Promise<void>
stopAnimatedImage(target: SceneObjectHandle): Promise<void>

视频

getVideoDuration(target: SceneObjectHandle): Promise<number | null>
getVideoPaused(target: SceneObjectHandle): Promise<boolean | null>
getVideoCurrentTime(target: SceneObjectHandle): Promise<number | null>
setVideoCurrentTime(target: SceneObjectHandle, currentTime: number): Promise<void>

getVideoLoop(target: SceneObjectHandle): Promise<boolean | null>
setVideoLoop(target: SceneObjectHandle, loop: boolean): Promise<void>

playVideo(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>
pauseVideo(target: SceneObjectHandle): Promise<void>
stopVideo(target: SceneObjectHandle): Promise<void>
playbackVideo(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>

音频

getAudioDuration(target: SceneObjectHandle): Promise<number | null>
getAudioPaused(target: SceneObjectHandle): Promise<boolean | null>
getAudioCurrentTime(target: SceneObjectHandle): Promise<number | null>
setAudioCurrentTime(target: SceneObjectHandle, currentTime: number): Promise<void>

getAudioLoop(target: SceneObjectHandle): Promise<boolean | null>
setAudioLoop(target: SceneObjectHandle, loop: boolean): Promise<void>

playAudio(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>
pauseAudio(target: SceneObjectHandle): Promise<void>
stopAudio(target: SceneObjectHandle): Promise<void>
playbackAudio(target: SceneObjectHandle, options?: Record<string, any>): Promise<void>

动画

getAnimationNames(target: SceneObjectHandle): Promise<string[] | null>
animationIsRunning(target: SceneObjectHandle, animationName?: string): Promise<boolean | null>
isAnimationLoop(target: SceneObjectHandle, animationName: string): Promise<boolean | null>
getAnimationIsRunningNames(target: SceneObjectHandle): Promise<string[] | null>

playAnimation(
  target: SceneObjectHandle,
  options?: {
    name?: string;
    loop?: boolean;
    repeat?: number;
    repeatMode?: number;
    timeScale?: number;
    weight?: number;
    clampWhenFinished?: boolean;
    resetLoopCount?: boolean;
  },
  triggerEvent?: boolean,
): Promise<void>

pauseAnimation(
  target: SceneObjectHandle,
  name?: string,
  triggerEvent?: boolean,
): Promise<void>

stopAnimation(
  target: SceneObjectHandle,
  name?: string,
  triggerEvent?: boolean,
): Promise<void>

playbackAnimation(
  target: SceneObjectHandle,
  options?: {
    name?: string;
    loop?: boolean;
    repeat?: number;
    repeatMode?: number;
    timeScale?: number;
    weight?: number;
    clampWhenFinished?: boolean;
    resetLoopCount?: boolean;
  },
  triggerEvent?: boolean,
): Promise<void>

事件监听

on(
  eventName:
    | 'objectClick'
    | 'click'
    | 'loop'
    | 'play'
    | 'pause'
    | 'ended'
    | 'replay',
  callback: (...args: any[]) => any,
  target?: SceneObjectHandle,
): Promise<void>

off(
  eventName:
    | 'objectClick'
    | 'click'
    | 'loop'
    | 'play'
    | 'pause'
    | 'ended'
    | 'replay',
  callback: (...args: any[]) => any,
  target?: SceneObjectHandle,
): Promise<void>

事件名规则

不传 target 时，仅支持 objectClick
传 target 时，支持 click、play、pause、ended、replay等

回调参数

不同对象类型，不同事件类型，有不一样的参数支持。

Scene API ​

获取方式 ​

适用范围 ​

通用约定 ​

全部方法都应按异步方法处理 ​

对象是句柄，不是原生 3D 对象 ​

立即体验按钮 ​

常量 ​

对象查询与基础属性 ​

对象层级与生命周期 ​

变换属性 ​

动态创建内容 ​

渲染与材质 ​

光照 ​

相机与拍照 ​

说明 ​

动图 ​

视频 ​

音频 ​

动画 ​

事件监听 ​

事件名规则 ​

回调参数 ​

相关 Guide ​

Scene API

获取方式

适用范围

通用约定

全部方法都应按异步方法处理

对象是句柄，不是原生 3D 对象

立即体验按钮

常量

对象查询与基础属性

对象层级与生命周期

变换属性

动态创建内容

渲染与材质

光照

相机与拍照

说明

动图

视频

音频

动画

事件监听

事件名规则

回调参数

相关 Guide