Vant3 快速上手

通過(guò) npm 安裝

在現(xiàn)有項(xiàng)目中使用 Vant 時(shí)，可以通過(guò) ?npm ?或 ?yarn ?進(jìn)行安裝：

# Vue 2 項(xiàng)目，安裝 Vant 2：
npm i vant -S

# Vue 3 項(xiàng)目，安裝 Vant 3：
npm i vant@next -S

通過(guò) CDN 安裝

使用 Vant 最簡(jiǎn)單的方法是直接在 html 文件中引入 CDN 鏈接，之后你可以通過(guò)全局變量 ?vant ?訪問(wèn)到所有組件。

<!-- 引入樣式文件 -->
<link
  rel="stylesheet"
   rel="external nofollow" target="_blank" 
/>

<!-- 引入 Vue 和 Vant 的 JS 文件 -->
<script src="https://cdn.jsdelivr.net/npm/vue@next" rel="external nofollow" ></script>
<script src="https://cdn.jsdelivr.net/npm/vant@next/lib/vant.min.js" rel="external nofollow" ></script>

<script>
  // 在 #app 標(biāo)簽下渲染一個(gè)按鈕組件
  const app = Vue.createApp({
    template: `<van-button>按鈕</van-button>`,
  });
  app.use(vant);

  // 通過(guò) CDN 引入時(shí)不會(huì)自動(dòng)注冊(cè) Lazyload 組件
  // 可以通過(guò)下面的方式手動(dòng)注冊(cè)
  app.use(vant.Lazyload);

  // 調(diào)用函數(shù)組件，彈出一個(gè) Toast
  vant.Toast('提示');

  app.mount('#app');
</script>

你可以通過(guò)以下免費(fèi) CDN 服務(wù)來(lái)使用 Vant:

• jsdelivr
• cdnjs
• unpkg

通過(guò)腳手架安裝

在新項(xiàng)目中使用 Vant 時(shí)，推薦使用 Vue 官方提供的腳手架 Vue Cli 創(chuàng)建項(xiàng)目并安裝 Vant。

# 安裝 Vue Cli
npm install -g @vue/cli

# 創(chuàng)建一個(gè)項(xiàng)目
vue create hello-world

# 創(chuàng)建完成后，可以通過(guò)命令打開(kāi)圖形化界面，如下圖所示
vue ui

在圖形化界面中，點(diǎn)擊 依賴(lài) -> 安裝依賴(lài)，然后將 vant 添加到依賴(lài)中即可。

示例

示例工程

我們提供了豐富的示例工程，通過(guò)示例工程你可以了解如下內(nèi)容：

• 基于 Vue Cli 和 Vant 搭建應(yīng)用
• 基于 Nuxt 和 Vant 搭建應(yīng)用
• 配置按需引入組件
• 配置基于 Rem 的適配方案
• 配置基于 Viewport 的適配方案
• 配置基于 TypeScript 的工程
• 配置自定義主題色方案

引入組件

方式一. 通過(guò) babel 插件按需引入組件

babel-plugin-import 是一款 babel 插件，它會(huì)在編譯過(guò)程中將 import 語(yǔ)句自動(dòng)轉(zhuǎn)換為按需引入的方式。

# 安裝插件
npm i babel-plugin-import -D

在.babelrc 或 babel.config.js 中添加配置：

{
  "plugins": [
    [
      "import",
      {
        "libraryName": "vant",
        "libraryDirectory": "es",
        "style": true
      }
    ]
  ]
}

接著你可以在代碼中直接引入 Vant 組件，插件會(huì)自動(dòng)將代碼轉(zhuǎn)化為按需引入的形式。

// 原始代碼
import { Button } from 'vant';

// 編譯后代碼
import Button from 'vant/es/button';
import 'vant/es/button/style';

如果你在使用 TypeScript，可以使用 ts-import-plugin 實(shí)現(xiàn)按需引入。

方式二. 在 Vite 項(xiàng)目中按需引入組件

對(duì)于 vite 項(xiàng)目，可以使用 vite-plugin-style-import 實(shí)現(xiàn)按需引入, 原理和 babel-plugin-import 類(lèi)似。

# 安裝插件
npm i vite-plugin-style-import -D

// vite.config.js
import vue from '@vitejs/plugin-vue';
import styleImport from 'vite-plugin-style-import';

export default {
  plugins: [
    vue(),
    styleImport({
      libs: [
        {
          libraryName: 'vant',
          esModule: true,
          resolveStyle: (name) => `vant/es/${name}/style`,
        },
      ],
    }),
  ],
};

方式三. 手動(dòng)按需引入組件

在不使用插件的情況下，可以手動(dòng)引入需要使用的組件和樣式。

// 引入組件
import Button from 'vant/es/button';
// 引入組件對(duì)應(yīng)的樣式，若組件沒(méi)有樣式文件，則無(wú)須引入
import 'vant/es/button/style';

方式四. 導(dǎo)入所有組件

Vant 支持一次性導(dǎo)入所有組件，引入所有組件會(huì)增加代碼包體積，因此不推薦這種做法。

import { createApp } from 'vue';
import Vant from 'vant';
import 'vant/lib/index.css';

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

Tips: 配置按需引入后，將不允許直接導(dǎo)入所有組件。

常見(jiàn)問(wèn)題

如何自定義 Vant 組件的樣式？

1. 主題定制

Vant 基于 CSS 變量提供了主題定制的能力，可以對(duì)組件樣式進(jìn)行統(tǒng)一修改，詳見(jiàn) ConfigProvider 全局配置 組件。

2. 覆蓋默認(rèn)樣式

如果主題定制不能滿(mǎn)足你的需求，也可以通過(guò)自定義樣式類(lèi)來(lái)覆蓋默認(rèn)樣式，參考下面的示例：

<template>
  <van-button class="my-button">按鈕</van-button>
</template>

<style>
  /** 覆蓋 Button 最外層元素的樣式 */
  .my-button {
    width: 200px;
  }

  /** 覆蓋 Button 內(nèi)部子元素的樣式 */
  .my-button .van-button__text {
    color: red;
  }
</style>

在 HTML 中無(wú)法正確渲染組件？

在 HTML 中使用 Vant 組件時(shí)，你可能會(huì)碰到部分示例代碼無(wú)法正確渲染的情況，比如下面的用法：

<van-cell-group>
  <van-cell title="單元格" value="內(nèi)容" />
  <van-cell title="單元格" value="內(nèi)容" />
</van-cell-group>

這是因?yàn)?HTML 并不支持自閉合的自定義元素，也就是說(shuō) <van-cell /> 這樣的語(yǔ)法是不被識(shí)別的，使用完整的閉合標(biāo)簽可以避免這個(gè)問(wèn)題：

<van-cell-group>
  <van-cell title="單元格" value="內(nèi)容"></van-cell>
  <van-cell title="單元格" value="內(nèi)容"></van-cell>
</van-cell-group>

在單文件組件、字符串模板和 JSX 中可以使用自閉合的自定義元素，因此不會(huì)出現(xiàn)這個(gè)問(wèn)題。