node-dommatrix

一个符合规范的W3C DOMMatrix实现，用于2D/3D矩阵变换。适用于图形库、动画系统以及任何需要精确几何变换的应用场景。

✨ 核心特性

• 遵循W3C标准：严格按照几何接口规范实现
• 双模式支持：无缝处理2D（3×3）和3D（4×4）矩阵
• 类型安全：完整的TypeScript支持，带有严格的类型定义
• 轻量级：压缩后约4KB，无依赖
• CSS兼容：输出matrix()/matrix3d()字符串，可直接用于样式中

🚀 安装

# npm
npm install node-dommatrix

# yarn
yarn add node-dommatrix

📖 API 参考

🔹 DOMMatrix 类

构造函数

支持多种初始化方式创建新矩阵：

| 语法 | 描述 | |-----------------------------------|----------------------------------------------------------------| | new DOMMatrix() | 空的单位矩阵（默认2D模式） | | new DOMMatrix(transformString) | 从CSS变换字符串创建（例如："translate(10px) rotate(30deg)"） | | new DOMMatrix(matrixArray) | 从数组创建：2D矩阵需要6个元素[a,b,c,d,e,f]，3D矩阵需要16个元素 | | new DOMMatrix(otherMatrix) | 克隆另一个DOMMatrix实例 |

示例：

// 从CSS变换字符串创建
const mat = new DOMMatrix('translate(50px, 100px) scale(2) rotate(45deg)');

// 从2D数组创建
const identity2d = new DOMMatrix([1, 0, 0, 1, 0, 0]);

// 从3D数组创建
const identity3d = new DOMMatrix([
  1,0,0,0,
  0,1,0,0,
  0,0,1,0,
  0,0,0,1
]);

🔸 核心方法

| 方法 | 参数 | 返回值 | 描述 | |-------------------------|--------------------------|-----------------|----------------------------------------------| | clone() | - | DOMMatrix | 创建矩阵的深拷贝 | | identity() | - | void | 将矩阵重置为单位矩阵（无变换） | | multiply(other) | other: DOMMatrix | DOMMatrix | 返回新矩阵：this × other | | multiplySelf(other) | other: DOMMatrix | this | 修改当前矩阵：this = this × other | | inverse() | - | DOMMatrix \| null | 返回逆矩阵（如果是奇异矩阵则返回null） | | transformPoint(point) | point: DOMPointInit | DOMPoint | 将矩阵应用于点进行变换 | | toString() | - | string | 返回兼容CSS的变换字符串 |

示例：矩阵乘法

const translate = new DOMMatrix().translateSelf(10, 20);
const rotate = new DOMMatrix().rotateSelf(30);

// 创建新矩阵：translate × rotate
const combined = translate.multiply(rotate);

// 或者在当前矩阵上直接修改
translate.multiplySelf(rotate);

示例：逆变换

const matrix = new DOMMatrix().scaleSelf(2);
const inverse = matrix.inverse(); // 逆矩阵将缩放0.5倍

// 逆转变换
const point = new DOMPoint(4, 6);
const transformed = matrix.transformPoint(point); // {x:8, y:12}
const original = inverse!.transformPoint(transformed); // {x:4, y:6}

🔸 变换方法

所有变换方法都有两种变体：

• 非变异版本：method() 返回应用了变换的新矩阵
• 变异版本：methodSelf() 直接在当前矩阵上应用变换

| 方法 | 参数 | 返回值 | 描述 | |-------------------------|----------------------------------------------------------------------------------------------|-----------------|--------------------------------------| | translate(tx, ty?, tz?) | tx: number（X方向平移）ty: number（Y方向平移，默认：0）tz: number（Z方向平移，默认：0） | DOMMatrix | 带平移的新矩阵 | | translateSelf(tx, ty?, tz?) | 同上 | this | 平移当前矩阵 | | rotate(angle, x?, y?, z?) | angle: number（角度）x,y,z: 旋转轴（默认：0,0,1 用于2D） | DOMMatrix | 带旋转的新矩阵 | | rotateSelf(angle, x?, y?, z?) | 同上 | this | 旋转当前矩阵 | | scale(sx, sy?, sz?) | sx: number（X方向缩放）sy: number（Y方向缩放，默认：sx）sz: number（Z方向缩放，默认：1） | DOMMatrix | 带缩放的新矩阵 | | scaleSelf(sx, sy?, sz?) | 同上 | this | 缩放当前矩阵 | | skewX(angle) | angle: number（角度） | DOMMatrix | 带X方向倾斜的新矩阵 | | skewXSelf(angle) | 同上 | this | 对当前矩阵应用X方向倾斜 | | skewY(angle) | angle: number（角度） | DOMMatrix | 带Y方向倾斜的新矩阵 | | skewYSelf(angle) | 同上 | this | 对当前矩阵应用Y方向倾斜 | | to2D() | - | DOMMatrix | 转换为2D矩阵（丢弃3D数据） |

示例：链式变换

const matrix = new DOMMatrix()
  .translateSelf(100, 200)    // 移动原点
  .rotateSelf(45)             // 绕新原点旋转
  .scaleSelf(1.5);            // 缩放变换后的矩阵

console.log(matrix.toString()); 
// 输出: matrix(1.06..., 1.06..., -1.06..., 1.06..., 100, 200)

示例：3D变换

const matrix = new DOMMatrix()
  .rotateSelf(30, 1, 0, 0)    // 绕X轴旋转30°
  .translateSelf(0, 0, 50)    // 沿Z轴移动
  .scaleSelf(1, 1, 0.8);      // 缩放Z轴

const point = matrix.transformPoint(new DOMPoint(10, 20, 30));

🔸 属性

| 属性 | 类型 | 描述 | |-----------|---------------------|------------------------------------------------------------| | is2D | boolean | 若矩阵处于2D模式则为true | | elements | readonly number[] | 原始矩阵值（3D矩阵16个元素，2D矩阵6个有效元素） | | a-f | number | 2D组件快捷方式：a=m11, b=m12, c=m21, d=m22, e=m41, f=m42 | | m11-m44 | number | 3D组件访问器（4×4矩阵位置） |

示例：直接访问属性

const matrix = new DOMMatrix().scaleSelf(2, 3);
console.log(matrix.a);  // 2 (m11: X方向缩放)
console.log(matrix.d);  // 3 (m22: Y方向缩放)

matrix.e = 50;          // 设置X方向平移 (m41)
matrix.f = 100;         // 设置Y方向平移 (m42)

🔹 DOMPoint 类

表示3D空间中的点，带有齐次坐标：

构造函数

new DOMPoint(x?: number, y?: number, z?: number, w?: number);

属性

| 属性 | 类型 | 描述 | |------|----------|------------------------| | x | number | X坐标（默认：0） | | y | number | Y坐标（默认：0） | | z | number | Z坐标（默认：0） | | w | number | 齐次坐标（默认：1） |

示例：

const point = new DOMPoint(10, 20, 30);
console.log(point.x); // 10

// 用矩阵变换点
const transformed = matrix.transformPoint(point);

🧩 兼容性

• Node.js: ≥ 14.0.0
• 浏览器: Chrome 54+, Firefox 43+, Safari 10+, Edge 15+
• TypeScript: ≥ 4.0（用于类型定义）

📄 许可证

MIT ©