# node-dommatrix

**Repository Path**: nodets/node-dommatrix

## Basic Information

- **Project Name**: node-dommatrix
- **Description**: 一个符合规范的W3C DOMMatrix实现，用于2D/3D矩阵变换。适用于图形库、动画系统以及任何需要精确几何变换的应用场景。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-05
- **Last Updated**: 2025-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# node-dommatrix

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

---

## ✨ 核心特性

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

---

## 🚀 安装

```bash
# 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实例                                        |

**示例：**

```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方向平移）<br>`ty: number`（Y方向平移，默认：0）<br>`tz: number`（Z方向平移，默认：0） | `DOMMatrix`     | 带平移的新矩阵                       |
| `translateSelf(tx, ty?, tz?)` | 同上                                                                                         | `this`          | 平移当前矩阵                         |
| `rotate(angle, x?, y?, z?)`   | `angle: number`（角度）<br>`x,y,z`: 旋转轴（默认：`0,0,1` 用于2D）                            | `DOMMatrix`     | 带旋转的新矩阵                       |
| `rotateSelf(angle, x?, y?, z?)`  | 同上                                                                                         | `this`          | 旋转当前矩阵                         |
| `scale(sx, sy?, sz?)`      | `sx: number`（X方向缩放）<br>`sy: number`（Y方向缩放，默认：sx）<br>`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组件快捷方式：<br>`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)
```

---

### 🔹 DOMPoint 类

表示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 ©