介紹

用于全局配置 Vant 組件，提供深色模式、主題定制等能力。

引入

通過(guò)以下方式來(lái)全局注冊(cè)組件，更多注冊(cè)方式請(qǐng)參考組件注冊(cè)。

import { createApp } from 'vue';
import { ConfigProvider } from 'vant';

const app = createApp();
app.use(ConfigProvider);

深色模式

開啟深色模式

將 ConfigProvider 組件的 ?theme? 屬性設(shè)置為 ?dark?，可以開啟深色模式。

深色模式會(huì)全局生效，使頁(yè)面上的所有 Vant 組件變?yōu)樯钌L(fēng)格。

<van-config-provider theme="dark">...</van-config-provider>

值得注意的是，開啟 Vant 的深色模式只會(huì)影響 Vant 組件的 UI，并不會(huì)影響全局的文字顏色或背景顏色，你可以參考以下 CSS 來(lái)設(shè)置一些全局樣式：

.van-theme-dark body {
  text-color: #f5f5f5;
  background-color: black;
}

動(dòng)態(tài)切換

通過(guò)動(dòng)態(tài)設(shè)置 ?theme? 屬性，可以在淺色風(fēng)格和深色風(fēng)格之間進(jìn)行切換。

<van-config-provider :theme="theme">...</van-config-provider>

export default {
  setup() {
    const theme = ref('light');

    setTimeout(() => {
      theme.value = 'dark';
    }, 1000);

    return { theme };
  },
};

定制主題

介紹

Vant 組件通過(guò)豐富的 CSS 變量 來(lái)組織樣式，通過(guò)覆蓋這些 CSS 變量，可以實(shí)現(xiàn)定制主題、動(dòng)態(tài)切換主題等效果。

示例

以 Button 組件為例，查看組件的樣式，可以看到 ?.van-button--primary? 類名上存在以下變量：

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

這些變量的默認(rèn)值被定義在 ?:root? 節(jié)點(diǎn)上，HTML 里的所有子節(jié)點(diǎn)都可以訪問(wèn)到這些變量：

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

自定義 CSS 變量

通過(guò) CSS 覆蓋

你可以直接在代碼中覆蓋這些 CSS 變量，Button 組件的樣式會(huì)隨之發(fā)生改變：

/* 添加這段樣式后，Primary Button 會(huì)變成紅色 */
:root {
  --van-button-primary-background: red;
}

通過(guò) ConfigProvider 覆蓋

?ConfigProvider? 組件提供了覆蓋 CSS 變量的能力，你需要在根節(jié)點(diǎn)包裹一個(gè) ?ConfigProvider? 組件，并通過(guò) ?theme-vars? 屬性來(lái)配置一些主題變量。

<van-config-provider :theme-vars="themeVars">
  <van-form>
    <van-field name="rate" label="評(píng)分">
      <template #input>
        <van-rate v-model="rate" />
      </template>
    </van-field>
    <van-field name="slider" label="滑塊">
      <template #input>
        <van-slider v-model="slider" />
      </template>
    </van-field>
    <div style="margin: 16px">
      <van-button round block type="primary" native-type="submit">
        提交
      </van-button>
    </div>
  </van-form>
</van-config-provider>

import { ref } from 'vue';

export default {
  setup() {
    const rate = ref(4);
    const slider = ref(50);

    // themeVars 內(nèi)的值會(huì)被轉(zhuǎn)換成對(duì)應(yīng) CSS 變量
    // 比如 sliderBarHeight 會(huì)轉(zhuǎn)換成 `--van-slider-bar-height`
    const themeVars = {
      rateIconFullColor: '#07c160',
      sliderBarHeight: '4px',
      sliderButtonWidth: '20px',
      sliderButtonHeight: '20px',
      sliderActiveBackground: '#07c160',
      buttonPrimaryBackground: '#07c160',
      buttonPrimaryBorderColor: '#07c160',
    };

    return {
      rate,
      slider,
      themeVars,
    };
  },
};

注意：ConfigProvider 僅影響它的子組件的樣式，不影響全局 root 節(jié)點(diǎn)。

在 TypeScript 中使用

在 TypeScript 中定義 themeVars 時(shí)，建議使用 Vant 提供的 ?ConfigProviderThemeVars? 類型，可以提供完善的類型提示：

import type { ConfigProviderThemeVars } from 'vant';

const themeVars: ConfigProviderThemeVars = {
  sliderBarHeight: '4px',
};

結(jié)合深色模式與 CSS 變量

如果需要單獨(dú)定義深色模式或淺色模式下的 CSS 變量，可以使用 ?theme-vars-dark? 和 ?theme-vars-light? 屬性。

• ?theme-vars-dark?: 僅在深色模式下生效的 CSS 變量，優(yōu)先級(jí)高于 ?theme-vars? 中定義的變量。
• ?theme-vars-light?: 僅在淺色模式下生效的 CSS 變量，優(yōu)先級(jí)高于 ?theme-vars? 中定義的變量。

示例

以下方的 ?buttonPrimaryBackground? 變量為例, 在深色模式下的值為 ?blue?，在淺色模式下的值為 ?green?。

<van-config-provider
  :theme-vars="themeVars"
  :theme-vars-dark="themeVarsDark"
  :theme-vars-light="themeVarsLight"
>
  ...
</van-config-provider>

import { ref } from 'vue';

export default {
  setup() {
    const themeVars = { buttonPrimaryBackground: 'red' };
    const themeVarsDark = { buttonPrimaryBackground: 'blue' };
    const themeVarsLight = { buttonPrimaryBackground: 'green' };

    return {
      themeVars,
      themeVarsDark,
      themeVarsLight,
    };
  },
};

主題變量

基礎(chǔ)變量

Vant 中的 CSS 變量分為 基礎(chǔ)變量 和 組件變量。組件變量會(huì)繼承基礎(chǔ)變量，因此在修改基礎(chǔ)變量后，會(huì)影響所有相關(guān)的組件。

修改變量

由于 CSS 變量繼承機(jī)制的原因，兩者的修改方式有一定差異：

• 基礎(chǔ)變量只能通過(guò) ?:root 選擇器? 修改，不能通過(guò) ?ConfigProvider 組件? 修改。
• 組件變量可以通過(guò) ?:root 選擇器? 和 ?ConfigProvider 組件? 修改。

你也可以使用 ?.van-theme-light? 和 ?.van-theme-dark? 這兩個(gè)類名選擇器來(lái)單獨(dú)修改淺色或深色模式下的基礎(chǔ)變量和組件變量。

變量列表

下面是所有的基礎(chǔ)變量：

// 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-link-color: #576b95;
--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;

你可以在各個(gè)組件文檔底部的表格中查看組件變量。

API

Props

類型定義

組件導(dǎo)出以下類型定義：

import type {
  ConfigProviderProps,
  ConfigProviderTheme,
  ConfigProviderThemeVars,
} from 'vant';