Fabric.js 事件系统详解：自定义鼠标行为与对象选中逻辑

一、Fabric.js 事件系统的分层架构与分发机制

Fabric.js 的事件体系并非简单封装原生 DOM 监听，而是在其之上构建了双层分发总线：底层是承载用户交互的 upper-canvas 元素，上层则是维护着图元对象树与视口变换矩阵（viewportTransform）的 Canvas 实例。理解这一分层机制，是编写稳定交互逻辑的前提。

1. 画布级事件与对象级事件的双轨制

Fabric.js 中存在两个维度的事件侦听器：

• 画布级事件（Canvas Events）：绑定在 canvas.on(...) 上，监听整个视口范围内的交互，包括 mouse:down、mouse:move、mouse:up、mouse:wheel 以及选区生命周期事件如 selection:created、selection:updated。无论鼠标击中空白区域还是具体图元，这些事件均会照常触发。
• 对象级事件（Object Events）：绑定在具体图元实例（如 rect.on(...)）上，例如 mousedown、mouseup、moving、scaling、rotating。只有当拾取引擎判定当前鼠标坐标落在该对象范围内，且对象的 evented 属性为 true 时，对象级回调才会被执行。

2. 事件参数对象 opt 的核心字段与坐标系转换

在所有事件回调中，Fabric.js 都会注入一个上下文参数 opt。其中 opt.e 为原生的浏览器 DOM 鼠标/触控事件（MouseEvent/TouchEvent），而 opt.target 则指向被命中的图形实例。若点击在空白区域，opt.target 为 undefined。

在涉及图形几何运算时，初学者最常犯的错误是直接使用 opt.e.clientX 或 opt.e.offsetX。一旦画布进行了缩放或平移，屏幕像素坐标与图元在画布坐标系中的绝对坐标（Scene Coordinates）将产生严重偏移。必须统一使用 canvas.getPointer(opt.e) 获取转换后的真实坐标点：

// 正确获取画布绝对世界坐标的方式
canvas.on('mouse:down', function (opt) {
  const pointer = canvas.getPointer(opt.e);
  console.log('画布内部真实 X 坐标:', pointer.x);
  console.log('画布内部真实 Y 坐标:', pointer.y);
  
  if (opt.target) {
    console.log('命中了具体图元:', opt.target.type);
  } else {
    console.log('点击在画布空白背景');
  }
});

二、自定义鼠标行为：平移拖动画布与滚轮缩放

在 CAD、流程图或海报编辑器中，常见交互是按住空格键或 Alt 键拖动画布（Pan），以及滚动鼠标滚轮以鼠标指针为中心缩放视口（Zoom）。Fabric.js 默认的鼠标拖动行为是拉取多选框（Selection Rectangle），两者存在天然的操作冲突。解决该冲突的关键是在按键触发或模式切换时，动态关闭 canvas.selection 并更新 viewportTransform。

1. 画布平移模式的状态机设计与实现

实现平移拖拽需要维护一个明确的状态机：在 mouse:down 阶段识别修饰键（如 Alt 键或中键），开启拖拽标志 isDragging，并记录起始屏幕坐标；在 mouse:move 阶段计算像素位移差值，调用 canvas.relativePan() 进行相对平移；在 mouse:up 阶段复原状态并重新允许框选。

let isDragging = false;
let lastPosX = 0;
let lastPosY = 0;

// 1. 按下鼠标：判定修饰键并锁定拖拽
canvas.on('mouse:down', function (opt) {
  const evt = opt.e;
  // 约定：按住 Alt 键或按下鼠标中键（button === 1）启动平移
  if (evt.altKey || evt.button === 1) {
    isDragging = true;
    canvas.selection = false; // 彻底关闭默认框选，防止出现选框虚影
    lastPosX = evt.clientX;
    lastPosY = evt.clientY;
    canvas.defaultCursor = 'grab';
  }
});

// 2. 移动鼠标：计算位移并增量平移
canvas.on('mouse:move', function (opt) {
  if (isDragging) {
    const evt = opt.e;
    const deltaX = evt.clientX - lastPosX;
    const deltaY = evt.clientY - lastPosY;

    // 核心函数：以当前视口为基准进行相对位移
    canvas.relativePan(new fabric.Point(deltaX, deltaY));

    // 更新上一帧记录点
    lastPosX = evt.clientX;
    lastPosY = evt.clientY;
    canvas.defaultCursor = 'grabbing';
  }
});

// 3. 松开鼠标：重置状态并恢复框选功能
canvas.on('mouse:up', function () {
  if (isDragging) {
    canvas.setViewportTransform(canvas.viewportTransform);
    isDragging = false;
    canvas.selection = true; // 重新启用默认框选
    canvas.defaultCursor = 'default';
  }
});

2. 滚轮以指针为中心的阻尼缩放

单纯调用 canvas.setZoom() 会固定以画布左上角 (0, 0) 为原点缩放，导致视觉体验突兀。Fabric.js 提供了 canvas.zoomToPoint(point, zoomLevel) 方法，能够以鼠标当前的瞬时像素位置为几何不动点进行等比缩放。在实现时需加入缩放上下限与阻尼系数，防止视口无限放大或翻转。

canvas.on('mouse:wheel', function (opt) {
  const evt = opt.e;
  evt.preventDefault();
  evt.stopPropagation();

  // 获取当前缩放级别
  let zoom = canvas.getZoom();
  
  // 根据滚轮 deltaY 计算阻尼比例（每次滚轮微调约 2% - 5%）
  const zoomFactor = 0.999 ** evt.deltaY;
  zoom = zoom * zoomFactor;

  // 限制缩放极值：最小 0.1 倍，最大 10 倍
  if (zoom > 10) zoom = 10;
  if (zoom < 0.1) zoom = 0.1;

  // 以鼠标指针当前视口点为中心执行缩放
  canvas.zoomToPoint(
    new fabric.Point(evt.offsetX, evt.offsetY),
    zoom
  );
});

三、精细化对象选中逻辑：属性配置与决策判定

在复杂业务场景中，并非画布上的所有元素都应具备相同的交互能力。例如：底层设计参考图只作为背景不可被选中；特定水印图层必须完全穿透；而某些标注点只响应鼠标悬浮展示 tooltip，绝不能进入被选中的外包围框。Fabric.js 提供了多个核心属性来精准调控选中逻辑。

1. 核心属性辨析：selectable 与 evented 的解耦

许多开发者容易混淆 selectable 与 evented。这两个属性在 Fabric.js 中承担完全独立的职责：

• evented: false：对象彻底退出碰撞拾取树（Hit-test）。鼠标在对象上方点击或滑动时，事件直接穿透该对象到达下层元素或背景。对象自身不会触发任何 mousedown、mouseover，canvas.findTarget() 会直接忽略它。
• selectable: false：对象依然参与碰撞拾取，但禁止成为活跃选中对象（ActiveObject）。这意味着对象依然能监听到 mousedown 与 hover 事件，也可以自定义光标手势，但用户无论单击还是框选，都无法调出旋转缩放控制柄，也不会将其纳入多选集合中。

2. 防止选中元素自动浮顶：preserveObjectStacking

默认情况下，当用户点击选中一个对象时，Fabric.js 会将该对象自动移动到当前渲染层级的最顶层，以便控制手柄完全可见。但这在多图层排版应用中往往会破坏图层的既定层叠顺序（Z-Index）。

// 画布初始化时的防跳层配置
const canvas = new fabric.Canvas('main-canvas', {
  preserveObjectStacking: true, // 保持原有图层堆叠顺序
  selectionBorderColor: '#6B88A6', // 统一定制框选边框颜色
  selectionColor: 'rgba(107, 136, 166, 0.15)', // 框选填充色
  selectionLineWidth: 1
});

3. 像素级精准拾取与组合穿透：perPixelTargetFind 与 subTargetCheck

默认情况下，Fabric.js 采用对象的轴对齐包围盒（AABB / OBB）进行点击检测。对于带有大面积透明区域的 PNG 图片或中空多边形，点击透明缝隙也会意外选中该对象。

• perPixelTargetFind: true：启用像素级命中测试。Fabric.js 会读取点击处像素的 Alpha 透明度值，只有非透明像素才算命中。可在画布全局或单个对象上开启。
• targetFindTolerance: 4：针对细线条（如 1px 描边），提高鼠标点击的容差容错范围，改善触控与点击体验。
• subTargetCheck: true：对于 fabric.Group 复合对象，默认点击只会选中整个组。若在 Group 上开启 subTargetCheck: true，拾取引擎会深入遍历组内子元素，并在 opt.subTargets 中返回命中的具体子图元。

四、进阶拦截：基于选区生命周期的业务互斥逻辑

除了静态配置属性外，复杂业务往往要求动态干预选中行为。例如：“锁定状态的图元不能与其他图元一同被批量多选”、“同一时间只允许选中文本图元或图片图元，禁止混合选中”。这需要介入选区的生命周期事件序列。

1. 选区生命周期事件序列

当用户在画布上点击或切换选中项时，Fabric.js 会严格按照以下顺序广播事件：

1. before:selection:cleared：旧的选区即将被销毁前触发，适合在此处保存上一个对象的编辑草稿或做取消校验。
2. selection:cleared：旧选区正式销毁。
3. selection:created：从无选区到建立首个 ActiveObject 时触发。
4. selection:updated：在已有选中状态下，按住 Shift 追加选择或切换至其他对象时触发。

2. 案例：多选时的类型互斥过滤

以下代码演示了如何在 selection:created 与 selection:updated 中拦截不符合业务规则的多选行为。若用户框选的内容中包含了只读锁定的对象，代码会自动将其从激活组中剔除：

function sanitizeSelection(opt) {
  const activeObj = canvas.getActiveObject();
  if (!activeObj) return;

  // 判定是否为多选激活集合 (ActiveSelection)
  if (activeObj.type === 'activeSelection') {
    const rawObjects = activeObj.getObjects();
    // 业务规则：过滤掉携带 isLocked 自定义属性的图元
    const validObjects = rawObjects.filter(item => !item.isLocked);

    if (validObjects.length === 0) {
      // 没有可用对象，直接清空选区
      canvas.discardActiveObject();
      canvas.requestRenderAll();
    } else if (validObjects.length !== rawObjects.length) {
      // 存在被锁定的对象，重新构建纯净的激活选区
      canvas.discardActiveObject();
      const newSelection = new fabric.ActiveSelection(validObjects, {
        canvas: canvas
      });
      canvas.setActiveObject(newSelection);
      canvas.requestRenderAll();
    }
  }
}

canvas.on('selection:created', sanitizeSelection);
canvas.on('selection:updated', sanitizeSelection);

五、高频性能优化与避坑实践

在处理包含数百甚至上千个图元的大型画布时，不当的事件监听往往是导致鼠标卡顿、操作掉帧的根源。牢记以下关键原则能够有效保证 60 FPS 的流畅度。

1. 渲染性能铁律：使用 requestRenderAll 替代 renderAll

canvas.renderAll() 是同步执行的全量重绘操作。如果在 mouse:move 这种每秒触发 60 至 120 次的高频事件中连续调用 renderAll()，主线程将毫无缓冲地反复计算包围盒与像素位图，造成严重卡顿。

正确做法：在所有事件处理回调中，统一调用 canvas.requestRenderAll()。该方法内部基于 window.requestAnimationFrame 进行调度，会将同一个事件循环周期内的多次渲染请求合并为单次屏幕刷新，从根本上杜绝冗余重绘。

2. 单页应用（SPA）中的事件解绑与内存管理

在 React、Vue 等前端框架中，组件卸载时若未销毁 Canvas 实例并解绑 DOM 事件，挂载在 window 或画布宿主上的事件闭包将导致严重的内存泄漏。在组件销毁钩子（如 useEffect cleanup 或 beforeUnmount）中，应依序执行事件解绑与画布清理：

// 组件销毁阶段标准清理范式
function destroyCanvas(canvas) {
  if (!canvas) return;
  // 1. 解绑所有自定义与画布事件监听器
  canvas.off();
  // 2. 清理 DOM 节点与上下文引用
  canvas.dispose();
}