常用 API 说明

播放器

player.destroyCurrentCompositions

销毁当前播放的所有 Composition，此时画面上的现有合成都会被清除。需要再次播放已销毁的合成时请重新使用player.loadScene。

合成

播放控制

在 player 上播放多个合成时，可以通过合成上的下列接口控制每个合成的播放状态。

composition.play()

可以用于以下情况：

1. loadScene时配置了autoplay: false的合成调用后播放
2. 合成暂停后继续播放
3. 结束行为设置「销毁」且在loadScene时设置了reusable的合成，播放结束后调用可以重新播放

composition.gotoAndPlay() / composition.gotoAndStop()

播放多个合成时可以使用此API控制合成单独跳转播放

composition.setSpeed()

用于设置合成的播放速度，默认播放速度是 1

composition.setIndex

设置合成的绘制等级，Index 高的合成会绘制在 Index 低的合成上；默认为 loadScene 时的顺序。

composition.dispose()

销毁指定合成。

一般情况下，设置了结束行为销毁的合成在播放结束后会自动销毁以释放内存，但如果设置了reusable参数，合成在播放结束后不会自动销毁，在不希望销毁 player 的情况下，可以使用该方法销毁指定的合成。合成销毁后不允许再播放，需要播放请重新通过 player.loadScene。

元素/预合成

属性继承说明

1. 对一般元素，父级会对子级的【路径 / 位置、缩放、旋转 以及这些属性对应的 k 帧变化 】生效，父节点的【元素时长、可见性、颜色（包含透明度）】不会被子级基础。
2. 对预合成元素，预合成元素会对内部元素的【路径 / 位置、缩放、旋转 以及这些属性对应的k帧变化、可见性 】生效，【元素时长、颜色（包含透明度）】不会被子级基础。

位置

设置

/**
 * 元素整体移动水平方向移动 x 像素，垂直方向移动 y 像素
 */
translateByPixel(x: number, y: number): void;
/**
 * 元素在 3D 坐标轴上相对移动
 */
translate(x: number, y: number, z: number): void;
/**
 * 元素在 3D 坐标轴上相对旋转（角度）
 */
rotate(x: number, y: number, z: number): void;
/**
 * 元素在 3D 坐标轴上相对缩放
 */
scale(x: number, y: number, z: number): void;

/**
 * 元素的在画布上的像素位置，坐标原点在 canvas 中心，x 正方向水平向右， y 正方向垂直向下
 */
setPositionByPixel(x: number, y: number): void;
/**
 * 设置元素在 3D 坐标轴的位置
 */
setPosition(x: number, y: number, z: number): void;
/**
 * 设置元素在 3D 坐标轴的角度
 */
setRotation(x: number, y: number, z: number): void;
/**
 * 设置元素在 3D 坐标轴的缩放
 */
setScale(x: number, y: number, z: number): void;

读取

item.getCurrentPosition

获取元素当前世界坐标

item.setVisible

设置元素的显示/隐藏：

1. 对一般元素，子级不会继承父级的隐藏属性。
2. 对预合成元素，设置后对预合成内的所有元素生效。

item.setColor

设置颜色，目前仅对图层元素生效

item.setOpacity

设置透明度，目前仅对图层和粒子元素生效

item.setSpeed

单独设置元素的播放速度

其他

拖拽系数

const scene = await player.loadScene('https://mdn.alipayobjects.com/mars/afts/file/A*ivbATIHzO1QAAAAAAAAAAAAADlB4AQ');
const dragItem = scene.getItemByName('滑动')?.getComponent(InteractComponent);

// 拖拽的距离映射系数，越大越容易拖动
if (dragItem) {
  dragItem.dragRatio = [2, 2];
}