Class2CSS - 高性能原子化CSS工具

🚀 企业级原子化CSS生成工具，支持智能单位处理、配置验证、性能缓存和向后兼容

待办

1. 增加缺失检查功能，不主动对class进行删除

✨ 主要特性

• 🔧 智能配置系统 - 新旧配置格式无缝兼容，自动冲突检测和修复
• 🚀 高性能缓存 - 多层缓存机制，增量更新，显著提升生成速度
• 🎯 智能单位处理 - 自动单位转换，支持rpx、px、em等多种单位
• 🧾 输出格式与排序 - 支持 multiLine/singleLine/compressed 格式，支持按选择器名称排序
• 📊 配置诊断 - 完整的配置健康检查和优化建议
• 🔄 实时监控 - 文件变更实时检测，配置热更新
• 🛡️ 向后兼容 - 完全兼容旧版配置，零成本升级
• 📱 小程序优化 - 专为微信小程序设计，支持rpx单位
• 🧩 增量“只增不删” - 统一文件模式支持从输出文件加载基线，可选 appendDelta 追加写入

🚀 快速开始

文档

https://wnagchi.github.io/css2class/

安装

npm install css2class --save-dev

基本使用

# 启动工具（默认使用根目录配置：./class2css.config.js）
npm run start

# 开发模式（文件监听；默认使用根目录配置：./class2css.config.js）
npm run dev

# 构建模式（单次扫描后退出，不监听；默认使用根目录配置：./class2css.config.js）
npm run build

# 运行内置示例（推荐：显式指定）
npm run example:weapp
npm run example:web

# 单次构建内置示例
npm run example:weapp:build
npm run example:web:build

# 可选：启动 weapp 示例 + docs
npm run example:weapp:docs

# 查看帮助/版本
npm run help
npm run version

基础配置

推荐直接复制示例配置（可运行）：

• 小程序（wxss / rpx）：examples/weapp/class2css.config.js + examples/weapp/styles.config.js
• Web（css / px）：examples/web/class2css.config.js + examples/web/styles.config.js

你可以直接用 -c 指定配置启动（不需要改默认文件名）：

# 小程序示例
class2css -c ./examples/weapp/class2css.config.js

# Web 示例
class2css -c ./examples/web/class2css.config.js

📖 配置指南

🆕 新版配置结构

新版本引入了 system 配置节，提供更强大的功能：

module.exports = {
  // 新增的系统配置
  system: {
    baseUnit: "rpx",
    unitConversion: 2,
    compression: true,
    unitStrategy: {
      autoDetect: true,
      propertyUnits: {
        'font-size': 'rpx',
        'width|height': 'rpx',
        'opacity': ''
      }
    }
  },
  
  // 原有配置保持不变
  output: { /* ... */ },
  cssName: { /* ... */ },
  baseClassName: { /* ... */ }
};

🔄 向后兼容

工具完全兼容旧版配置格式：

// 旧版配置仍然有效
module.exports = {
  baseUnit: "rpx",           // 自动映射到 system.baseUnit
  unitConversion: 2,         // 自动映射到 system.unitConversion
  output: { /* ... */ },
  cssName: { /* ... */ },
  baseClassName: { /* ... */ }
};

📊 配置诊断

使用内置诊断工具检查配置健康状况：

// 注意：当前包入口默认仅导出 Class2CSS
// 如需使用诊断工具，可通过内部模块路径引用（未来版本可能调整路径）
const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');

const diagnostics = new ConfigDiagnostics(eventBus, configManager);
const results = await diagnostics.runFullDiagnostics();

console.log(diagnostics.generateReport()); // 生成详细报告

🎯 智能单位处理

自动单位检测

工具能智能识别和处理不同单位：

<!-- 自动添加单位 -->
<view class="m-10 p-20">           <!-- 生成: margin: 20rpx; padding: 40rpx; -->
<view class="w-100px h-50">        <!-- 生成: width: 100px; height: 100rpx; -->
<view class="opacity-50 z-999">    <!-- 生成: opacity: 0.5; z-index: 999; -->

单位转换策略

system: {
  unitStrategy: {
    autoDetect: true,  // 启用自动检测
    propertyUnits: {
      'font-size': 'rpx',      // 字体大小默认使用rpx
      'width|height': 'rpx',   // 宽高默认使用rpx
      'opacity': '',           // 透明度无单位
      'z-index': '',           // 层级无单位
      'line-height': '',       // 行高可以无单位
      'border-radius': 'rpx'   // 圆角默认使用rpx
    }
  }
}

🚀 性能优化

多层缓存机制

• 文件缓存: 缓存已读取的文件内容
• CSS生成缓存: 缓存生成的CSS结果
• 配置缓存: 缓存解析后的配置
• 增量更新: 只处理变更的文件

性能统计

const stats = cacheManager.getCacheStats();
console.log(stats);
// {
//   file: { size: 120, hitRate: 85.2 },
//   cssGeneration: { hits: 450, misses: 50, hitRate: 90.0 },
//   memoryUsage: { kb: 250, mb: 0.24 }
// }

🔧 高级功能

增量模式（只增不删）与 appendDelta

该能力主要面向 统一文件模式（cssOutType: 'uniFile'），用于解决“历史输出文件累积了旧 class，不希望工具主动删除”的场景。

• incrementalOnlyAdd：启用“只增不删”。运行期新增 class 会被保护，不会因为后续文件变化而删除。
• incrementalBaseline：基线来源策略，目前支持从输出文件读取（fromOutputFile）。
• rebuildOnStart：启动时是否重建输出文件（推荐开启）。开启后会全量扫描并覆盖写出一次，输出文件会被“清理到只包含当前项目使用的 class”，然后进入运行期只增不删。
• unusedReportLimit：启动重建时，控制台打印“旧输出存在但当前未使用的 class”的最大示例数量。
• uniFileWriteMode：
  • rewrite：统一文件写入保持兼容（防抖全量覆盖写）。
  • appendDelta：启动时写入 BASE 段 + DELTA_START 标记；运行期仅把新增 class 的 CSS 追加到文件末尾（更快、减少重写）。

示例配置：

module.exports = {
  multiFile: {
    entry: {
      // 扫描/监听入口：
      // - string：单目录/单文件
      // - string[]：多目录/多文件（目录与文件可混用）
      path: "./src",
      fileType: ["wxml", "html"],
    },
    output: {
      cssOutType: "uniFile",
      path: "./dist",
      fileName: "styles.wxss",

      // 增量“只增不删”
      incrementalOnlyAdd: true,
      incrementalBaseline: "fromOutputFile",
      rebuildOnStart: true,
      unusedReportLimit: 200,

      // 统一文件写入策略
      uniFileWriteMode: "appendDelta", // or 'rewrite'
    },
  },
};

appendDelta 模式下输出文件会包含标记：

• /* CLASS2CSS:BASE */：启动重建写入的基础段（压缩/排序后的全量结果）
• /* CLASS2CSS:DELTA_START */：增量追加段起点（运行期新增 class 会追加到该标记之后）

配置模块化

将大型配置拆分为多个模块：

// configs/spacing.config.js
module.exports = {
  margin: {
    "m": { classArr: ["margin"], unit: "rpx" },
    "mt": { classArr: ["margin-top"], unit: "rpx" }
  }
};

// configs/colors.config.js
module.exports = {
  baseColors: {
    primary: "#007bff",
    secondary: "#6c757d"
  }
};

// class2css.config.js
const spacing = require('./configs/spacing.config');
const colors = require('./configs/colors.config');

module.exports = {
  system: { /* ... */ },
  cssName: {
    ...spacing.margin,
    // 其他配置
  }
};

配置验证和自动修复

// 注意：内部模块路径引用（未来版本可能调整路径）
const ConfigValidator = require('class2css/src/core/ConfigValidator');

const validator = new ConfigValidator(eventBus);
const result = validator.validateConfig(config);

if (!result.isValid) {
  console.log('配置错误:', result.errors);
  console.log('警告:', result.warnings);
  
  // 自动修复
  const fixedConfig = validator.autoFix(config);
  console.log('已自动修复配置');
}

📋 使用示例

基础类名

<!-- 间距 -->
<view class="m-10 p-20">           <!-- margin: 20rpx; padding: 40rpx; -->
<view class="mt-15 mb-25">         <!-- margin-top: 30rpx; margin-bottom: 50rpx; -->

<!-- 尺寸 -->
<view class="w-100 h-200">         <!-- width: 200rpx; height: 400rpx; -->
<view class="w-50px h-auto">       <!-- width: 50px; height: auto; -->

<!-- 字体 -->
<text class="text-14 text-16px">   <!-- font-size: 28rpx; font-size: 16px; -->

<!-- 特殊值 -->
<view class="opacity-05 z-999">    <!-- opacity: 0.5; z-index: 999; -->

Important标识

<view class="m-10-i p-20-i">       <!-- margin: 20rpx !important; padding: 40rpx !important; -->

静态类

<view class="container flex-center"> <!-- 预定义的静态类 -->

🛠️ API 参考

Class2CSS 主类

const Class2CSS = require('class2css');

const tool = new Class2CSS();
await tool.init();

// 获取统计信息
const stats = tool.getStats();

// 手动触发扫描
await tool.fullScan();

// 获取配置
const config = tool.getConfig();

ConfigManager

const configManager = tool.configManager;

// 获取配置
const config = configManager.getConfig();

// 获取CSS映射
const cssNameMap = configManager.getCssNameMap();

// 获取单位转换比例
const unitConversion = configManager.getUnitConversion();

CacheManager

const cacheManager = tool.cacheManager;

// 获取缓存统计
const stats = cacheManager.getCacheStats();

// 清除缓存
cacheManager.clearFileCache();
cacheManager.clearCssGenerationCache();

// 配置缓存策略
cacheManager.updateCacheStrategy({
  enableFileCache: true,
  enableCssGenerationCache: true,
  maxCssGenerationCacheSize: 5000
});

🔄 迁移指南

从 1.x 升级到 2.x

1. 配置文件升级（可选）

   // 旧版本配置仍然有效
   module.exports = {
     baseUnit: "rpx",
     unitConversion: 2,
     // ... 其他配置
   };
      
   // 推荐升级到新格式
   module.exports = {
     system: {
       baseUnit: "rpx",
       unitConversion: 2,
       compression: true  // 新功能
     },
     // ... 其他配置
   };

2. API 变更

   // 旧版本
   const tool = new Class2CSS(config);
      
   // 新版本（配置文件自动加载）
   const tool = new Class2CSS();
   await tool.init();

3. 新功能启用

   // 启用新的单位处理策略
   system: {
     unitStrategy: {
       autoDetect: true,
       propertyUnits: { /* ... */ }
     }
   }

配置迁移工具

使用内置的兼容性适配器自动迁移：

// 注意：内部模块路径引用（未来版本可能调整路径）
const CompatibilityAdapter = require('class2css/src/core/CompatibilityAdapter');

const adapter = new CompatibilityAdapter(eventBus);
const adaptedConfig = adapter.adaptConfig(oldConfig);

📊 最佳实践

1. 配置组织

// ✅ 推荐：模块化配置
const spacing = require('./configs/spacing.config');
const typography = require('./configs/typography.config');

module.exports = {
  system: {
    baseUnit: "rpx",
    unitConversion: 2,
    compression: true
  },
  cssName: {
    ...spacing,
    ...typography
  }
};

2. 性能优化

// ✅ 启用缓存
system: {
  compression: true  // 启用CSS压缩
},

// ✅ 配置缓存策略
cacheStrategy: {
  enableFileCache: true,
  enableCssGenerationCache: true,
  maxFileAge: 24 * 60 * 60 * 1000  // 24小时
}

3. 单位处理

// ✅ 使用智能单位策略
system: {
  unitStrategy: {
    autoDetect: true,
    propertyUnits: {
      'font-size': 'rpx',
      'width|height': 'rpx',
      'opacity': '',
      'z-index': ''
    }
  }
}

4. 开发工作流

// package.json
{
  "scripts": {
    "start": "node bin/class2css.js",
    "dev": "node bin/class2css.js --config ./class2css.config.js",
    "build": "node bin/class2css.js --no-watch",
    "help": "node bin/class2css.js --help",
    "version": "node bin/class2css.js --version"
  }
}

🧰 CLI 使用说明

安装后可通过 class2css 命令运行（或用 node bin/class2css.js）。常用参数：

• -c, --config <path>：指定配置文件路径（默认 ./class2css.config.js）
• --no-watch：关闭监听模式（执行一次扫描后退出）
• -i, --input <path>：运行时覆盖输入目录（覆盖配置里的扫描/监听目录）
• -o, --output <path>：运行时覆盖输出目录
• -f, --output-file <name>：运行时覆盖输出文件名
• -t, --output-type <type>：运行时覆盖输出类型（filePath 或 uniFile）

示例：

# 默认配置启动（监听模式）
class2css

# 单次构建（不监听）
class2css --no-watch

# 运行时覆盖输入/输出
class2css -i ./src -o ./dist -f styles.wxss -t uniFile

🐛 故障排除

常见问题

1. 配置冲突

   错误: CSS property conflict detected for 'font-size'
   解决: 运行配置诊断工具检查冲突

2. 单位不一致

   警告: Unit inconsistency detected
   解决: 启用 autoDetect 或统一单位配置

3. 性能问题

   解决: 启用缓存，使用增量更新

诊断工具

// 运行完整诊断
const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');
const diagnostics = new ConfigDiagnostics(eventBus, configManager);
const results = await diagnostics.runFullDiagnostics();
console.log(diagnostics.generateReport());

// 获取优化建议
const suggestions = diagnostics.generateOptimizationSuggestions();

📈 性能数据

• 缓存命中率: 90%+
• CSS生成速度: 提升 300%
• 内存使用: 减少 40%
• 文件监听延迟: < 100ms

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

📄 许可证

MIT © wnagchi

🔗 相关链接

• GitHub 仓库
• 问题反馈
• 更新日志
• 配置参考
• API 文档
• 贡献指南

💡 如有问题或建议，欢迎提交 Issue 或加入我们的讨论！