常用 API 说明

播放器

player.destroyCurrentCompositions

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

player.loadScene

多合成加载可以通过下面几种形式，并允许合成使用相同 / 不同的加载 options:

// 1. 加载单个合成链接并设置可选参数
const composition = await player.loadScene('xxx.json', { ... });
const composition = await player.loadScene({ url: 'xxx.json' }, { ... });

// 2. 加载单个合成的 JSON 对象并设置可选参数
const composition = await player.loadScene(JSONValue, { ... });

// 3. 加载多个合成链接或 JSON 对象
const [_, _, _] = await player.loadScene(['x1.json', 'x2.json', JSONValue]);

// 4. 加载多个合成链接并各自设置可选参数
const [_, _] = await player.loadScene([{
  url: 'x1.json',
  options: { autoplay: false, ... },
}, {
  url: 'x2.json',
  options: { speed: 2, ... },
}, { ... }]);

// 5. 加载多个合成链接并统一设置可选参数（共用）
const [_, _, _] = await player.loadScene(['x1.json', 'x2.json', ...], { ... });
const [_, _] = await player.loadScene(
  [{ url: 'x1.json' }, { url: 'x2.json' }, { ... }],
  {
    variables: {
      'name': 'value',
    },
    speed: 2,
    ...
   },
);

// 6. 疯狂混合
await player.loadScene([
  {
    url: 'x1.json',
    options: {
      variables: {
        'name1': 'value1',
      },
      speed: 2,
    },
  },
  'x2.json',
  JSONValue,
], {
  variables: {
    'name2': 'value2',
  },
  speed: 0.1,
});

合成

播放控制

在 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.setSpeed

单独设置元素的播放速度

component.setColor

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

import { SpriteComponent } from '@galacean/effects';

const item = composition.getItemByName(`_${name}`);
const component = item?.getComponent(SpriteComponent);

// 设置成黄色
component?.setColor([255, 255, 0, 1]);

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

// 设置 color 的 alpha 通道为 0
component?.setColor([255, 255, 255, 0]);