VUP

简体中文

English

简体中文

English

Appearance

主题系统 ​

VUP 提供统一的主题系统，通过 _shared/assets/styles 目录维护全局主题与设计令牌，支持 CSS 变量和 Tailwind CSS 集成。

概述 ​

主题系统包含以下核心文件：

  • base-colors.scss - 基础色板（0-9 色阶）
  • base-size.scss - 间距、圆角、字号、行高、控件高度
  • theme.scss - 语义色映射（primary/success/warning/error/info/neutral）
  • tailwind.scss - Tailwind CSS 主题集成

文件结构 ​

_shared/assets/styles/
  ├─ base-colors.scss    # 基础色板
  ├─ base-size.scss     # 尺寸系统
  ├─ theme.scss         # 语义色映射
  └─ tailwind.scss      # Tailwind 集成

基础色板 (base-colors.scss) ​

基础色板定义了 0-9 共 10 个色阶，每个颜色都有完整的色阶体系：

颜色分类 ​

  • Blue (primary) - 主色调，蓝色系
  • Green (success) - 成功色，绿色系
  • Gold (warning) - 警告色，金色系
  • Red (error) - 错误色，红色系
  • Gray (info/neutral) - 信息色/中性色，灰色系

色阶说明 ​

每个颜色从 0-9 共 10 个色阶：

  • 0 - 最浅（背景色）
  • 5 - 主色（常用）
  • 9 - 最深（文字色）

使用示例 ​

css
/* 使用基础色板 */
.element {
  background-color: var(--vup-blue-0); /* 最浅蓝色 */
  color: var(--vup-blue-5); /* 主蓝色 */
  border-color: var(--vup-blue-9); /* 最深蓝色 */
}

尺寸系统 (base-size.scss) ​

尺寸系统定义了统一的间距、圆角、字号等设计令牌：

间距 (Space) ​

css
--vup-space-0: 0;
--vup-space-2: 2px;
--vup-space-4: 4px;
--vup-space-8: 8px;
--vup-space-12: 12px;
--vup-space-16: 16px;
--vup-space-24: 24px;
--vup-space-32: 32px;
--vup-space-48: 48px;
--vup-space-64: 64px;

圆角 (Radius) ​

css
--vup-radius-xs: 2px;
--vup-radius-sm: 4px;
--vup-radius-md: 6px;
--vup-radius-lg: 8px;
--vup-radius-xl: 12px;

字号 (Font Size) ​

css
--vup-font-size-xs: 12px;
--vup-font-size-sm: 13px;
--vup-font-size-md: 14px;
--vup-font-size-lg: 16px;
--vup-font-size-xl: 18px;
--vup-font-size-2xl: 20px;

行高 (Line Height) ​

css
--vup-line-height-xs: 1.2;
--vup-line-height-sm: 1.4;
--vup-line-height-md: 1.6;
--vup-line-height-lg: 1.8;

控件高度 (Control Height) ​

css
--vup-control-height-xs: 24px;
--vup-control-height-sm: 28px;
--vup-control-height-md: 32px;
--vup-control-height-lg: 36px;
--vup-control-height-xl: 40px;

语义色 (theme.scss) ​

语义色将基础色板映射为语义化的颜色变量：

语义色分类 ​

  • primary - 主色（映射自 blue）
  • success - 成功色（映射自 green）
  • warning - 警告色（映射自 gold）
  • error - 错误色（映射自 red）
  • info - 信息色（映射自 gray）
  • neutral - 中性色（映射自 gray）

使用示例 ​

css
/* 使用语义色 */
.button-primary {
  background-color: var(--vup-primary-5);
  color: var(--vup-primary-0);
}

.button-success {
  background-color: var(--vup-success-5);
  color: var(--vup-success-0);
}

.text-error {
  color: var(--vup-error-5);
}

引入方式 ​

1. 引入语义主题（CSS 变量） ​

在项目入口文件或全局样式文件中引入：

ts
// main.ts 或全局样式文件
import '@_shared/assets/styles/theme.scss';

引入后即可在组件中使用 CSS 变量：

vue
<template>
  <div class="custom-element">内容</div>
</template>

<style scoped>
.custom-element {
  background-color: var(--vup-primary-0);
  color: var(--vup-primary-5);
  padding: var(--vup-space-16);
  border-radius: var(--vup-radius-md);
}
</style>

2. 引入 Tailwind 集成 ​

如果项目启用了 Tailwind CSS，可以引入 Tailwind 主题集成：

ts
// main.ts 或全局样式文件
import '@_shared/assets/styles/tailwind.scss';

引入后可以在 Tailwind 类中使用主题颜色：

vue
<template>
  <div class="bg-primary-5 text-primary-0 p-4 rounded-md">
    使用 Tailwind 主题色
  </div>
</template>

Tailwind CSS 集成 ​

引入 tailwind.scss 后，主题色会自动映射到 Tailwind 的颜色系统：

颜色类 ​

html
<!-- 主色 -->
<div class="bg-primary-5 text-primary-0">主色</div>

<!-- 成功色 -->
<div class="bg-success-5 text-success-0">成功色</div>

<!-- 警告色 -->
<div class="bg-warning-5 text-warning-0">警告色</div>

<!-- 错误色 -->
<div class="bg-error-5 text-error-0">错误色</div>

<!-- 信息色 -->
<div class="bg-info-5 text-info-0">信息色</div>

尺寸类 ​

html
<!-- 间距 -->
<div class="p-4 m-8">使用主题间距</div>

<!-- 圆角 -->
<div class="rounded-md">使用主题圆角</div>

使用示例 ​

Vue 组件中使用 CSS 变量 ​

vue
<template>
  <div class="card">
    <h2 class="title">标题</h2>
    <p class="content">内容</p>
    <button class="button">按钮</button>
  </div>
</template>

<style scoped>
.card {
  background-color: var(--vup-neutral-0);
  border: 1px solid var(--vup-neutral-3);
  border-radius: var(--vup-radius-lg);
  padding: var(--vup-space-24);
}

.title {
  color: var(--vup-primary-5);
  font-size: var(--vup-font-size-xl);
  margin-bottom: var(--vup-space-16);
}

.content {
  color: var(--vup-neutral-7);
  font-size: var(--vup-font-size-md);
  line-height: var(--vup-line-height-md);
}

.button {
  background-color: var(--vup-primary-5);
  color: var(--vup-primary-0);
  padding: var(--vup-space-8) var(--vup-space-16);
  border-radius: var(--vup-radius-md);
  height: var(--vup-control-height-md);
}
</style>

使用 Tailwind 类 ​

vue
<template>
  <div class="bg-neutral-0 border border-neutral-3 rounded-lg p-6">
    <h2 class="text-primary-5 text-xl mb-4">标题</h2>
    <p class="text-neutral-7 text-md leading-md">内容</p>
    <button class="bg-primary-5 text-primary-0 px-4 py-2 rounded-md h-8">
      按钮
    </button>
  </div>
</template>

组合使用 ​

vue
<template>
  <div class="card">
    <div class="header">头部</div>
    <div class="body">内容</div>
  </div>
</template>

<style scoped>
.card {
  /* 使用 CSS 变量 */
  background-color: var(--vup-neutral-0);
  border-radius: var(--vup-radius-lg);

  /* 结合 Tailwind */
  @apply p-6 shadow-md;
}

.header {
  /* 使用语义色 */
  color: var(--vup-primary-5);
  @apply mb-4 text-xl font-bold;
}
</style>

自定义主题 ​

覆盖基础色板 ​

如果需要自定义颜色，可以在项目中覆盖基础色板：

scss
// 在你的样式文件中
:root {
  /* 覆盖主色 */
  --vup-blue-5: #your-color;
  --vup-blue-6: #your-darker-color;
}

覆盖语义色 ​

scss
:root {
  /* 覆盖语义色映射 */
  --vup-primary-5: var(--vup-blue-5);
  --vup-primary-6: var(--vup-blue-6);
}

覆盖尺寸 ​

scss
:root {
  /* 覆盖间距 */
  --vup-space-16: 20px;

  /* 覆盖圆角 */
  --vup-radius-md: 8px;
}

最佳实践 ​

  1. 优先使用语义色 - 使用 primary、success 等语义色，而不是直接使用 blue、green
  2. 使用 CSS 变量 - 在需要精确控制时使用 CSS 变量
  3. 结合 Tailwind - 在快速开发时使用 Tailwind 类
  4. 保持一致性 - 在整个项目中使用统一的主题令牌
  5. 响应式设计 - 结合 Tailwind 的响应式类实现响应式布局

注意事项 ​

  • 主题文件需要在项目入口或全局样式中引入
  • 大部分模板已经自动引入了主题文件
  • CSS 变量在运行时可用，无需编译
  • Tailwind 集成需要在 tailwind.config.js 中正确配置
  • 自定义主题时注意保持色阶的一致性

相关资源 ​

Copyright © 2025 VUP-CLI