node-dommatrix

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

---

✨ 核心特性

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

---

🚀 安装

``bash


npm

npm install node-dommatrix

yarn

yarn add node-dommatrix
`

---

📖 API 参考

$3

#### 构造函数

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

| 语法 | 描述 |
|-----------------------------------|----------------------------------------------------------------|
| 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实例 |

示例：

`javascript
// 从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的变换字符串 |

示例：矩阵乘法

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

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

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

示例：逆变换

`javascript
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数据） |

示例：链式变换

`javascript
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变换

`javascript
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矩阵位置） |

示例：直接访问属性

`javascript
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)
`

---

$3

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

#### 构造函数

`javascript
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） |

示例：

`javascript
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 ©