交互

阅读时间：2分钟更新于 2025-07-24 14:55

在 Galacean Effects 编辑器中设置交互后，Player 可以完成元素的点击事件、创建/销毁生命周期等响应。

设计使用参考：交互元素。

监听交互

Player 的实例化参数interactive用于开启运行时监听元素的交互，click和message用于执行点击/消息交互行为的事件监听。

import { spec , Player} from '@galacean/effects';

type MessageItem = {
  name: string; // 编辑器中设置的名字
  phrase: number; // 元素状态，开始: MESSAGE_ITEM_PHRASE_BEGIN ，结束: MESSAGE_ITEM_PHRASE_END
}

type ClickedItem = {
  clickInfo: Region, // 点击元素详情
  player: Player, // 播放器
  compositionId: string, // 合成ID
  compositionName: string, // 合成名称
};

const player = new Player({
  container,
  interactive: true, //！！！设置了此参数才响应交互
});

player.on('click', item => {
  // 设置多个元素的点击交互需要根据 name 判断是否指定元素
  console.log('trigger onItemClicked');
  console.log(item.name);
});

player.on('message', (item: MessageItem) => {
  console.log(item.name); // 设置多个交互元素需要根据 name 判断是否指定元素
  if (item.phrase === spec.MESSAGE_ITEM_PHRASE_BEGIN) {
    // 元素创建
  } else if (item.phrase === spec.MESSAGE_ITEM_PHRASE_END) {
    // 元素销毁
  }
});

// 也可以直接对元素进行监听
const composition = await player.loadScene(json);
const item = composition.getItemByName('lotteryBtn');

item?.on('click', e => {
  console.info(`[item click] - item [${e.name}] clicked.`);
});

注意：

降级后交互行为的监听都不会生效。
click事件是编辑器中设置元素的交互行为“消息通知”。
message事件仅在交互元素创建/销毁时触发。

设置交互

可以通过添加交互元素、给图层或粒子元素直接设置交互行为来设置交互，具体设置开发可以和设计同学协商。

交互元素

在编辑器中增加“交互元素”，允许将其类型设置为「点击」、「消息」、「拖拽」。

点击类型交互元素的交互行为可以设置为「消息通知」或「恢复播放」，元素点击后会触发click回调或合成暂停状态下恢复播放。点击交互元素最好放置在元素列表的最上层避免被其它元素遮挡。
消息类型交互元素会在元素创建/销毁时触发message回调；

拖拽类型交互元素拖拽目标为camera，开启后允许拖拽相机位置（可以参考灵感中心的天猫大街案例）。

拖拽

设置拖拽系数：

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];
}

拖拽的惯性衰减系数：

// 范围[0, 1], 越大惯性越强
dragItem.downgrade = 0.8;

设置是否可拖拽：

💡小知识

可以在任意情况设置拖拽停止（或失效），如下代码片段：

// disable interaction
dragItem.interactive = false;
// enable interaction
dragItem.interactive = true;

图层/文本/矢量元素

图层元素可以响应点击事件，可以直接在右侧面板开启并设置交互行为，可以选择「消息通知NOTIFY」或「恢复播放RESUME_PLAYER」，元素点击后会触发 click 回调或合成暂停状态下恢复播放。

如果动画太复杂，还是建议新创建一个交互元素。

注意：

如果设置【消息通知】，编码时通过 click 来监听回调。
如果设置【交互行为】为【恢复播放】，在 player 暂停（pause()）时，点击后会恢复播放（resume），无需做回调的编码。

粒子元素

粒子元素可以响应点击事件，可以直接在右侧面板开启并设置交互行为，可以选择「无响应none」或「移除粒子removeParticle」，后者会导致粒子被点击后消失。交互响应半径越大则越容易点中粒子，重叠元素响应关闭表示粒子重叠只有最上层粒子会触发交互行为，否则重叠粒子都触发指定的交互行为。

监听交互设置交互交互元素拖拽图层/文本/矢量元素粒子元素

Preview