AndroidRemoteController/doc/PROJECT_CSS_GUIDE.md

项目 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

当前定义的变量

颜色变量

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

尺寸变量

$spacing-base: 0;             // 基础间距
$full-size: 100%;             // 全尺寸

布局变量

$flex-center: (
  display: flex,
  align-items: center,
  justify-content: center
);

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

如何使用变量

1. 导入变量文件

// 在组件 SCSS 文件顶部导入
@import '../../styles/_variables';

2. 使用变量

.device-container {
  background-color: $primary-color;
  width: $full-size;
  height: $full-size;
}

3. 添加新变量

在 _variables.scss 中添加：

// 新颜色
$success-color: #28a745;
$danger-color: #dc3545;

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

---

代码规范

1. 文件组织

✅ 好的做法

// 1. 导入变量（文件顶部）
@import '../../styles/_variables';

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

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

❌ 避免的做法

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

2. 嵌套规范

✅ 好的嵌套（3-4层以内）

.device-container {
  width: $full-size;
  
  .device-update {
    padding: 16px;
    
    .device-update-title {
      font-size: 20px;
    }
  }
}

❌ 避免过度嵌套

// ❌ 嵌套太深，难以维护
.container {
  .wrapper {
    .content {
      .inner {
        .title {
          .text {
            color: red;
          }
        }
      }
    }
  }
}

3. 使用 & 符号

✅ 正确使用

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

4. 注释规范

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

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

---

最佳实践

1. 统一使用变量

✅ 推荐

@import '../../styles/_variables';

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

❌ 不推荐

.container {
  background-color: #0769fb; // ❌ 硬编码
  color: #fff;
}

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

创建混入文件

// 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;
}

使用混入

@import '../../styles/_variables';
@import '../../styles/_mixins';

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

3. 响应式设计

.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 文件：

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

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

---

快速参考

常用代码片段

1. 居中布局

// Flex 居中
@mixin flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

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

2. 清除浮动

@mixin clearfix {
  &::after {
    content: '';
    display: table;
    clear: both;
  }
}

3. 文本省略

@mixin text-ellipsis {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

4. 响应式断点

$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%;
  }
}

颜色函数

$primary: $primary-color;

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

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

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

数学函数

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

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

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

---

常见问题

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

A: 在 src/styles/_variables.scss 中添加：

// 新变量
$new-color: #ff0000;
$new-spacing: 20px;

然后在组件中导入使用：

@import '../../styles/_variables';

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

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

A: 使用混入（Mixin）：

// 在 _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 变量和类切换：

// _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：

$width: 100px;
@debug "Width is: #{$width}";

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

---

项目特定规范

当前项目颜色方案

主色调: #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 语法
• React CSS 方案对比 - 各种 CSS 方案对比
• 现代 CSS 功能 - 现代 CSS 特性

---

贡献指南

添加新样式时

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

代码审查检查点

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

---

最后更新：2025-01-30