eafonyang
3.3 KiB
3.3 KiB
kind, name, category, scope, source_files
| kind | name | category | scope | source_files | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| frontend_style | 基于 UnoCSS + NaiveUI 的主题化样式体系 | frontend_style |
|
|
系统概述
前端采用 UnoCSS（原子化 CSS）+ Naive UI 组件库的混合方案，配合自研 @sa/uno-preset 预设与 JSON 主题预设文件，实现可配置、可切换的多主题中后台风格。
核心架构
- 原子化样式层：通过
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，支持暗色覆盖。
关键文件
frontend/uno.config.ts— UnoCSS 入口，合并themeVars、注册presetWind3({ dark: 'class' })与presetSoybeanAdmin、启用transformerDirectives/transformerVariantGroupfrontend/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— 带暗色覆盖的滚动条 mixinfrontend/package.json— 依赖声明（naive-ui、unocss、sass、tailwind-merge 等）
约定与规则
- 优先使用 UnoCSS 原子类：布局用
flex-center、absolute-lt等 preset 快捷类，避免手写 flex/position 代码。 - 主题色通过 CSS 变量消费：组件内直接引用
var(--primary-color)或 Uno 类text-primary，禁止硬编码十六进制色值。 - 暗色模式以 class 切换：Uno 配置
dark: 'class'，通过给<html>添加.dark类触发，所有样式需遵循此约定。 - 新增主题走 preset JSON：在
src/theme/preset/下新建 JSON 文件，保持与default.json一致的字段结构，再通过 theme drawer 加载。 - 全局样式分层：reset 放
css/reset.css，业务通用样式放scss/global.scss，页面级样式尽量拆到组件 SCSS 文件中，避免污染全局。 - 滚动条统一使用 mixin：需要自定义滚动条时引入
@forward 'scrollbar'并使用$size/$color参数，确保暗色自动适配。