@brickjs-fe/stylelint-config

适用于 Vue3 + TypeScript 项目的 CSS 代码检查配置

📖 项目介绍

@brickjs-fe/stylelint-config 是 BrickJs 项目提供的 Stylelint 配置包，专为 Vue3 + TypeScript 项目设计。该配置提供了完整的 CSS 代码检查规则，确保样式代码的质量和一致性。

✨ 特性

• 🎯 Vue3 支持: 完整的 Vue3 单文件组件样式支持
• 🔧 多语言支持: 支持 CSS、SCSS、SASS、Less 等样式语言
• 🎨 统一风格: 与 Prettier 规则完美兼容
• 📝 详细注释: 每个规则都有详细的中文注释说明
• 🔄 灵活配置: 支持覆盖和自定义规则
• 🚀 现代 CSS: 支持现代 CSS 特性和最佳实践

🛠️ 技术栈

• Stylelint: CSS 代码检查工具
• stylelint-config-standard: 标准配置
• stylelint-config-standard-scss: SCSS 标准配置
• stylelint-config-prettier: Prettier 兼容配置
• stylelint-order: 属性顺序检查

🚀 快速开始

安装

# 使用 pnpm 安装
pnpm add -D @brickjs-fe/stylelint-config stylelint

# 或使用 npm 安装
npm install -D @brickjs-fe/stylelint-config stylelint

# 或使用 yarn 安装
yarn add -D @brickjs-fe/stylelint-config stylelint

# 或使用 bun 安装
bun add -D @brickjs-fe/stylelint-config stylelint

基本使用

在项目根目录创建 .stylelintrc.js 文件：

module.exports = require("@brickjs-fe/stylelint-config");

在 package.json 中使用

{
  "stylelint": {
    "extends": ["@brickjs-fe/stylelint-config"]
  }
}

使用 ES 模块

// .stylelintrc.mjs
import config from "@brickjs-fe/stylelint-config";

export default config;

📋 配置说明

基础规则

• at-rule-no-unknown: 禁止未知的 at 规则
• selector-pseudo-class-no-unknown: 禁止未知的伪类选择器
• selector-pseudo-element-no-unknown: 禁止未知的伪元素选择器

代码风格规则

• block-no-empty: 禁止空块
• comment-no-empty: 禁止空注释
• no-duplicate-selectors: 禁止重复的选择器
• no-empty-source: 禁止空源
• no-extra-semicolons: 禁止额外的分号

颜色和值规则

• color-no-invalid-hex: 禁止无效的十六进制颜色
• function-name-case: 禁止无效的命名
• number-no-trailing-zeros: 禁止无效的数字
• string-no-newline: 禁止无效的字符串
• unit-no-unknown: 禁止无效的单位

属性规则

• property-no-unknown: 禁止无效的属性
• keyframe-declaration-no-important: 禁止无效的关键字
• declaration-block-no-duplicate-properties: 禁止无效的声明
• declaration-block-no-redundant-longhand-properties: 禁止无效的声明块
• shorthand-property-no-redundant-values: 禁止无效的简写属性

选择器规则

• selector-max-compound-selectors: 限制选择器数量
• selector-max-id: 限制 ID 选择器
• selector-max-type: 限制类型选择器
• selector-max-universal: 限制通用选择器

媒体查询规则

• media-feature-name-no-unknown: 禁止无效的媒体特性
• media-feature-range-notation: 使用现代媒体查询

属性顺序规则

• order/properties-order: 属性顺序检查
  • 定位属性
  • 盒模型属性
  • 字体属性
  • 背景属性
  • 其他属性

兼容性规则

• property-no-vendor-prefix: 禁止使用浏览器前缀
• value-no-vendor-prefix: 禁止使用浏览器前缀
• selector-no-vendor-prefix: 禁止使用浏览器前缀

性能规则

• max-nesting-depth: 限制选择器嵌套深度
• selector-max-compound-selectors: 限制选择器数量
• selector-max-id: 限制 ID 选择器

可访问性规则

• color-no-hex: 禁止使用颜色作为唯一标识
• color-named: 禁止使用颜色名称
• color-function-notation: 使用现代颜色函数

现代 CSS 规则

• color-function-notation: 使用现代颜色函数
• length-zero-no-unit: 使用现代长度单位
• selector-not-notation: 使用现代选择器
• media-feature-range-notation: 使用现代媒体查询

🔧 配置选项

环境配置

module.exports = {
  ...require("@brickjs-fe/stylelint-config"),
  // 可以在这里添加项目特定的配置
  rules: {
    // 覆盖特定规则
    "max-nesting-depth": 4, // 允许更深的嵌套
  },
};

规则覆盖

module.exports = {
  ...require("@brickjs-fe/stylelint-config"),
  rules: {
    // 覆盖特定规则
    "color-no-hex": false, // 允许使用十六进制颜色
    "property-no-unknown": [
      true,
      {
        ignoreProperties: ["composes", "custom-property"],
      },
    ],
  },
};

📁 文件支持

该配置支持以下文件类型：

• .css - CSS 文件
• .scss - SCSS 文件
• .sass - SASS 文件
• .less - Less 文件
• .vue - Vue 单文件组件
• .jsx - React JSX 文件
• .tsx - TypeScript JSX 文件

🎯 最佳实践

1. 项目结构

project/
├── .stylelintrc.js        # Stylelint 配置
├── .prettierrc.js         # Prettier 配置
├── .eslintrc.js           # ESLint 配置
├── src/                   # 源代码目录
│   ├── styles/           # 样式文件
│   │   ├── global.css    # 全局样式
│   │   ├── variables.css # 变量定义
│   │   └── components/   # 组件样式
│   ├── components/       # Vue 组件
│   └── views/           # 页面组件
└── package.json          # 项目配置

2. 样式示例

/* 组件样式 */
.example {
  /* 定位 */
  position: relative;
  top: 0;
  left: 0;
  z-index: 1;

  /* 盒模型 */
  display: flex;
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 20px;
  border: 1px solid #ccc;
  border-radius: 4px;

  /* 字体 */
  font-family: "Arial", sans-serif;
  font-size: 16px;
  font-weight: 400;
  line-height: 1.5;
  text-align: center;
  color: #333;

  /* 背景 */
  background-color: #fff;
  background-image: url("bg.png");
  background-position: center;
  background-repeat: no-repeat;
  background-size: cover;

  /* 其他 */
  opacity: 1;
  visibility: visible;
  overflow: hidden;
  cursor: pointer;
  user-select: none;
  transition: all 0.3s ease;
  transform: translateX(0);
  animation: fadeIn 0.5s ease;
}

@keyframes fadeIn {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

3. SCSS 示例

// 变量定义
$primary-color: #007bff;
$secondary-color: #6c757d;
$border-radius: 4px;

// 混入
@mixin button-style($bg-color, $text-color: #fff) {
  background-color: $bg-color;
  color: $text-color;
  border: none;
  border-radius: $border-radius;
  padding: 8px 16px;
  cursor: pointer;
  transition: background-color 0.3s ease;

  &:hover {
    background-color: darken($bg-color, 10%);
  }
}

// 组件样式
.button {
  @include button-style($primary-color);

  &--secondary {
    @include button-style($secondary-color);
  }

  &--large {
    padding: 12px 24px;
    font-size: 18px;
  }
}

🔍 故障排除

常见问题

1. 规则冲突: 确保 Stylelint 配置与 Prettier 规则兼容
2. 文件格式: 检查文件扩展名是否被支持
3. 编辑器集成: 确保编辑器已安装 Stylelint 插件

调试技巧

# 检查 Stylelint 配置
npx stylelint --print-config src/styles/main.css

# 检查特定文件的样式
npx stylelint src/components/Button.vue

# 运行 Stylelint 检查
npx stylelint src --ext .css,.scss,.vue

🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'feat: add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

本项目基于 MIT 许可证开源。

👥 维护者

• brickFE - 项目维护者

🙏 致谢

感谢以下开源项目的支持：

• Stylelint - CSS 代码检查工具
• stylelint-config-standard - 标准配置
• stylelint-config-prettier - Prettier 兼容配置
• stylelint-order - 属性顺序检查

如果这个项目对你有帮助，请给它一个 ⭐️

报告问题 · 提出建议 · 贡献代码