全局样式变量使用指南

版本: v3.0 创建时间: 2024-01-19 项目: jkec-xiaozhi-v2/jk-rag-platform

📁 文件位置

src/styles/
├── variables.scss    # SCSS/CSS 变量（统一文件）
└── global.scss       # 全局样式入口

🚀 快速开始

方式 1: SCSS 变量（推荐）

在 SCSS 文件顶部导入:

@import '@/styles/variables.scss';

// 使用变量
.my-component {
    color: $text-primary;
    padding: $spacing-4;
    border-radius: $radius-lg;
}

方式 2: CSS 变量

在 SCSS/CSS 文件中使用:

.my-component {
    color: var(--text-primary);
    padding: var(--spacing-4);
    border-radius: var(--radius-lg);
}

在 JS/TS 中使用:

const primaryColor = getComputedStyle(
    document.documentElement
).getPropertyValue('--color-primary');

注意: CSS 变量已定义在 variables.scss 的 :root {} 中，无需单独导入 CSS 文件。

📋 变量清单

色彩系统

// 主色调
$primary-color: #1D4ED8;
$primary-light: #3B82F6;
$primary-dark: #1E40AF;

// 辅助色
$success-color: #10B981;
$warning-color: #F59E0B;
$error-color: #EF4444;
$info-color: #3B82F6;

// 中性色
$text-primary: #1F2937;
$text-secondary: #6B7280;
$text-hint: #9CA3AF;
$bg-primary: #F9FAFB;
$bg-secondary: #FFFFFF;
$border-base: #E5E7EB;

间距系统

// 4px 基准
$spacing-1: 4px;
$spacing-2: 8px;
$spacing-3: 12px;
$spacing-4: 16px;
$spacing-6: 24px;
$spacing-8: 32px;

圆角系统

$radius-sm: 4px;
$radius-md: 6px;
$radius-lg: 8px;
$radius-xl: 12px;
$radius-full: 9999px;

阴影系统

$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
$shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
$shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
$shadow-glow: 0 0 20px rgba(59, 130, 246, 0.3);

字体系统

// 字体大小
$font-xs: 9px;
$font-sm: 12px;
$font-base: 13px;
$font-lg: 15px;
$font-xl: 16px;

// 字重
$font-weight-medium: 500;
$font-weight-semibold: 600;

动画系统

// 时长
$animation-fast: 0.1s;
$animation-base: 0.2s;
$animation-slow: 0.3s;

// 缓动
$easing-default: cubic-bezier(0.4, 0, 0.2, 1);

// 快捷过渡
$transition-base: all $animation-base $easing-default;

🔧 旧代码迁移指南

步骤 1: 导入变量文件

在文件顶部添加:

@import '@/styles/variables.scss';

步骤 2: 替换硬编码值

色彩替换

// ❌ 旧代码 (LESS)
color: @primary-color;

// ✅ 新代码 (SCSS)
color: $text-primary;

间距替换

// ❌ 旧代码 (LESS)
padding: @spacing-4;

// ✅ 新代码 (SCSS)
padding: $spacing-4;

步骤 3: 使用 Mixins（可选）

// 文字截断
.my-text {
    @include text-truncate();
}

// 多行文字截断
.my-description {
    @include text-clamp(2);  // 最多 2 行
}

// 居中
.my-center {
    @include center-flex();
}

// 卡片阴影
.my-card {
    @include shadow-card();
}

📝 迁移示例

示例 1: 按钮组件

迁移前 (LESS):

.btn {
    padding: @spacing-2 @spacing-4;
    background: @primary-color;
    color: #FFFFFF;
    border-radius: @radius-md;
    font-size: @font-md;
    font-weight: @font-weight-medium;
    transition: @transition-base;

    &:hover {
        background: @primary-light;
        transform: translateY(-@spacing-1);
        box-shadow: @shadow-md;
    }
}

迁移后 (SCSS):

@import '@/styles/variables.scss';

.btn {
    padding: $spacing-2 $spacing-4;
    background: $primary-color;
    color: #FFFFFF;
    border-radius: $radius-md;
    font-size: $font-md;
    font-weight: $font-weight-medium;
    transition: $transition-base;

    &:hover {
        background: $primary-light;
        transform: translateY(-$spacing-1);
        box-shadow: $shadow-md;
    }
}

示例 2: 卡片组件

迁移前 (LESS):

.card {
    padding: @spacing-5;
    background: @bg-secondary;
    border-radius: @radius-2xl;
    border: 1px solid @border-light;

    &:hover {
        box-shadow: @shadow-xl;
    }
}

迁移后 (SCSS):

@import '@/styles/variables.scss';

.card {
    padding: $spacing-5;
    background: $bg-secondary;
    border-radius: $radius-2xl;
    border: 1px solid $border-light;

    &:hover {
        box-shadow: $shadow-xl;
    }
}

🎯 最佳实践

1. 始终使用变量

// ✅ 好
color: $text-primary;

// ❌ 不好
color: #1F2937;

2. 使用语义化命名

// ✅ 好
background: $bg-active;

// ❌ 不好
background: rgba(29, 78, 216, 0.1);

3. 使用间距系统

// ✅ 好
margin: $spacing-4;

// ❌ 不好
margin: 16px;

4. 使用快捷 Mixins

// ✅ 好
@include text-truncate();

// ❌ 不好
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;

📊 迁移检查清单

文件级别

导入 variables.scss
移除硬编码颜色
移除硬编码间距
移除硬编码圆角
移除硬编码字体
移除硬编码阴影

组件级别

按钮使用 $primary-color
卡片使用 $bg-secondary
文字使用 $text-primary / $text-secondary
边框使用 $border-base
间距使用 $spacing-*
圆角使用 $radius-*

🔍 常见问题

Q1: 变量不生效？

检查:

是否正确导入文件
导入路径是否正确
是否在 SCSS 文件中使用

解决:

// 确保在文件顶部导入
@import '@/styles/variables.scss';

Q2: 如何覆盖变量？

方法:

// 在导入后覆盖
@import '@/styles/variables.scss';
$primary-color: #FF0000;  // 覆盖主色

Q3: CSS 变量和 SCSS 变量选哪个？

📄 相关文档

建科小智设计规范_v3.md - 完整设计规范
variables.scss - SCSS/CSS 变量文件
global.scss - 全局样式

文档维护: AI Assistant 最后更新: 2026-03-28 版本: v4.0 (SCSS)

README.md 6.2 KB Histórico Raw