Fabric.js 图层点击穿透实现方法 添加水印/背景

在前端开发中，使用 Fabric.js 进行画布开发时，经常会遇到图层遮挡导致下层对象无法响应鼠标事件的问题，也就是我们常说的 点击穿透 需求。无论是做背景层、水印层、遮罩层，还是需要实现像素级的精准交互，掌握 Fabric.js 的点击穿透技巧都能大幅提升开发效率。作为一名全栈开发，结合日常项目实战，整理了 Fabric.js 图层点击穿透的所有常用实现方法，覆盖基础场景到进阶需求，供各位开发者参考。

一、核心原理：Fabric.js 对象交互属性

Fabric.js 的画布对象（fabric.Object）有两个核心属性决定了其是否响应鼠标事件，也是实现点击穿透的关键：

• selectable：控制对象是否可被选中、拖动、编辑，默认值为 true；
• evented：控制对象是否响应任何鼠标事件（点击、 hover、拖拽等），默认值为 true。

点击穿透的本质，就是通过控制这两个属性，让上层对象 忽略 鼠标事件，从而让事件穿透到下层对象。除此之外，还有像素级穿透、全局画布穿透等场景，需结合具体需求选择对应方法。

二、标准实现：完全点击穿透（推荐场景）

最常用的场景是上层图层仅作为视觉展示（如背景、水印），不需要任何交互，此时需让其完全穿透，点击事件直接作用于下层可操作对象。核心配置是将 selectable 和 evented 同时设为 false，这也是最推荐的完全穿透方案。

代码示例（创建时直接配置）：

// 初始化 Fabric 画布
const canvas = new fabric.Canvas('canvas-container');

// 创建完全穿透的上层图层（半透明遮罩示例）
let overlay = new fabric.Rect({
  left: 0,
  top: 0,
  width: canvas.width,
  height: canvas.height,
  fill: 'rgba(0, 0, 0, 0.1)', // 半透明遮罩
  selectable: false,   // 禁止选中
  evented: false,      // 禁止响应所有鼠标事件（关键）
  hoverCursor: 'default' // 优化体验：鼠标悬停不显示操作光标
});

// 添加到画布
canvas.add(overlay);

// 下层可操作对象（示例：可点击、可拖动的矩形）
let operableRect = new fabric.Rect({
  left: 150,
  top: 150,
  width: 100,
  height: 100,
  fill: '#409eff',
  selectable: true,
  evented: true
});

canvas.add(operableRect);

也可在对象创建后动态修改穿透属性，满足动态交互需求：

// 动态设置穿透
overlay.set({ selectable: false, evented: false });
canvas.renderAll(); // 重新渲染画布生效

三、常用场景：视觉遮挡+事件穿透（背景/水印）

在项目中，我们经常需要给画布添加背景图、水印或固定遮罩，这些图层仅起视觉作用，不能拦截下层对象的交互。此时除了设置核心的穿透属性，还可以添加一些优化配置，提升开发体验和产品质感。

完整实战示例（水印层）：

// 假设已获取水印图片（本地图片或远程图片）
const watermarkImg = new Image();
watermarkImg.src = './watermark.png'; // 水印图片路径

watermarkImg.onload = () => {
  // 创建水印图层（完全穿透）
  let watermark = new fabric.Image(watermarkImg, {
    left: 50,
    top: 50,
    scaleX: 0.5,
    scaleY: 0.5,
    selectable: false,
    evented: false,
    hasBorders: false,    // 取消选中边框（即使 selectable 为 false，建议配置）
    hasControls: false,   // 取消操作控制点
    excludeFromExport: true, // 可选：导出画布时排除水印层
    hoverCursor: 'default'
  });

  canvas.add(watermark);
};

该配置适用于所有仅视觉展示、无需交互的上层图层，如背景图、固定遮罩、水印等，是全栈开发中最常用的穿透方案。

四、进阶实现：按像素透明穿透（精准交互）

有些场景下，上层对象并非完全透明，我们需要实现 透明区域可穿透，不透明区域可交互 的效果（如不规则图形、带透明通道的图片）。此时不能设置 evented: false，需通过开启画布的像素级检测来实现。

核心配置是在初始化画布时，设置 perPixelTargetFind 为 true，开启像素级目标检测，配合 targetFindTolerance（检测容差）优化交互体验。

代码示例：

// 初始化画布时开启像素级检测
const canvas = new fabric.Canvas('canvas-container', {
  perPixelTargetFind: true,  // 关键：开启像素级透明检测
  targetFindTolerance: 4      // 可选：检测容差（像素），值越大越容易选中
});

// 上层半透明对象（仅透明区域穿透）
let semiTransparentObj = new fabric.Rect({
  left: 100,
  top: 100,
  width: 200,
  height: 200,
  fill: 'rgba(255, 0, 0, 0.3)', // 半透明红色
  selectable: true, // 必须设为 true，否则无法响应非透明区域的点击
  evented: true     // 必须设为 true，保留交互能力
});

// 下层可操作对象
let bottomRect = new fabric.Rect({
  left: 150,
  top: 150,
  width: 100,
  height: 100,
  fill: '#67c23a'
});

canvas.add(bottomRect, semiTransparentObj);

说明：当点击 semiTransparentObj 的透明区域时，事件会穿透到下层的 bottomRect；点击不透明区域时，会选中 semiTransparentObj，实现精准的像素级交互。

五、特殊场景：全局画布点击穿透

如果需要让整个 Fabric 画布都被点击穿透（即鼠标事件完全跳过画布，作用于画布下方的 HTML 元素），仅通过 Fabric.js 的属性无法实现，需配合 CSS 的 pointer-events 属性。

CSS 配置：

/* 画布容器 ID，根据实际项目修改 */
#canvas-container {
  pointer-events: none; /* 禁止画布响应任何鼠标事件，完全穿透 */
}

/* 注意：如果画布内有部分元素需要保留交互，可单独设置 */
#canvas-container .need-interact {
  pointer-events: auto;
}

适用场景：画布仅作为视觉展示，无需任何交互，且需要点击画布下方的按钮、链接等 HTML 元素。

六、核心属性与场景对应表

为了方便大家快速查找对应方案，整理了核心属性与穿透效果、适用场景的对应关系，一目了然：

七、实战总结

在 Fabric.js 开发中，点击穿透的核心是 控制对象是否响应鼠标事件 ，不同场景对应不同的实现方案：

1. 日常开发中，背景、水印等纯视觉图层，优先使用 selectable: false + evented: false ，简单高效，兼容性好；
2. 需要精准交互的不规则图层，开启像素级检测（perPixelTargetFind: true），实现透明区域穿透；
3. 特殊场景下需要全局穿透，配合 CSS 的 pointer-events: none 即可实现。

以上所有方法均经过项目实战验证，覆盖了大部分 Fabric.js 画布开发中的点击穿透需求。掌握这些技巧，能有效解决图层遮挡导致的交互问题，提升画布开发的效率和用户体验。