怎么在 Matter.js 中实现物体拖拽与鼠标交互

在网页中运行 Matter.js 物理模拟时，默认情况下场景中的刚体只会受重力和碰撞影响自由下落。要在画面中用鼠标或触摸屏直接抓起一个方块、小球并自由抛掷，核心解法是利用官方提供的两个专用模块：Mouse（负责捕获画布输入并计算坐标）和 MouseConstraint（负责在光标与拾取的刚体之间建立弹性约束）。只需初始化这两个对象并加入物理世界，即可完成流畅自然的拖拽与投掷交互。

图 0：Matter.js 鼠标拖拽运行示意图：通过弹性约束在鼠标点与刚体之间建立牵引力

一、底层原理：Mouse 与 MouseConstraint 的分工

初学者在尝试给物理场景添加拖拽功能时，常常直觉地想监听 Canvas 的 mousemove 事件，并通过直接修改物体的 position.x 和 position.y 来实现位移。但在物理引擎中，暴力强行修改坐标会打破动量守恒，导致物体瞬间失去速度或直接穿墙损坏物理计算。

Matter.js 采用了一种符合真实物理规律的设计——约束驱动交互（Constraint-driven Interaction）。它把鼠标操作拆解为两个分工明确的独立模块：

• Matter.Mouse：负责监听指定 DOM 元素（通常是 <canvas>）的鼠标和触控原生事件（mousedown、mousemove、mouseup、touchstart、touchmove 等），并将屏幕坐标转化为当前物理世界的虚拟坐标。
• Matter.MouseConstraint：本质上是一个动态的弹簧约束器。当检测到鼠标按下并且光标落在某个非静态刚体上时，它会自动在光标位置与刚体的点击点之间建立一条弹性约束（Spring），通过施加真实的物理拉力拖动刚体；当鼠标移动过快时，物体会有自然的滞后感；当松开鼠标时，刚体会带着当前的初速度飞出，形成逼真的抛掷效果。

图 1：Matter.js 鼠标交互各核心组件的架构依赖与数据流闭环

二、标准实现步骤：从零实现鼠标拖拽

在 Matter.js 中实现鼠标拖拽有四个标准且固定的步骤。我们将从获取核心模块开始，一步步完成代码搭建。

图 2：在 Matter.js 中实现鼠标拖拽功能的四个标准实施阶段

步骤 1：准备基本物理环境

首先解构出常用模块，实例化 Engine（物理计算引擎）与 Render（画布渲染器），并向物理世界中添加几个可被拖拽的动态刚体以及起承托作用的静态刚体：

// 1. 解构 Matter.js 常用模块
const { Engine, Render, Runner, Bodies, Composite, Mouse, MouseConstraint } = Matter;

// 2. 创建引擎与渲染器
const engine = Engine.create();
const render = Render.create({
  element: document.body,
  engine: engine,
  options: {
    width: 800,
    height: 600,
    wireframes: false, // 设置为 false 以渲染实体颜色而非线框
    background: '#142537'
  }
});
Render.run(render);

// 3. 创建执行循环
const runner = Runner.create();
Runner.run(runner, engine);

// 4. 添加刚体到世界中（箱子、圆形小球、静态地板）
const boxA = Bodies.rectangle(400, 200, 80, 80, {
  render: { fillStyle: '#83ADD0' }
});
const ballB = Bodies.circle(460, 100, 40, {
  restitution: 0.8, // 弹性系数
  render: { fillStyle: '#77B9AE' }
});
const ground = Bodies.rectangle(400, 590, 810, 30, {
  isStatic: true, // 静态物体不受重力影响，不能被拖走
  render: { fillStyle: '#223E5E' }
});

Composite.add(engine.world, [boxA, ballB, ground]);

步骤 2：创建 Mouse 对象捕获输入

调用 Mouse.create(element)，传入渲染器绑定的 render.canvas 元素。这一步会把滚轮、鼠标移动、按压以及触控屏事件与该画布绑定：

// 创建与 canvas 绑定的鼠标控制对象
const mouse = Mouse.create(render.canvas);

步骤 3：创建 MouseConstraint 弹性约束

通过 MouseConstraint.create(engine, options) 将物理引擎与刚才的 mouse 关联。可以通过 constraint 配置项调节拖拽时的弹性刚度与阻尼：

// 创建鼠标约束
const mouseConstraint = MouseConstraint.create(engine, {
  mouse: mouse,
  constraint: {
    stiffness: 0.2, // 弹簧刚度：0.1~0.2 具有柔韧拖拽手感，1.0 为纯硬性瞬间跟随
    damping: 0.1,   // 阻尼系数：防止剧烈抖动
    render: {
      visible: true // 是否在画面中绘制牵引弹簧线（用于调试或视觉趣味）
    }
  }
});

步骤 4：将约束加入物理世界并同步渲染器

创建完 mouseConstraint 之后，必须做两件事，否则拖拽无法生效或在特殊情况下会发生坐标错位：

// 1. 将鼠标约束作为物理元素加入世界复合体
Composite.add(engine.world, mouseConstraint);

// 2. 极其重要：将 mouse 同步给 render 渲染器
render.mouse = mouse;

三、完整可运行代码示例

下面是一个完整的单文件 HTML 示例。你可以将其保存为 index.html 并直接在浏览器中打开，即可用鼠标自由拖拽、提拉和抛掷彩色几何刚体：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Matter.js 鼠标拖拽完整演示</title>
  <!-- 引入官方 Matter.js CDN -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/matter-js/0.19.0/matter.min.js"></script>
  <style>
    body {
      margin: 0;
      padding: 0;
      background: #0c1723;
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      overflow: hidden;
      font-family: sans-serif;
    }
    canvas {
      box-shadow: 0 8px 30px rgba(0,0,0,0.5);
      border-radius: 8px;
      touch-action: none; /* 移动端禁止浏览器默认滚动，保证触控顺畅 */
    }
  </style>
</head>
<body>

<script>
  // 1. 模块解构
  const { Engine, Render, Runner, Bodies, Composite, Mouse, MouseConstraint, Events } = Matter;

  // 2. 初始化引擎与渲染器
  const engine = Engine.create();
  const render = Render.create({
    element: document.body,
    engine: engine,
    options: {
      width: 800,
      height: 600,
      wireframes: false,
      background: '#142537'
    }
  });
  Render.run(render);

  const runner = Runner.create();
  Runner.run(runner, engine);

  // 3. 构建物理场景（生成可拖拽的物体与防跌落围栏）
  const box1 = Bodies.rectangle(350, 200, 70, 70, { render: { fillStyle: '#83ADD0' } });
  const box2 = Bodies.rectangle(450, 200, 70, 70, { render: { fillStyle: '#77B9AE' } });
  const circle = Bodies.circle(400, 100, 35, { 
    restitution: 0.9, 
    render: { fillStyle: '#e0c068' } 
  });

  // 边界墙壁（静态物体，不能被拖走）
  const ground = Bodies.rectangle(400, 590, 800, 20, { isStatic: true, render: { fillStyle: '#223E5E' } });
  const leftWall = Bodies.rectangle(10, 300, 20, 600, { isStatic: true, render: { fillStyle: '#223E5E' } });
  const rightWall = Bodies.rectangle(790, 300, 20, 600, { isStatic: true, render: { fillStyle: '#223E5E' } });

  Composite.add(engine.world, [box1, box2, circle, ground, leftWall, rightWall]);

  // 4. 关键：添加鼠标控制与拖拽约束
  const mouse = Mouse.create(render.canvas);
  const mouseConstraint = MouseConstraint.create(engine, {
    mouse: mouse,
    constraint: {
      stiffness: 0.2, // 刚度
      damping: 0.1,   // 阻尼
      render: {
        visible: true,
        lineWidth: 2,
        strokeStyle: '#77B9AE'
      }
    }
  });

  // 将约束添加进世界
  Composite.add(engine.world, mouseConstraint);

  // 将鼠标同步给渲染器，保持缩放/视口一致
  render.mouse = mouse;

  // 5. 监听拖拽事件
  Events.on(mouseConstraint, 'startdrag', function(event) {
    console.log('用户抓起了刚体:', event.body.id);
  });

  Events.on(mouseConstraint, 'enddrag', function(event) {
    console.log('用户松开了刚体:', event.body.id);
  });
</script>
</body>
</html>

四、进阶调优与交互事件

在掌握了基础实现后，实际业务往往需要对拖拽手感进行打磨，例如希望物体像挂在皮筋上那样有回弹，或者只允许拖拽特定的某些方块，又或者需要在拖拽开始和结束时播放音效、修改样式。

图 3：MouseConstraint 关键物理参数配置项及鼠标交互事件触发时序

1. 调节物理手感：刚度（stiffness）与阻尼（damping）

2. 精确过滤：指定哪些物体可以被拖动

默认情况下，场景中只要是 isStatic: false 的非静态刚体，都能被鼠标拖动。如果你希望某些特定的物体不能被用户乱动（例如悬挂的吊灯、某些障碍机关），可以通过 Matter.js 的 collisionFilter（碰撞掩码）进行分组隔离：

// 定义交互分类常量
const CATEGORY_DEFAULT = 0x0001;
const CATEGORY_DRAGGABLE = 0x0002;
const CATEGORY_LOCKED = 0x0004;

// 允许拖动的箱子
const movableBox = Bodies.rectangle(300, 200, 60, 60, {
  collisionFilter: {
    category: CATEGORY_DRAGGABLE
  }
});

// 不希望被鼠标拖动的物体（仍有物理重力和碰撞，但鼠标抓不到）
const lockedBox = Bodies.rectangle(500, 200, 60, 60, {
  collisionFilter: {
    category: CATEGORY_LOCKED
  }
});

// 让 MouseConstraint 的拾取检测只响应 CATEGORY_DRAGGABLE
mouseConstraint.collisionFilter.mask = CATEGORY_DRAGGABLE;

五、常见问题排查与避坑指南

在将 Matter.js 集成到实际前端项目（如 Vue、React 或自适应移动端页面）时，经常会遇到拖拽不准或手势冲突的情况。以下是四种最典型的问题及其对应解决方案。

图 4：Matter.js 拖拽交互中四大常见故障现象与标准排查路径

1. 坐标偏移：CSS 缩放与 Retina 屏适配

如果你在 CSS 中设置了 canvas { width: 100%; height: auto; }，会导致 Canvas 在屏幕上的 CSS 像素尺寸与其内部绘图缓冲区的逻辑分辨率不一致。此时必须告知 mouse 对象正确的缩放比例：

// 当窗口尺寸改变或 CSS 产生了缩放时校准
function handleResize() {
  const scaleX = render.canvas.clientWidth / render.options.width;
  const scaleY = render.canvas.clientHeight / render.options.height;
  
  // 设置鼠标坐标映射缩放比
  Mouse.setScale(mouse, { x: 1 / scaleX, y: 1 / scaleY });
}
window.addEventListener('resize', handleResize);

2. 移动端触摸手势与浏览器原生滚动冲突

在智能手机或平板设备上，手指触摸屏幕滑动默认会触发页面上下滚动或缩放，这会导致 touchmove 事件被浏览器中断，使拖拽刚体出现顿挫或卡死。

六、总结

在 Matter.js 中实现自然、平滑的物体拖拽与鼠标交互，核心在于理解“输入监听”与“物理约束”的分离设计：

• 通过 Mouse.create(render.canvas) 捕获输入事件并处理坐标转换；
• 通过 MouseConstraint.create(engine, options) 将鼠标位置转化为拉动刚体的物理弹簧，并通过 stiffness 与 damping 控制拖拽刚度与手感；
• 将 mouseConstraint 加入 Composite 物理世界并设置 render.mouse = mouse 保持视口坐标一致；
• 在自适应布局与移动端场景下，配合 Mouse.setScale 与 touch-action: none 避免坐标偏移与手势拦截。