外观
自定义主题
约 2434 字大约 8 分钟
2025-10-31
uView-unix 提供了强大的主题定制功能,通过简单的变量覆盖,您可以轻松定制应用的整体视觉风格,实现品牌的统一化设计。
主题系统特点
- 基于 SCSS 和 CSS 变量双重支持:结合了 SCSS 的编译时变量和 CSS 变量的运行时可变性
- 灵活的变量覆盖机制:支持全局变量覆盖和组件级别的样式定制
- 完善的变量体系:包含行高、圆角、字号、颜色等全方位的设计变量
- 默认值 fallback 机制:即使未定义某些变量,也能保证系统正常运行
工作原理
这种定义方式遵循以下优先级规则:
- 最高优先级:CSS变量 (
--un-color-primary) - 运行时可动态修改 - 中等优先级:自定义SCSS变量 (
$un-color-primary) - 通过覆盖文件定义 - 最低优先级:默认值 (
#1677FF) - 系统内置的默认值
方法一:编译时变量覆盖
这是最常用的主题定制方式,适用于项目初始化时确定主题风格的场景。在项目根目录下的uni.scss文件中,定义SCSS变量来覆盖默认值:
示例
uni.scss
$un-color-primary: #FF6B81; // 珊瑚红
$un-color-primary-light: #FFCDD2; // 浅主色
$un-color-primary-lighter: #FFE6E8; // 更浅主色
$un-color-primary-dark: #D84315; // 暗主色
$un-color-primary-disabled: #FFB3B8; // 禁用状态主色
// 自定义成功色
$un-color-success: #00B96B; // 基础成功色
$un-color-success-light: #C6F0DC; // 亮成功色
$un-color-success-lighter: #E0F8EC; // 更亮成功色
$un-color-success-dark: #009A5A; // 暗成功色
// 自定义警告色
$un-color-warning: #FF9C2A; // 基础警告色
$un-color-warning-light: #FFE8CC; // 亮警告色
$un-color-warning-lighter: #FFF2E6; // 更亮警告色
$un-color-warning-dark: #E68517; // 暗警告色
// 自定义错误色
$un-color-error: #FF4D4F; // 基础错误色
$un-color-error-light: #FFD9D9; // 亮错误色
$un-color-error-lighter: #FFEBEB; // 更亮错误色
$un-color-error-dark: #D9363E; // 暗错误色
// 自定义文本颜色
$un-text-color: #333333; // 主要文本颜色
$un-text-color-secondary: #666666; // 次要文本颜色
$un-text-color-muted: #999999; // 辅助文本颜色
$un-text-color-placeholder: #BBBBBB; // 输入框占位符颜色
$un-text-color-disabled: #CCCCCC; // 禁用状态文本颜色
$un-text-color-white: #FFFFFF; // 白色文本颜色
$un-text-color-active: #FF6B81; // 激活状态文本颜色
// 自定义背景颜色
$un-bg-color: #F5F5F5; // 基础背景色
$un-bg-color-light: #F9F9F9; // 亮色背景色
$un-bg-color-lighter: #FFFFFF; // 更亮背景色
$un-bg-color-container: #FFFFFF; // 容器背景色
$un-bg-color-page: #FFFFFF; // 页面背景色
$un-bg-color-hover: #F0F0F0; // 悬停状态背景色
$un-bg-color-active: #E8E8E8; // 激活状态背景色
$un-bg-color-disabled: #FAFAFA; // 禁用状态背景色
$un-bg-color-overlay: rgba(0, 0, 0, 0.6); // 遮罩层背景色
// 自定义边框颜色
$un-border-color: #E0E0E0; // 基础边框颜色
$un-border-color-light: #F0F0F0; // 亮色边框颜色
$un-border-color-lighter: #F5F5F5; // 更亮边框颜色
$un-border-color-hover: #FF6B81; // 悬停状态边框颜色
$un-border-color-disabled: #F5F5F5; // 禁用状态边框颜色
// 自定义圆角大小
$un-radius-xs: 2px; // 最小圆角
$un-radius-sm: 4px; // 小圆角
$un-radius-base: 8px; // 基础圆角
$un-radius-lg: 12px; // 大圆角
$un-radius-xl: 16px; // 超大圆角
$un-radius-circle: 9999px; // 圆形
// 自定义字号
$un-text-xs: 11px; // 超小文本
$un-text-sm: 13px; // 小文本
$un-text-base: 16px; // 基础文本
$un-text-lg: 18px; // 大文本
$un-text-xl: 20px; // 超大文本
// 自定义行高
$un-line-xs: 18px; // 配合11px字号
$un-line-sm: 20px; // 配合13px字号
$un-line-base: 24px; // 配合16px字号
$un-line-lg: 28px; // 配合18px字号
$un-line-xl: 30px; // 配合20px字号
// 自定义字重
$un-font-normal: 400; // 常规字重
$un-font-medium: 500; // 中等字重
$un-font-bold: 700; // 粗体字重方法二:运行时动态修改
这种方式适用于需要在应用运行过程中切换主题的场景,如实现深色模式/浅色模式切换。您可以直接在根节点样式中覆盖这些 CSS 变量,组件的样式会随之自动更新
:root, page {
/* 主题色 */
--un-color-primary: #1677FF; /* 基础主色 */
--un-color-primary-light: #D4E7FF; /* 亮主色 */
--un-color-primary-lighter: #E6F0FF; /* 更亮主色 */
--un-color-primary-dark: #0E5CD6; /* 暗主色 */
--un-color-primary-disabled: #B3D9FF; /* 禁用状态主色 */
/* 成功色 */
--un-color-success: #00B96B; /* 基础成功色 */
--un-color-success-light: #C6F0DC; /* 亮成功色 */
--un-color-success-lighter: #E0F8EC; /* 更亮成功色 */
--un-color-success-dark: #009A5A; /* 暗成功色 */
--un-color-success-disabled: #99E6C6; /* 禁用状态成功色 */
/* 警告色 */
--un-color-warning: #FF9C2A; /* 基础警告色 */
--un-color-warning-light: #FFE8CC; /* 亮警告色 */
--un-color-warning-lighter: #FFF2E6; /* 更亮警告色 */
--un-color-warning-dark: #E68517; /* 暗警告色 */
--un-color-warning-disabled: #FFD699; /* 禁用状态警告色 */
/* 错误色 */
--un-color-error: #FF4D4F; /* 基础错误色 */
--un-color-error-light: #FFD9D9; /* 亮错误色 */
--un-color-error-lighter: #FFEBEB; /* 更亮错误色 */
--un-color-error-dark: #D9363E; /* 暗错误色 */
--un-color-error-disabled: #FFB8B8; /* 禁用状态错误色 */
/* 信息色 */
--un-color-info: #8C8C8C; /* 基础信息色 */
--un-color-info-light: #E8E8E8; /* 亮信息色 */
--un-color-info-lighter: #F0F0F0; /* 更亮信息色 */
--un-color-info-dark: #595959; /* 暗信息色 */
--un-color-info-disabled: #D9D9D9; /* 禁用状态信息色 */
/* 文本颜色 */
--un-text-color: #1F1F1F; /* 基础文本颜色 */
--un-text-color-secondary: #5C5C5C; /* 次要文本颜色 */
--un-text-color-muted: #8C8C8C; /* 辅助文本颜色 */
--un-text-color-placeholder: #BFBFBF; /* 输入框占位符颜色 */
--un-text-color-disabled: #D9D9D9; /* 禁用状态文本颜色 */
--un-text-color-white: #FFFFFF; /* 白色文本颜色 */
--un-text-color-active: #1677FF; /* 激活状态文本颜色 */
/* 背景颜色 */
--un-bg-color: #E8E8E8; /* 基础背景色 */
--un-bg-color-light: #F0F0F0; /* 中等背景色 */
--un-bg-color-lighter: #F5F5F5; /* 更亮背景色 */
--un-bg-color-container: #FFFFFF; /* 容器背景色 */
--un-bg-color-page: #FFFFFF; /* 页面背景色 */
--un-bg-color-hover: #EBEBEB; /* 悬停状态背景色 */
--un-bg-color-active: #E0E0E0; /* 激活状态背景色 */
--un-bg-color-disabled: #F8F8F8; /* 禁用状态背景色 */
--un-bg-color-overlay: rgba(0, 0, 0, 0.75); /* 遮罩层背景色 */
/* 边框颜色 */
--un-border-color: #E0E0E0; /* 基础边框颜色 */
--un-border-color-light: #F0F0F0; /* 中等边框颜色 */
--un-border-color-lighter: #F5F5F5; /* 更亮边框颜色 */
--un-border-color-hover: #1677FF; /* 悬停状态边框颜色 */
--un-border-color-disabled: #F5F5F5; /* 禁用状态边框颜色 */
/* 圆角大小 */
--un-radius-xs: 2px; /* 最小圆角 */
--un-radius-sm: 4px; /* 小圆角 */
--un-radius-base: 6px; /* 基础圆角 */
--un-radius-lg: 8px; /* 大圆角 */
--un-radius-xl: 12px; /* 超大圆角 */
--un-radius-circle: 100px; /* 圆形 */
/* 字号 */
--un-text-xs: 11px; /* 超小文本 */
--un-text-sm: 13px; /* 小文本 */
--un-text-base: 15px; /* 基础文本 */
--un-text-lg: 17px; /* 大文本 */
--un-text-xl: 19px; /* 超大文本 */
/* 行高 */
--un-line-xs: 18px; /* 配合11px字号 */
--un-line-sm: 20px; /* 配合13px字号 */
--un-line-base: 24px; /* 配合15px字号 */
--un-line-lg: 26px; /* 配合17px字号 */
--un-line-xl: 28px; /* 配合19px字号 */
/* 字重 */
--un-font-normal: 400; /* 常规文本 */
--un-font-medium: 500; /* 标题、强调文本 */
--un-font-bold: 700; /* 突出强调 */
}方法三:通过 un-page 组件覆盖
您可以在 un-page 组件中直接覆盖主题变量,可用配合后端接口动态切换主题。
示例
<template>
<un-page :themeVars="themeVars">
<view>
<un-button type="primary">Primary Button</un-button>
<text>Hello uView-unix</text>
</view>
</un-page>
</template>
<script setup lang="uts">
import { ref } from 'vue'
// themeVars的值会自动转换成对应的CSS变量
// 比如 colorPrimary 会转换成 `--un-color-primary`
// 比如 colorPrimaryLight 会转换成 `--un-color-primary-light`
const themeVars = ref({
colorPrimary: '#fd2e0e',
colorPrimaryLight: '#8db4e9',
colorPrimaryDark: '#d84315',
})
</script>组件SCSS变量用法
基本用法
uView-unix的每个组件都提供了独立的SCSS变量,您可以通过覆盖这些变量来定制组件的样式。
在项目的uni.scss文件中覆盖组件变量,会影响所有使用该组件的地方:
uni.scss
// 覆盖按钮组件变量
$un-button-height: 30px;
$un-button-padding: 6px;
// 覆盖输入框组件变量
$un-input-height: 45px !default;
$un-input-border-color: #e0e0e0 !default;最佳实践
保持变量一致性:在覆盖变量时,确保相关变量(如颜色的深浅变体)一起更新,保持视觉协调
使用设计工具辅助:利用Figma、Sketch等设计工具提取颜色值,确保主题与设计稿一致
主题预定义:在项目初期就定义好主题变量,避免后期大量修改
主题切换优化:实现深色模式时,建议预加载两种主题的CSS变量,以避免切换时的闪烁
性能考虑:对于频繁切换主题的场景,使用CSS变量方式比重新编译SCSS更高效
变量命名规范:遵循uView的命名规范,使用有意义的变量名,便于维护
组件变量优先级:组件变量 > 全局变量,局部覆盖 > 全局覆盖
!default 标志:所有组件变量都带有
!default标志,确保您可以安全地覆盖它们
通过以上方法和实践,您可以灵活地定制uView-unix的主题,打造符合品牌特色的应用界面。
