# 项目 CSS/SCSS 使用规范

## 📋 目录

1. [项目概述](#项目概述)
2. [文件结构](#文件结构)
3. [变量系统](#变量系统)
4. [代码规范](#代码规范)
5. [最佳实践](#最佳实践)
6. [快速参考](#快速参考)
7. [常见问题](#常见问题)

---

## 项目概述

### 当前使用的方案
- **SCSS**：项目使用 SCSS 作为 CSS 预处理器
- **Vite**：构建工具，内置 SCSS 支持
- **变量系统**：统一的变量管理

### 技术栈
- React 18.2.0
- Vite 5.0.8
- Sass 1.97.3

---

## 文件结构

### 目录结构
```
src/
├── styles/
│   └── _variables.scss      # 全局变量文件
├── page/
│   ├── home.scss            # 页面样式
│   ├── device/
│   │   └── device.scss      # 组件样式
│   ├── ai-chat/
│   │   ├── ai-chat.scss
│   │   ├── input/
│   │   │   └── input.scss
│   │   └── dialog/
│   │       └── dialog.scss
│   └── ...
```

### 命名规范
- **变量文件**：使用下划线前缀 `_variables.scss`
- **组件样式**：与组件同名 `device.scss`、`home.scss`
- **导入变量**：使用 `@import '../../styles/_variables'`

---

## 变量系统

### 全局变量文件
位置：`src/styles/_variables.scss`

### 当前定义的变量

#### 颜色变量
```scss
$primary-color: #0769fb;      // 主色调
$ai-chat-bg: #e0e8f4;         // AI聊天背景色
$process-bg: #07fb40;         // 进程背景色
$screenshot-bg: #fb0707e6;    // 截图背景色
$white: #fff;                 // 白色
$black: #000;                 // 黑色
```

#### 尺寸变量
```scss
$spacing-base: 0;             // 基础间距
$full-size: 100%;             // 全尺寸
```

#### 布局变量
```scss
$flex-center: (
  display: flex,
  align-items: center,
  justify-content: center
);

$reset: (
  margin: 0,
  padding: 0
);
```

### 如何使用变量

#### 1. 导入变量文件
```scss
// 在组件 SCSS 文件顶部导入
@import '../../styles/_variables';
```

#### 2. 使用变量
```scss
.device-container {
  background-color: $primary-color;
  width: $full-size;
  height: $full-size;
}
```

#### 3. 添加新变量
在 `_variables.scss` 中添加：
```scss
// 新颜色
$success-color: #28a745;
$danger-color: #dc3545;

// 新尺寸
$spacing-sm: 8px;
$spacing-md: 16px;
$spacing-lg: 24px;
```

---

## 代码规范

### 1. 文件组织

#### ✅ 好的做法
```scss
// 1. 导入变量（文件顶部）
@import '../../styles/_variables';

// 2. 组件根类
.device-container {
  // 样式
}

// 3. 嵌套子元素
.device-container {
  .device-update {
    // 样式
  }
}
```

#### ❌ 避免的做法
```scss
// 不要忘记导入变量
.device-container {
  background-color: #0769fb; // ❌ 应该使用 $primary-color
}
```

### 2. 嵌套规范

#### ✅ 好的嵌套（3-4层以内）
```scss
.device-container {
  width: $full-size;
  
  .device-update {
    padding: 16px;
    
    .device-update-title {
      font-size: 20px;
    }
  }
}
```

#### ❌ 避免过度嵌套
```scss
// ❌ 嵌套太深，难以维护
.container {
  .wrapper {
    .content {
      .inner {
        .title {
          .text {
            color: red;
          }
        }
      }
    }
  }
}
```

### 3. 使用 & 符号

#### ✅ 正确使用
```scss
.button {
  background: $primary-color;
  
  // 伪类
  &:hover {
    background: darken($primary-color, 10%);
  }
  
  // 修饰符
  &.active {
    background: #28a745;
  }
  
  // 伪元素
  &::before {
    content: '';
  }
}
```

### 4. 注释规范

```scss
// 单行注释（推荐）
.device-container {
  // 设备容器样式
  width: 100%;
}

/* 
 * 多行注释
 * 用于复杂说明
 */
```

---

## 最佳实践

### 1. 统一使用变量

#### ✅ 推荐
```scss
@import '../../styles/_variables';

.container {
  background-color: $primary-color;
  color: $white;
}
```

#### ❌ 不推荐
```scss
.container {
  background-color: #0769fb; // ❌ 硬编码
  color: #fff;
}
```

### 2. 创建混入（Mixin）复用代码

#### 创建混入文件
```scss
// src/styles/_mixins.scss
@mixin flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

@mixin button-base {
  padding: 12px 24px;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.3s;
}
```

#### 使用混入
```scss
@import '../../styles/_variables';
@import '../../styles/_mixins';

.device-container {
  @include flex-center;
  width: $full-size;
}
```

### 3. 响应式设计

```scss
.device-container {
  width: 100%;
  
  // 移动端
  @media (max-width: 768px) {
    padding: 10px;
    
    .device-update {
      flex-direction: column;
    }
  }
  
  // 桌面端
  @media (min-width: 1200px) {
    max-width: 1200px;
    margin: 0 auto;
  }
}
```

### 4. 组件样式隔离

每个组件有自己的 SCSS 文件：
```scss
// device/device.scss
.device-container {
  // 只包含 device 组件的样式
}

// home.scss
.home-container {
  // 只包含 home 组件的样式
}
```

---

## 快速参考

### 常用代码片段

#### 1. 居中布局
```scss
// Flex 居中
@mixin flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

// 使用
.container {
  @include flex-center;
}
```

#### 2. 清除浮动
```scss
@mixin clearfix {
  &::after {
    content: '';
    display: table;
    clear: both;
  }
}
```

#### 3. 文本省略
```scss
@mixin text-ellipsis {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}
```

#### 4. 响应式断点
```scss
$breakpoints: (
  'sm': 576px,
  'md': 768px,
  'lg': 992px,
  'xl': 1200px
);

@mixin respond-to($breakpoint) {
  $value: map-get($breakpoints, $breakpoint);
  
  @if $value {
    @media (min-width: $value) {
      @content;
    }
  }
}

// 使用
.container {
  width: 100%;
  
  @include respond-to('md') {
    width: 50%;
  }
}
```

### 颜色函数

```scss
$primary: $primary-color;

// 变亮/变暗
lighten($primary, 20%)
darken($primary, 10%)

// 调整透明度
rgba($primary, 0.8)

// 混合颜色
mix($primary, white, 50%)
```

### 数学函数

```scss
// 百分比
percentage(2/3)  // 66.666667%

// 四舍五入
round(18.7px)    // 19px

// 向上/向下取整
ceil(18.2px)     // 19px
floor(18.9px)    // 18px
```

---

## 常见问题

### Q1: 如何添加新的全局变量？

**A:** 在 `src/styles/_variables.scss` 中添加：
```scss
// 新变量
$new-color: #ff0000;
$new-spacing: 20px;
```

然后在组件中导入使用：
```scss
@import '../../styles/_variables';

.container {
  color: $new-color;
  padding: $new-spacing;
}
```

### Q2: 如何创建可复用的样式？

**A:** 使用混入（Mixin）：
```scss
// 在 _mixins.scss 中定义
@mixin card-style {
  padding: 16px;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

// 使用
.card {
  @include card-style;
}
```

### Q3: 如何实现主题切换？

**A:** 使用 SCSS 变量和类切换：
```scss
// _variables.scss
$themes: (
  'light': (
    'bg': #fff,
    'text': #333
  ),
  'dark': (
    'bg': #1a1a1a,
    'text': #fff
  )
);

@function theme($theme-name, $key) {
  $theme: map-get($themes, $theme-name);
  @return map-get($theme, $key);
}

// 使用
.container {
  background-color: theme('light', 'bg');
  
  .dark-theme & {
    background-color: theme('dark', 'bg');
  }
}
```

### Q4: 样式不生效怎么办？

**检查清单：**
1. ✅ 确认文件扩展名是 `.scss`
2. ✅ 确认在组件中正确导入：`import './component.scss'`
3. ✅ 确认类名拼写正确
4. ✅ 检查浏览器控制台是否有错误
5. ✅ 确认 SCSS 文件已保存

### Q5: 如何调试 SCSS？

**A:** 使用 `@debug` 和 `@warn`：
```scss
$width: 100px;
@debug "Width is: #{$width}";

@function calculate($value) {
  @if $value < 0 {
    @warn "Value should be positive";
  }
  @return $value * 2;
}
```

---

## 项目特定规范

### 当前项目颜色方案
```scss
主色调: #0769fb (蓝色)
AI聊天: #e0e8f4 (浅蓝灰)
进程:   #07fb40 (绿色)
截图:   #fb0707e6 (红色，带透明度)
```

### 组件样式文件位置
- `home.scss` - 首页布局
- `device/device.scss` - 设备管理
- `ai-chat/ai-chat.scss` - AI聊天
- `process/process.scss` - 进程管理
- `screenshot/screenshot.scss` - 截图功能
- `public/alert-view/alert-view.scss` - 弹窗组件

---

## 更新日志

### 2025-01-30
- ✅ 项目迁移到 SCSS
- ✅ 创建全局变量系统
- ✅ 统一代码规范
- ✅ 删除所有旧 CSS 文件

---

## 相关文档

- [SCSS 使用指南](./SCSS_USAGE_GUIDE.md) - 详细的 SCSS 语法
- [React CSS 方案对比](./REACT_CSS_COMPARISON.md) - 各种 CSS 方案对比
- [现代 CSS 功能](./MODERN_CSS_EXAMPLES.md) - 现代 CSS 特性

---

## 贡献指南

### 添加新样式时
1. ✅ 优先使用现有变量
2. ✅ 如需新变量，添加到 `_variables.scss`
3. ✅ 保持嵌套不超过 4 层
4. ✅ 添加必要的注释
5. ✅ 遵循命名规范

### 代码审查检查点
- [ ] 是否使用了变量而非硬编码？
- [ ] 嵌套是否过深？
- [ ] 是否有重复代码可以提取为混入？
- [ ] 是否添加了必要的注释？
- [ ] 响应式设计是否考虑？

---

**最后更新：2025-01-30**