PostCSS Transform to Matrix3D Plugin

一个 PostCSS 插件，将 CSS transform 属性自动转换为 matrix3d 格式。

功能特点

• ✅ 支持所有常见的 2D 和 3D transform 函数
• ✅ 支持 transform 函数组合
• ✅ 可选保留原始 transform 值
• ✅ 支持选择器过滤（only/exclude）
• ✅ 零依赖核心算法

支持的 Transform 函数

2D Transforms

• translate(x, y)
• translateX(x) / translateY(y)
• rotate(angle)
• scale(x, y)
• scaleX(x) / scaleY(y)
• skew(x, y)
• skewX(angle) / skewY(angle)
• matrix(a, b, c, d, e, f)

3D Transforms

• translate3d(x, y, z)
• translateZ(z)
• rotate3d(x, y, z, angle)
• rotateX(angle) / rotateY(angle) / rotateZ(angle)
• scale3d(x, y, z)
• scaleZ(z)
• perspective(distance)
• matrix3d(...)

安装

npm install postcss postcss-value-parser

使用方法

基础用法

const postcss = require('postcss');
const transformToMatrix = require('postcss-transform-to-matrix');

postcss([
  transformToMatrix()
])
  .process(css)
  .then(result => {
    console.log(result.css);
  });

在 Webpack 中使用

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('postcss-transform-to-matrix')()
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

在 Vite 中使用

// vite.config.js
import { defineConfig } from 'vite';
import transformToMatrix from 'postcss-transform-to-matrix';

export default defineConfig({
  css: {
    postcss: {
      plugins: [
        transformToMatrix()
      ]
    }
  }
});

PostCSS 配置文件

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-transform-to-matrix')()
  ]
};

配置选项

transformToMatrix({
  // 是否保留原始 transform 属性（默认: false）
  preserveOriginal: true,

  // 只转换匹配的选择器
  only: '.my-class',  // 字符串、正则或数组

  // 排除特定选择器
  exclude: /\.no-convert/
})

配置示例

保留原始值

transformToMatrix({ preserveOriginal: true })

输入:

.element {
  transform: translate(100px, 50px) rotate(45deg);
}

输出:

.element {
  transform: translate(100px, 50px) rotate(45deg);
  transform: matrix3d(0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 100, 50, 0, 1);
}

选择器过滤

transformToMatrix({ only: ['.convert-me', /\.transform-/] })

只会转换 .convert-me 和以 .transform- 开头的选择器。

转换示例

示例 1: 基础 translate + rotate

输入:

.box {
  transform: translate(100px, 50px) rotate(45deg);
}

输出:

.box {
  transform: matrix3d(0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 100, 50, 0, 1);
}

示例 2: 3D transforms

输入:

.card {
  transform: perspective(500px) rotateY(45deg) translateZ(100px);
}

输出:

.card {
  transform: matrix3d(0.707107, 0, -0.707107, -0.001414, 0, 1, 0, 0, 0.707107, 0, 0.707107, 0, 0, 0, 100, 1);
}

示例 3: 复杂组合

输入:

.complex {
  transform: translate3d(10px, 20px, 30px) rotateX(30deg) scale(1.5);
}

输出:

.complex {
  transform: matrix3d(1.5, 0, 0, 0, 0, 1.299038, 0.75, 0, 0, -0.75, 1.299038, 0, 10, 20, 30, 1);
}

运行示例

cd example
node test.js

这将生成三个输出文件：

• output.css - 基础转换
• output-preserved.css - 保留原始值
• output-filtered.css - 选择器过滤

为什么使用 matrix3d？

1. 性能优化: 浏览器在处理 matrix3d 时可以跳过解析和计算步骤
2. 跨浏览器一致性: 避免不同浏览器对 transform 函数的实现差异
3. 动画优化: 在某些情况下，matrix3d 的动画性能更好
4. 调试工具: 可以更直观地看到最终的变换矩阵

注意事项

• 已经是 matrix3d 格式的属性不会被重复转换
• 转换失败时会保留原始值并在控制台输出警告
• 单位值（px, em, % 等）会被保留在计算中

开发

# 安装依赖
npm install

# 运行测试
npm test

# 运行示例
node example/test.js

License

ISC