uView Next
4.0.105

外观

自定义主题

约 2434 字大约 8 分钟

2025-10-31

uView-unix 提供了强大的主题定制功能，通过简单的变量覆盖，您可以轻松定制应用的整体视觉风格，实现品牌的统一化设计。

主题系统特点

  1. 基于 SCSS 和 CSS 变量双重支持：结合了 SCSS 的编译时变量和 CSS 变量的运行时可变性
  2. 灵活的变量覆盖机制：支持全局变量覆盖和组件级别的样式定制
  3. 完善的变量体系：包含行高、圆角、字号、颜色等全方位的设计变量
  4. 默认值 fallback 机制：即使未定义某些变量，也能保证系统正常运行

工作原理

这种定义方式遵循以下优先级规则：

  1. 最高优先级：CSS变量 (--un-color-primary) - 运行时可动态修改
  2. 中等优先级：自定义SCSS变量 ($un-color-primary) - 通过覆盖文件定义
  3. 最低优先级：默认值 (#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;

最佳实践

  1. 保持变量一致性：在覆盖变量时，确保相关变量（如颜色的深浅变体）一起更新，保持视觉协调

  2. 使用设计工具辅助：利用Figma、Sketch等设计工具提取颜色值，确保主题与设计稿一致

  3. 主题预定义：在项目初期就定义好主题变量，避免后期大量修改

  4. 主题切换优化：实现深色模式时，建议预加载两种主题的CSS变量，以避免切换时的闪烁

  5. 性能考虑：对于频繁切换主题的场景，使用CSS变量方式比重新编译SCSS更高效

  6. 变量命名规范：遵循uView的命名规范，使用有意义的变量名，便于维护

  7. 组件变量优先级：组件变量 > 全局变量，局部覆盖 > 全局覆盖

  8. !default 标志：所有组件变量都带有!default标志，确保您可以安全地覆盖它们

通过以上方法和实践，您可以灵活地定制uView-unix的主题，打造符合品牌特色的应用界面。

Copyright © 2026 uView Next