PixiJS 交互事件处理：怎么响应鼠标点击与触摸操作

一、基础实现：四步让显示对象响应点击与触摸

在 HTML5 Canvas 中，由于整张画布是一个单一渲染上下文，Canvas 内部绘制的各种矩形或精灵并不像 DOM 元素那样天然拥有独立的点击事件。PixiJS 内置了完善的拾取检测（Hit-Testing）与事件分发树。只要按照规范完成四个步骤，任何显示节点都可以像普通按钮一样被用户点击。

下面是一个可以在现代浏览器直接执行的完整代码示例。示例通过 Graphics 绘制一个交互按钮，演示如何在单个对象上捕获点击与轻触：

import { Application, Graphics } from 'pixi.js';

// 1. 初始化 PixiJS 舞台
const app = new Application();
await app.init({
  width: 600,
  height: 300,
  backgroundColor: 0xFAF7F1,
  antialias: true
});
document.body.appendChild(app.canvas);

// 2. 创建并绘制一个交互按钮矩形
const button = new Graphics();
button.roundRect(0, 0, 180, 60, 10);
button.fill({ color: 0x394957 });
button.position.set(210, 120);

// 3. 核心设置：开启事件模式，指定光标样式
button.eventMode = 'static';
button.cursor = 'pointer';

// 4. 监听统一指针点击事件 pointertap
button.on('pointertap', (event) => {
  console.log('按钮被点击或触控！触发设备类型:', event.pointerType);
  // 点击后短暂改变背景颜色给出反馈
  button.clear();
  button.roundRect(0, 0, 180, 60, 10);
  button.fill({ color: 0xAD8B58 });
});

app.stage.addChild(button);

二、核心机制：Federated Events 与事件类型选择

很多初学者会疑惑：为什么不直接监听 click 或者 touchstart？为了理解两者的区别，需要看 PixiJS 的底层事件传递模型。

PixiJS 内部维护了 EventBoundary 对象，负责将浏览器发出的原生事件与舞台内的节点树进行空间对齐。开发中常用的指针事件与传统事件对比逻辑如下：

pointertap 为何优于传统 click

在移动浏览器端，如果直接依赖传统的 click 事件，会产生两个显著问题：一是浏览器为了判定用户是否是“双击放大屏幕”，默认存在约 300 毫秒的等待延迟；二是移动端触控往往伴随着手指的微小抖动，容易被误判。PixiJS 的 pointertap 会检测手指按下（pointerdown）与抬起（pointerup）期间的屏幕移动距离，只有位移在极小容差内才触发，既规避了延迟，又过滤掉了滑动列表时的误碰。

三、进阶控制：精确点击区域与 eventMode 选型

在实际游戏或可视化应用中，经常会遇到透明 PNG 图标、不规则多边形或是拥有大量子元素的复合容器。如果不加约束，可能会发生“点中透明空白也触发”或“节点过多引发性能下降”的问题。

1. 使用 hitArea 设定精确受击形变

PixiJS 允许直接赋予任何节点一个几何形状（支持 Rectangle、Circle、Polygon 或 Ellipse），作为其受击范围。这在两类场景中非常有用：扩大过小按钮的热区以便手指按压，或者收缩透明大图以避免遮挡下层内容：

import { Sprite, Circle, Rectangle } from 'pixi.js';

const icon = Sprite.from('target.png');
icon.eventMode = 'static';

// 场景 A：设置圆形命中区（中心为 0,0，半径 50）
icon.hitArea = new Circle(0, 0, 50);

// 场景 B：将 20x20 的小图标扩大为 48x48 的容易点击区域
// icon.hitArea = new Rectangle(-14, -14, 48, 48);

2. eventMode 的五个工作档位

为了保障复杂场景下的帧率，不要把所有对象无脑设置成交互。eventMode 提供了五种不同开销的模式：

• 'none'：完全关闭事件。自身不响应，也不向子级分发。适合纯装饰背景。
• 'passive'：默认值。自身不参与事件判定，但如果它的子节点开启了交互，依然会向下遍历检测。
• 'auto'：保留兼容模式，由子节点状态动态决定。
• 'static'：标准交互模式。支持点击、触摸及光标悬停，在大多数交互按钮上使用。
• 'dynamic'：高频动态模式。当显示对象处于高帧率复杂运动，或者需要持续捕获平滑轨迹时使用，计算开销高于 'static'。

四、实战演练：编写跨平台通用交互按钮组件

在商业项目中，一个合格的按钮需要同时兼顾：悬停反馈（鼠标进入变亮、离开还原）、按下反馈（缩小或变暗）、滑动取消（按下后手指滑出按钮再抬起不应触发点击回调）。

下面的封装示例展示了如何同时挂载鼠标和触摸通用的状态机：

import { Container, Graphics, Text } from 'pixi.js';

export class GameButton extends Container {
  constructor(label, onClick) {
    super();

    // 绘制按钮背景底板
    this.bg = new Graphics();
    this.drawBackground(0x394957);
    this.addChild(this.bg);

    // 按钮文案
    this.txt = new Text({
      text: label,
      style: { fill: '#FAF7F1', fontSize: 15, fontWeight: 'bold' }
    });
    this.txt.anchor.set(0.5);
    this.txt.position.set(80, 24);
    this.addChild(this.txt);

    // 开启容器交互与手型
    this.eventMode = 'static';
    this.cursor = 'pointer';
    
    // 避免内部 Text 干扰命中测试，直接统一由容器代理
    this.interactiveChildren = false;

    this.isPressed = false;
    this.bindEvents(onClick);
  }

  drawBackground(color) {
    this.bg.clear();
    this.bg.roundRect(0, 0, 160, 48, 8);
    this.bg.fill({ color });
  }

  bindEvents(onClick) {
    // 1. 指针按下：变暗或轻微缩放
    this.on('pointerdown', () => {
      this.isPressed = true;
      this.scale.set(0.96);
      this.drawBackground(0x26333D);
    });

    // 2. 指针悬停（桌面鼠标特有）
    this.on('pointerover', () => {
      if (!this.isPressed) this.drawBackground(0x4E6172);
    });

    // 3. 指针移出（桌面移出，或触屏滑出）
    this.on('pointerout', () => {
      if (!this.isPressed) this.drawBackground(0x394957);
    });

    // 4. 正常释放点击
    this.on('pointerup', () => {
      if (this.isPressed) {
        this.resetState();
        if (onClick) onClick();
      }
    });

    // 5. 滑出按钮范围后松开：取消点击
    this.on('pointerupoutside', () => {
      this.resetState();
    });
  }

  resetState() {
    this.isPressed = false;
    this.scale.set(1.0);
    this.drawBackground(0x394957);
  }
}

五、常见问题排查与速查决策

当给对象绑定了事件却无法正常触发时，可以依据以下决策树进行由表及里的定位排查：

总结

在 PixiJS 中处理鼠标与触摸操作，最关键的原则是“拥抱指针事件，善用 eventMode”：

1. 始终优先监听 pointertap、pointerdown、pointerup，让 PixiJS 的 EventSystem 自动适配双端差异。
2. 根据组件特性设置 eventMode = 'static'，并主动将不需要交互的纯视觉背景置为 eventMode = 'none'。
3. 善用 hitArea 改善触控命中率，并结合 pointerupoutside 处理移动端滑动放弃逻辑，即可打造出丝滑、稳健的跨端交互体验。