ConfigProvider 全局配置 - Vant 4

ConfigProvider 全局配置

⚙️ 介绍

ConfigProvider 就像是 Vant 组件库的"魔法调色盘"！🎨 它是整个应用的视觉风格指挥官，拥有着神奇的变身能力。无论你想要优雅的深色夜间模式，还是个性十足的彩虹主题，ConfigProvider 都能轻松满足你的需求。

想象一下，只需要轻轻一挥魔法棒，整个应用就能瞬间换装！从清新的白天模式切换到护眼的深色模式，从默认的蓝色主题变身为活力四射的橙色风格，ConfigProvider 让主题定制变得如此简单而有趣。它不仅是一个配置工具，更是你打造独特用户体验的得力助手！

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { ConfigProvider } from'vant'; const app = createApp(); app.use(ConfigProvider);

🌙 深色模式

🌙 开启深色模式 - 夜猫子的福音

将 ConfigProvider 组件的 theme 属性设置为 dark，就像给你的应用戴上了一副时尚的墨镜！😎

深色模式就像是应用的"夜间守护者"，它会温柔地将所有 Vant 组件包裹在柔和的深色调中。无论是深夜加班的程序员，还是喜欢在暗光环境下使用手机的用户，都能享受到这种护眼又酷炫的视觉体验。一键开启，整个世界瞬间变得优雅而神秘！

html

值得注意的是，开启 Vant 的深色模式只会影响 Vant 组件的 UI，并不会影响全局的文字颜色或背景颜色，你可以参考以下 CSS 来设置一些全局样式：

css

.van-theme-darkbody { color: #f5f5f5; background-color: black; }

🔄 动态切换 - 变色龙般的灵活

通过动态设置 theme 属性，你的应用就拥有了变色龙般的超能力！🦎 可以在阳光明媚的浅色风格和星空璀璨的深色风格之间自由穿梭。

就像魔法师挥舞魔法棒一样，用户可以根据当前环境、心情或时间来选择最适合的主题。白天工作时选择清爽的浅色模式提升专注度，夜晚休闲时切换到温柔的深色模式保护视力。这种贴心的设计让用户体验更加人性化！

html

exportdefault { setup() { const theme = ref('light'); setTimeout(() => { theme.value = 'dark'; }, 1000); return { theme }; }, };

🎨 定制主题 - 你的专属调色板

🌈 介绍 - 解锁无限创意可能

Vant 组件就像一座精心设计的"乐高积木城堡"，每个组件都通过丰富的 CSS 变量来构建其视觉外观。这些 CSS 变量就像是城堡的"魔法宝石"，只要替换不同颜色的宝石，整座城堡就能焕然一新！

通过巧妙地覆盖这些 CSS 变量，你可以轻松实现个性化主题定制、实时动态切换主题等令人惊艳的效果。无论是企业品牌色、节日主题色，还是用户个人喜好色，都能完美呈现！

示例

以 Button 组件为例，查看组件的样式，可以看到 .van-button--primary 类名上存在以下变量：

css

.van-button--primary { color: var(--van-button-primary-color); background-color: var(--van-button-primary-background); }

这些变量的默认值被定义在 :root 节点上，HTML 里的所有子节点都可以访问到这些变量：

css

:root { --van-white: #fff; --van-blue: #1989fa; --van-button-primary-color: var(--van-white); --van-button-primary-background: var(--van-primary-color); }

自定义 CSS 变量

通过 CSS 覆盖

你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：

css

/* 添加这段样式后，Primary Button 会变成红色 */:root:root { --van-button-primary-background: red; }

注意：为什么要写两个重复的 :root？
由于 vant 中的主题变量也是在 :root 下声明的，所以在有些情况下会由于优先级的问题无法成功覆盖。通过 :root:root 可以显式地让你所写内容的优先级更高一些，从而确保主题变量的成功覆盖。

通过 ConfigProvider 覆盖

ConfigProvider 组件提供了覆盖 CSS 变量的能力，你需要在根节点包裹一个 ConfigProvider 组件，并通过 theme-vars 属性来配置一些主题变量。

html

import { ref, reactive } from'vue'; exportdefault { setup() { const rate = ref(4); const slider = ref(50); // themeVars 内的值会被转换成对应 CSS 变量// 比如 sliderBarHeight 会转换成 `--van-slider-bar-height`const themeVars = reactive({ rateIconFullColor: '#07c160', sliderBarHeight: '4px', sliderButtonWidth: '20px', sliderButtonHeight: '20px', sliderActiveBackground: '#07c160', buttonPrimaryBackground: '#07c160', buttonPrimaryBorderColor: '#07c160', }); return { rate, slider, themeVars, }; }, };

CSS 变量生效范围

默认情况下，themeVars 产生的 CSS 变量是设置在组件根节点上的，因此只会影响它的子组件的样式，不会影响整个页面。

你可以通过 theme-vars-scope 属性来修改 CSS 变量的生效范围。比如将 theme-vars-scope 设置为 global，此时 themeVars 产生的 CSS 变量会设置到 HTML 的根节点，并对整个页面内的所有组件生效。

html

在 TypeScript 中使用

在 TypeScript 中定义 themeVars 时，建议使用 Vant 提供的 ConfigProviderThemeVars 类型，可以提供完善的类型提示：

importtype { ConfigProviderThemeVars } from'vant'; constthemeVars: ConfigProviderThemeVars = { sliderBarHeight: '4px', };

结合深色模式与 CSS 变量

如果需要单独定义深色模式或浅色模式下的 CSS 变量，可以使用 theme-vars-dark 和 theme-vars-light 属性。

theme-vars-dark: 仅在深色模式下生效的 CSS 变量，优先级高于 theme-vars 中定义的变量。
theme-vars-light: 仅在浅色模式下生效的 CSS 变量，优先级高于 theme-vars 中定义的变量。

示例

以下方的 buttonPrimaryBackground 变量为例, 在深色模式下的值为 blue，在浅色模式下的值为 green。

html

import { ref, reactive } from'vue'; exportdefault { setup() { const themeVars = reactive({ buttonPrimaryBackground: 'red' }); const themeVarsDark = reactive({ buttonPrimaryBackground: 'blue' }); const themeVarsLight = reactive({ buttonPrimaryBackground: 'green' }); return { themeVars, themeVarsDark, themeVarsLight, }; }, };

使用类名

此外，你也可以使用 .van-theme-light 和 .van-theme-dark 这两个类名选择器来单独修改浅色或深色模式下的基础变量和组件变量。

css

.van-theme-light { --van-white: white; } .van-theme-dark { --van-white: black; }

主题变量

变量类型

Vant 中的 CSS 变量分为 基础变量 和 组件变量。组件变量会继承基础变量，因此在修改基础变量后，会影响所有相关的组件。

修改变量

CSS 变量存在继承关系，组件变量会寻找最近的父级基础变量进行继承。

因此修改基础变量存在一定限制，你需要使用 :root 选择器或 ConfigProvider 组件的 global 模式来修改基础变量。否则，组件变量可能会无法正确继承基础变量。

以 --van-primary-color 这个基础变量为例：

可以通过 :root 选择器修改：

css

:root { --van-primary-color: red; }

可以通过 ConfigProvider 组件的 global 模式修改：

html

不可以通过 ConfigProvider 组件默认的 local 模式修改：

html

对于组件变量，则没有上述限制，可以通过任意方式修改。

基础变量列表

下面是所有的基础变量：

less

// Color Palette--van-black: #000; --van-white: #fff; --van-gray-1: #f7f8fa; --van-gray-2: #f2f3f5; --van-gray-3: #ebedf0; --van-gray-4: #dcdee0; --van-gray-5: #c8c9cc; --van-gray-6: #969799; --van-gray-7: #646566; --van-gray-8: #323233; --van-red: #ee0a24; --van-blue: #1989fa; --van-orange: #ff976a; --van-orange-dark: #ed6a0c; --van-orange-light: #fffbe8; --van-green: #07c160; // Gradient Colors--van-gradient-red: linear-gradient(to right, #ff6034, #ee0a24); --van-gradient-orange: linear-gradient(to right, #ffd01e, #ff8917); // Component Colors--van-primary-color: var(--van-blue); --van-success-color: var(--van-green); --van-danger-color: var(--van-red); --van-warning-color: var(--van-orange); --van-text-color: var(--van-gray-8); --van-text-color-2: var(--van-gray-6); --van-text-color-3: var(--van-gray-5); --van-active-color: var(--van-gray-2); --van-active-opacity: 0.6; --van-disabled-opacity: 0.5; --van-background: var(--van-gray-1); --van-background-2: var(--van-white); // Padding--van-padding-base: 4px; --van-padding-xs: 8px; --van-padding-sm: 12px; --van-padding-md: 16px; --van-padding-lg: 24px; --van-padding-xl: 32px; // Font--van-font-size-xs: 10px; --van-font-size-sm: 12px; --van-font-size-md: 14px; --van-font-size-lg: 16px; --van-font-bold: 600; --van-line-height-xs: 14px; --van-line-height-sm: 18px; --van-line-height-md: 20px; --van-line-height-lg: 22px; --van-base-font: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei', sans-serif; --van-price-font: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial, sans-serif; // Animation--van-duration-base: 0.3s; --van-duration-fast: 0.2s; --van-ease-out: ease-out; --van-ease-in: ease-in; // Border--van-border-color: var(--van-gray-3); --van-border-width: 1px; --van-radius-sm: 2px; --van-radius-md: 4px; --van-radius-lg: 8px; --van-radius-max: 999px;

你可以在各个组件文档底部的表格中查看组件变量。

API

Props

参数	说明	类型	默认值
theme	主题风格，设置为 `dark` 来开启深色模式，全局生效	ConfigProviderTheme	`light`
theme-vars	自定义主题变量，局部生效	object	-
theme-vars-dark	仅在深色模式下生效的主题变量，优先级高于 `theme-vars`	object	-
theme-vars-light	仅在浅色模式下生效的主题变量，优先级高于 `theme-vars`	object	-
theme-vars-scope	默认仅影响子组件的样式，设置为 `global` 整个页面生效	ConfigProviderThemeVarsScope	`local`
tag	根节点对应的 HTML 标签名	string	`div`
z-index	设置所有弹窗类组件的 z-index，该属性对全局生效	number	`2000`
icon-prefix	所有图标的类名前缀，等同于 Icon 组件的 class-prefix 属性	string	`van-icon`

类型定义

组件导出以下类型定义：

importtype { ConfigProviderProps, ConfigProviderTheme, ConfigProviderThemeVars, ConfigProviderThemeVarsScope, } from'vant';

🎯 最佳实践

🎨 主题设计原则

保持一致性 - 确保整个应用的主题风格统一协调
考虑可访问性 - 选择对比度足够的颜色组合，确保文字清晰可读
响应用户偏好 - 支持系统主题跟随，提供手动切换选项
性能优化 - 避免频繁切换主题，合理使用缓存机制

🔧 主题变量管理技巧

javascript

// 推荐：集中管理主题变量
const lightTheme = {
  primaryColor: '#1989fa',
  successColor: '#07c160',
  warningColor: '#ff976a',
  dangerColor: '#ee0a24'
}

const darkTheme = {
  primaryColor: '#3291ff',
  successColor: '#4fc08d',
  warningColor: '#fcbd71',
  dangerColor: '#f56c6c'
}

// 动态切换主题
const currentTheme = computed(() => 
  isDark.value ? darkTheme : lightTheme
)

📱 响应式主题适配

css

/* 跟随系统主题 */
@media (prefers-color-scheme: dark) {
  :root {
    --van-primary-color: #3291ff;
    --van-background: #1a1a1a;
  }
}

/* 移动端适配 */
@media (max-width: 768px) {
  :root {
    --van-font-size-md: 16px;
    --van-padding-md: 20px;
  }
}

❓ 常见问题解决

🔍 主题变量不生效？

问题：设置了主题变量但样式没有改变 解决方案：

检查 CSS 变量名是否正确（注意 --van- 前缀）
确认变量作用域设置（local vs global）
使用 :root:root 提高优先级

🌙 深色模式闪烁问题

问题：切换深色模式时出现白屏闪烁 解决方案：

css

/* 预设深色背景避免闪烁 */
html {
  background-color: #1a1a1a;
  color-scheme: dark light;
}

🎨 自定义主题色不统一

问题：部分组件没有应用自定义主题色 解决方案：

使用基础变量而非组件变量
检查组件是否支持该主题变量
考虑使用 CSS 类名覆盖

💡 高级用法示例

🌈 多主题切换系统

vue

<template>
  <ConfigProvider :theme-vars="currentThemeVars">
    <div class="theme-selector">
      <button 
        v-for="theme in themes" 
        :key="theme.name"
        @click="switchTheme(theme)"
        :class="{ active: currentTheme === theme.name }"
      >
        {{ theme.label }}
      </button>
    </div>
    <YourApp />
  </ConfigProvider>
</template>

<script setup>
const themes = [
  { name: 'default', label: '默认蓝', vars: { primaryColor: '#1989fa' } },
  { name: 'green', label: '清新绿', vars: { primaryColor: '#07c160' } },
  { name: 'orange', label: '活力橙', vars: { primaryColor: '#ff976a' } },
  { name: 'purple', label: '神秘紫', vars: { primaryColor: '#7232dd' } }
]

const currentTheme = ref('default')
const currentThemeVars = computed(() => 
  themes.find(t => t.name === currentTheme.value)?.vars || {}
)

const switchTheme = (theme) => {
  currentTheme.value = theme.name
  // 可选：保存用户偏好
  localStorage.setItem('preferred-theme', theme.name)
}
</script>

🎭 节日主题自动切换

javascript

// 根据日期自动应用节日主题
const getSeasonalTheme = () => {
  const now = new Date()
  const month = now.getMonth() + 1
  const day = now.getDate()
  
  // 春节主题
  if (month === 1 || month === 2) {
    return { primaryColor: '#ff4757', successColor: '#ffa502' }
  }
  // 圣诞主题
  if (month === 12) {
    return { primaryColor: '#2ed573', dangerColor: '#ff4757' }
  }
  // 默认主题
  return {}
}

🎨 设计灵感

🌟 热门主题配色方案

科技蓝 - 专业、可信赖

css

--van-primary-color: #0066cc;
--van-success-color: #00cc66;

温暖橙 - 友好、活力

css

--van-primary-color: #ff6b35;
--van-warning-color: #ffa726;

优雅紫 - 创意、高端

css

--van-primary-color: #6c5ce7;
--van-success-color: #00b894;

🎯 行业主题建议

金融类应用：稳重蓝色 + 安全绿色
电商类应用：活力橙色 + 促销红色
教育类应用：知识蓝色 + 成长绿色
医疗类应用：医疗蓝色 + 健康绿色

📚 相关文档

Icon 图标 - 了解图标组件的使用方法
Style 内置样式 - 查看 Vant 的内置样式变量
进阶用法 - 学习更多组件注册方式
快速上手 - 从零开始使用 Vant

🔗 延伸阅读

CSS 自定义属性 (变量) - MDN 官方文档
深色模式设计指南 - Apple 设计规范
Material Design 主题系统 - Google 设计规范
无障碍设计色彩对比度 - 在线对比度检测工具

ConfigProvider 全局配置 ​

⚙️ 介绍 ​

📦 引入 ​

🌙 深色模式 ​

🌙 开启深色模式 - 夜猫子的福音 ​

🔄 动态切换 - 变色龙般的灵活 ​

🎨 定制主题 - 你的专属调色板 ​

🌈 介绍 - 解锁无限创意可能 ​

示例 ​

自定义 CSS 变量 ​

通过 CSS 覆盖 ​

通过 ConfigProvider 覆盖 ​

CSS 变量生效范围 ​

在 TypeScript 中使用 ​

结合深色模式与 CSS 变量 ​

示例 ​

使用类名 ​

主题变量 ​

变量类型 ​

修改变量 ​

基础变量列表 ​

API ​

Props ​

类型定义 ​

🎯 最佳实践 ​

🎨 主题设计原则 ​

🔧 主题变量管理技巧 ​

📱 响应式主题适配 ​

❓ 常见问题解决 ​

🔍 主题变量不生效？ ​

🌙 深色模式闪烁问题 ​

🎨 自定义主题色不统一 ​

💡 高级用法示例 ​

🌈 多主题切换系统 ​

🎭 节日主题自动切换 ​

🎨 设计灵感 ​

🌟 热门主题配色方案 ​

🎯 行业主题建议 ​

📚 相关文档 ​

🔗 延伸阅读 ​

ConfigProvider 全局配置

⚙️ 介绍

📦 引入

🌙 深色模式

🌙 开启深色模式 - 夜猫子的福音

🔄 动态切换 - 变色龙般的灵活

🎨 定制主题 - 你的专属调色板

🌈 介绍 - 解锁无限创意可能

示例

自定义 CSS 变量

通过 CSS 覆盖

通过 ConfigProvider 覆盖

CSS 变量生效范围

在 TypeScript 中使用

结合深色模式与 CSS 变量

示例

使用类名

主题变量

变量类型

修改变量

基础变量列表

API

Props

类型定义

🎯 最佳实践

🎨 主题设计原则

🔧 主题变量管理技巧

📱 响应式主题适配

❓ 常见问题解决

🔍 主题变量不生效？

🌙 深色模式闪烁问题

🎨 自定义主题色不统一

💡 高级用法示例

🌈 多主题切换系统

🎭 节日主题自动切换

🎨 设计灵感

🌟 热门主题配色方案

🎯 行业主题建议

📚 相关文档

🔗 延伸阅读