JavaScript Path2D 的 addPath 怎样同时应用矩阵变换

如果一个 Canvas 图形由多个可复用部件组成，最稳妥的做法是把部件保留为独立的 Path2D，再用 addPath(path, transform) 把它合并到目标路径。第二个参数接收 DOMMatrix，因此平移、缩放、倾斜或旋转的线性部分可以在一次合并时一起表达；它只影响“被加入”的路径，不会改写原始路径，也不会替代 Canvas 上下文的当前变换。

本文用一个矩形部件说明这条边界：先建立源路径，再把矩阵应用到它，最后一次性绘制目标路径。这样迁移旧代码时，不容易把路径坐标、绘制状态和页面布局混在一起。

核心写法是 target.addPath(source, matrix)。矩阵中的 a、b、c、d 描述二维线性变换，e、f 描述平移；addPath 返回 undefined，所以要继续使用目标路径对象。

先分清 addPath 与上下文变换

addPath 的第一个参数是要加入的源路径，调用者提供的 DOMMatrix 只作用于这一次加入动作。目标路径接收变换后的几何数据，之后可以交给 fill 或 stroke。源路径仍然可以被再次加入到别的目标路径中。

下面的例子把一个尺寸为 80 × 50 的部件平移到右侧，同时把它缩小为原来的 0.8。这里的矩阵是一次性传入 addPath 的，示例只展示 API 关系，不把图片当作运行截图。

const canvas = document.querySelector('#canvas');
const ctx = canvas.getContext('2d');

// 目标路径保存最终要绘制的多个子路径。
const target = new Path2D();
target.rect(20, 25, 120, 70);

// 源路径是可复用的局部图形，坐标从自己的原点开始。
const source = new Path2D();
source.rect(0, 0, 80, 50);

// a、d 负责缩放，e、f 负责平移；一次矩阵同时表达两类变换。
const matrix = new DOMMatrix([0.8, 0, 0, 0.8, 190, 35]);

// addPath 会把变换后的 source 加入 target，本身没有返回值。
target.addPath(source, matrix);

// 继续使用目标路径进行绘制；source 仍可复用。
ctx.fillStyle = '#2f6fed';
ctx.fill(target);

注意：target.addPath(...) 不是链式 API，不能写成 const merged = target.addPath(...) 后再把 merged 传给 fill。正确的对象仍是 target。

把平移、缩放和旋转放进同一个矩阵

DOMMatrix 的二维别名可以直接按 [a, b, c, d, e, f] 传入。a、b、c、d 构成线性部分，能够表达缩放、旋转和倾斜；e、f 是平移量。对于需要重复摆放的同一部件，矩阵通常比修改源路径坐标更容易维护。

例如下面的矩阵把一个局部三角形做轻微旋转与缩放，再平移到画布中部。这里把矩阵分量写出来，便于迁移时逐项对照，而不是把变换散落在多个绘制状态调用中。

// 局部坐标中的三角形，保持为可复用的几何模板。
const marker = new Path2D('M 0 0 L 70 0 L 35 55 Z');
const composed = new Path2D();

// 线性部分近似表示缩放加旋转，e、f 把结果移到目标位置。
const transform = new DOMMatrix([
  0.75, 0.22,
  -0.22, 0.75,
  240, 80
]);

// 只把 marker 的变换副本并入 composed，不修改 marker 本身。
composed.addPath(marker, transform);

// 上下文变换属于绘制阶段；这里用 resetTransform 避免继承外部状态。
ctx.save();
ctx.resetTransform();
ctx.strokeStyle = '#d14b38';
ctx.stroke(composed);
ctx.restore();

如果矩阵来自 CSS 或 SVG 计算结果，也可以使用拥有相同矩阵属性的对象；但在跨模块传递时，建议明确转换为 DOMMatrix，让调用方知道这里接收的是几何变换而不是 CSS 字符串。

迁移旧写法时，先决定变换属于哪里

旧代码常见的形式是先调用 ctx.save()、translate() 或 rotate()，再绘制源路径。这种方式适合“同一份路径在不同绘制时刻采用不同姿态”；它修改的是上下文当前变换，不会把多个部件合并成一个新的 Path2D。

迁移到 addPath 时，可以按下面的规则做取舍：

还要留意两个边界：第一，addPath 的变换是路径级的，之后再调用 ctx.scale 仍会影响最终绘制；第二，矩阵不可逆时不要假设可以从屏幕坐标反推局部坐标，反向计算应先检查矩阵是否可逆。

封装时保留源路径与目标路径的职责

如果项目里会反复放置同一图形，可以把“创建矩阵并合并”封装成小函数。函数返回目标路径，源路径只读使用；这样既能批量合并，也不会让调用方误以为 addPath 会返回新对象。

function appendTransformed(target, source, values) {
  // 只接收二维矩阵分量，避免在函数内部偷偷修改调用方的矩阵。
  const matrix = new DOMMatrix(values);

  // 目标路径负责承载结果，源路径继续留作模板复用。
  target.addPath(source, matrix);
  return target;
}

// 通过不同矩阵把同一模板放到两个位置。
const reusable = new Path2D('M 0 0 L 40 0 L 20 30 Z');
const scene = new Path2D();
appendTransformed(scene, reusable, [1, 0, 0, 1, 40, 40]);
appendTransformed(scene, reusable, [0.6, 0, 0, 0.6, 160, 90]);

// 最后统一绘制，避免每个部件都切换一次上下文状态。
ctx.fill(scene);

回归检查可以只围绕三件事展开：目标路径是否仍然是传入的对象、每个矩阵是否明确写出局部坐标到画布坐标的意图、上下文的外部变换是否在绘制前后成对保存和恢复。

常见问题

addPath 会修改 source 吗？

不会。它把源路径按给定矩阵加入目标路径；同一个 source 可以使用不同矩阵重复加入。

为什么合并后位置又被整体移动了？

通常是因为 addPath 的矩阵和 Canvas 上下文当前变换都生效了。先检查 ctx.getTransform() 或在绘制前使用成对的 save、resetTransform、restore，再决定哪一层负责页面布局。

一句话收尾：把可复用图形留在源 Path2D，把一次摆放所需的几何关系放进 DOMMatrix，用 addPath 合并到目标路径，最后再让 Canvas 负责绘制状态。