2026-07-17 17:17:22 +08:00
|
|
|
|
---
|
|
|
|
|
|
kind: frontend_style
|
|
|
|
|
|
name: 基于 UnoCSS + NaiveUI 的主题化样式体系
|
|
|
|
|
|
category: frontend_style
|
|
|
|
|
|
scope:
|
|
|
|
|
|
- '**'
|
|
|
|
|
|
source_files:
|
|
|
|
|
|
- frontend/uno.config.ts
|
|
|
|
|
|
- frontend/packages/uno-preset/src/index.ts
|
|
|
|
|
|
- frontend/src/theme/vars.ts
|
|
|
|
|
|
- frontend/src/theme/settings.ts
|
2026-07-20 18:39:33 +08:00
|
|
|
|
- frontend/src/theme/preset/default.json
|
2026-07-17 17:17:22 +08:00
|
|
|
|
- frontend/src/theme/preset/dark.json
|
|
|
|
|
|
- frontend/src/styles/css/reset.css
|
2026-07-20 18:39:33 +08:00
|
|
|
|
- frontend/src/styles/scss/scrollbar.scss
|
2026-07-17 17:17:22 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
2026-07-20 18:39:33 +08:00
|
|
|
|
## 系统概述
|
|
|
|
|
|
前端采用 **UnoCSS**（原子化 CSS）+ **Naive UI** 组件库的混合方案，配合自研 `@sa/uno-preset` 预设与 JSON 主题预设文件，实现可配置、可切换的多主题中后台风格。
|
2026-07-17 17:17:22 +08:00
|
|
|
|
|
|
|
|
|
|
## 核心架构
|
2026-07-20 18:39:33 +08:00
|
|
|
|
- **原子化样式层**：通过 `unocss` + `presetWind3` 提供 Tailwind 兼容类名；自定义 `presetSoybeanAdmin` 在 `packages/uno-preset/src/index.ts` 中集中定义 `flex-*`、`absolute-*`、`fixed-*` 等常用快捷类。
|
|
|
|
|
|
- **设计令牌层**：`src/theme/vars.ts` 将颜色、阴影映射为 CSS 变量（如 `--primary-color`、`--header-box-shadow`），由 `themeSettings` 与 `src/theme/preset/*.json` 驱动注入。
|
|
|
|
|
|
- **主题预设层**：`src/theme/preset/{default,dark,azir,compact}.json` 以 JSON 描述主题色板、圆角、布局模式、Header/Sider/Tab/Footer 尺寸等，运行时由 `theme-drawer` 动态切换。
|
|
|
|
|
|
- **全局样式层**：`src/styles/css/reset.css` 提供浏览器默认样式重置；`global.css` 统一 `html/body/#app` 高度与基础文本色；`src/styles/scss/global.scss` 引入滚动条 mixin，支持暗色覆盖。
|
2026-07-17 17:17:22 +08:00
|
|
|
|
|
|
|
|
|
|
## 关键文件
|
2026-07-20 18:39:33 +08:00
|
|
|
|
- `frontend/uno.config.ts` — UnoCSS 入口，合并 `themeVars`、注册 `presetWind3({ dark: 'class' })` 与 `presetSoybeanAdmin`、启用 `transformerDirectives` / `transformerVariantGroup`
|
|
|
|
|
|
- `frontend/packages/uno-preset/src/index.ts` — 项目级快捷类集合（flex/absolute/fixed/ellipsis 等）
|
|
|
|
|
|
- `frontend/src/theme/vars.ts` — 生成 `colors.*`、`boxShadow.*` 的 CSS 变量映射表
|
|
|
|
|
|
- `frontend/src/theme/settings.ts` — 默认主题设置（主色、圆角、布局模式、各区域尺寸、light/dark tokens）
|
|
|
|
|
|
- `frontend/src/theme/preset/*.json` — 可插拔主题预设（default/dark/azir/compact）
|
|
|
|
|
|
- `frontend/src/styles/css/reset.css` — 跨浏览器 reset 基线
|
|
|
|
|
|
- `frontend/src/styles/scss/scrollbar.scss` — 带暗色覆盖的滚动条 mixin
|
|
|
|
|
|
- `frontend/package.json` — 依赖声明（naive-ui、unocss、sass、tailwind-merge 等）
|
|
|
|
|
|
|
|
|
|
|
|
## 约定与规则
|
|
|
|
|
|
1. **优先使用 UnoCSS 原子类**：布局用 `flex-center`、`absolute-lt` 等 preset 快捷类，避免手写 flex/position 代码。
|
|
|
|
|
|
2. **主题色通过 CSS 变量消费**：组件内直接引用 `var(--primary-color)` 或 Uno 类 `text-primary`，禁止硬编码十六进制色值。
|
|
|
|
|
|
3. **暗色模式以 class 切换**：Uno 配置 `dark: 'class'`，通过给 `<html>` 添加 `.dark` 类触发，所有样式需遵循此约定。
|
|
|
|
|
|
4. **新增主题走 preset JSON**：在 `src/theme/preset/` 下新建 JSON 文件，保持与 `default.json` 一致的字段结构，再通过 theme drawer 加载。
|
|
|
|
|
|
5. **全局样式分层**：reset 放 `css/reset.css`，业务通用样式放 `scss/global.scss`，页面级样式尽量拆到组件 SCSS 文件中，避免污染全局。
|
|
|
|
|
|
6. **滚动条统一使用 mixin**：需要自定义滚动条时引入 `@forward 'scrollbar'` 并使用 `$size/$color` 参数，确保暗色自动适配。
|
