node-dommatrix

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 ©