ConfigProvider 全局配置

介绍

用于配置 Vant 组件的主题样式和全局属性,从 3.1.0 版本开始支持。

引入

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

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

定制主题

介绍

Vant 组件通过丰富的 CSS 变量 来组织样式,通过覆盖这些 CSS 变量,可以实现定制主题、动态切换主题等效果。

示例

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

  1. .van-button--primary {
  2. color: var(--van-button-primary-color);
  3. background-color: var(--van-button-primary-background-color);
  4. }

这些变量的默认值被定义在 root 节点上,HTML 文档的任何节点都可以访问到这些变量:

  1. :root {
  2. --van-white: #fff;
  3. --van-blue: #1989fa;
  4. --van-button-primary-color: var(--van-white);
  5. --van-button-primary-background-color: var(--van-primary-color);
  6. }

自定义 CSS 变量

通过 CSS 覆盖

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

  1. /* 添加这段样式后,Primary Button 会变成红色 */
  2. :root {
  3. --van-button-primary-background-color: red;
  4. }

通过 ConfigProvider 覆盖

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

  1. <van-config-provider :theme-vars="themeVars">
  2. <van-form>
  3. <van-field name="rate" label="评分">
  4. <template #input>
  5. <van-rate v-model="rate" />
  6. </template>
  7. </van-field>
  8. <van-field name="slider" label="滑块">
  9. <template #input>
  10. <van-slider v-model="slider" />
  11. </template>
  12. </van-field>
  13. <div style="margin: 16px">
  14. <van-button round block type="primary" native-type="submit">
  15. 提交
  16. </van-button>
  17. </div>
  18. </van-form>
  19. </van-config-provider>
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const rate = ref(4);
  5. const slider = ref(50);
  6. // themeVars 内的值会被转换成对应 CSS 变量
  7. // 比如 sliderBarHeight 会转换成 `--van-slider-bar-height`
  8. const themeVars = {
  9. rateIconFullColor: '#07c160',
  10. sliderBarHeight: '4px',
  11. sliderButtonWidth: '20px',
  12. sliderButtonHeight: '20px',
  13. sliderActiveBackgroundColor: '#07c160',
  14. buttonPrimaryBorderColor: '#07c160',
  15. buttonPrimaryBackgroundColor: '#07c160',
  16. };
  17. return {
  18. rate,
  19. slider,
  20. themeVars,
  21. };
  22. },
  23. };

注意:ConfigProvider 仅影响它的子组件的样式,不影响全局 root 节点。

基础变量

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

修改变量

由于 CSS 变量继承机制的原因,两者的修改方式有一定差异:

  • 基础变量只能通过 root 选择器 修改,不能通过 ConfigProvider 组件 修改。
  • 组件变量可以通过 root 选择器ConfigProvider 组件 修改。

变量列表

下面是所有的基础变量:

  1. // Color Palette
  2. --van-black: #000;
  3. --van-white: #fff;
  4. --van-gray-1: #f7f8fa;
  5. --van-gray-2: #f2f3f5;
  6. --van-gray-3: #ebedf0;
  7. --van-gray-4: #dcdee0;
  8. --van-gray-5: #c8c9cc;
  9. --van-gray-6: #969799;
  10. --van-gray-7: #646566;
  11. --van-gray-8: #323233;
  12. --van-red: #ee0a24;
  13. --van-blue: #1989fa;
  14. --van-orange: #ff976a;
  15. --van-orange-dark: #ed6a0c;
  16. --van-orange-light: #fffbe8;
  17. --van-green: #07c160;
  18. // Gradient Colors
  19. --van-gradient-red: linear-gradient(to right, #ff6034, #ee0a24);
  20. --van-gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);
  21. // Component Colors
  22. --van-primary-color: var(--van-blue);
  23. --van-success-color: var(--van-green);
  24. --van-danger-color: var(--van-red);
  25. --van-warning-color: var(--van-orange);
  26. --van-text-color: var(--van-gray-8);
  27. --van-text-color-2: var(--van-gray-6);
  28. --van-text-color-3: var(--van-gray-5);
  29. --van-text-link-color: #576b95;
  30. --van-active-color: var(--van-gray-2);
  31. --van-active-opacity: 0.6;
  32. --van-disabled-opacity: 0.5;
  33. --van-background-color: var(--van-gray-1);
  34. --van-background-color-light: var(--van-white);
  35. // Padding
  36. --van-padding-base: 4px;
  37. --van-padding-xs: 8px;
  38. --van-padding-sm: 12px;
  39. --van-padding-md: 16px;
  40. --van-padding-lg: 24px;
  41. --van-padding-xl: 32px;
  42. // Font
  43. --van-font-size-xs: 10px;
  44. --van-font-size-sm: 12px;
  45. --van-font-size-md: 14px;
  46. --van-font-size-lg: 16px;
  47. --van-font-weight-bold: 500;
  48. --van-line-height-xs: 14px;
  49. --van-line-height-sm: 18px;
  50. --van-line-height-md: 20px;
  51. --van-line-height-lg: 22px;
  52. --van-base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue',
  53. Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB',
  54. 'Microsoft Yahei', sans-serif;
  55. --van-price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue,
  56. Arial, sans-serif;
  57. // Animation
  58. --van-animation-duration-base: 0.3s;
  59. --van-animation-duration-fast: 0.2s;
  60. --van-animation-timing-function-enter: ease-out;
  61. --van-animation-timing-function-leave: ease-in;
  62. // Border
  63. --van-border-color: var(--van-gray-3);
  64. --van-border-width-base: 1px;
  65. --van-border-radius-sm: 2px;
  66. --van-border-radius-md: 4px;
  67. --van-border-radius-lg: 8px;
  68. --van-border-radius-max: 999px;

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

API

Props

参数说明类型默认值
theme-vars自定义主题变量object-
tag v3.1.2根节点对应的 HTML 标签名stringdiv
z-index v3.6.0设置所有弹窗类组件的 z-index,该属性对全局生效number2000
icon-prefix v3.1.3所有图标的类名前缀,等同于 Icon 组件的 class-prefix 属性stringvan-icon

类型定义

组件导出以下类型定义:

  1. import type { ConfigProviderProps } from 'vant';

ConfigProvider 全局配置 - 图1