@brickjs-fe/stylelint-config/README.md

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

# @brickjs-fe/stylelint-config

<div align="center">

![BrickJs Stylelint Config](https://img.shields.io/badge/BrickJs-Stylelint%20Config-blue?style=for-the-badge&logo=stylelint)

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

[![npm version](https://img.shields.io/npm/v/@brickjs-fe/stylelint-config?style=flat-square)](https://www.npmjs.com/package/@brickjs-fe/stylelint-config)
[![npm downloads](https://img.shields.io/npm/dm/@brickjs-fe/stylelint-config?style=flat-square)](https://www.npmjs.com/package/@brickjs-fe/stylelint-config)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

</div>

## 📖 项目介绍

`@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**: 属性顺序检查

## 🚀 快速开始

### 安装

```bash
# 使用 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` 文件：

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

### 在 package.json 中使用

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

### 使用 ES 模块

```javascript
// .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**: 使用现代媒体查询

## 🔧 配置选项

### 环境配置

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

### 规则覆盖

```javascript
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. 样式示例

```css
/* 组件样式 */
.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 示例

```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 插件

### 调试技巧

```bash
# 检查 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](https://opensource.org/licenses/MIT) 许可证开源。

## 👥 维护者

- [brickFE](https://github.com/brickFE) - _项目维护者_

## 🙏 致谢

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

- [Stylelint](https://stylelint.io/) - CSS 代码检查工具
- [stylelint-config-standard](https://github.com/stylelint/stylelint-config-standard) - 标准配置
- [stylelint-config-prettier](https://github.com/prettier/stylelint-config-prettier) - Prettier 兼容配置
- [stylelint-order](https://github.com/hudochenkov/stylelint-order) - 属性顺序检查

---

<div align="center">

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

[报告问题](https://github.com/brickFE/brickjs/issues) · [提出建议](https://github.com/brickFE/brickjs/discussions) · [贡献代码](https://github.com/brickFE/brickjs/pulls)

</div>