Vant3 快速上手

通過 npm 安裝

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

# Vue 2 項目，安裝 Vant 2：
npm i vant -S

# Vue 3 項目，安裝 Vant 3：
npm i vant@next -S

通過 CDN 安裝

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

<!-- 引入樣式文件 -->
<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)簽下渲染一個按鈕組件
  const app = Vue.createApp({
    template: `<van-button>按鈕</van-button>`,
  });
  app.use(vant);

  // 通過 CDN 引入時不會自動注冊 Lazyload 組件
  // 可以通過下面的方式手動注冊
  app.use(vant.Lazyload);

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

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

你可以通過以下免費 CDN 服務(wù)來使用 Vant:

• jsdelivr
• cdnjs
• unpkg

通過腳手架安裝

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

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

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

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

在圖形化界面中，點擊 依賴 -> 安裝依賴，然后將 vant 添加到依賴中即可。

示例

示例工程

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

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

引入組件

方式一. 通過 babel 插件按需引入組件

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

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

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

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

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

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

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

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

方式二. 在 Vite 項目中按需引入組件

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

# 安裝插件
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`,
        },
      ],
    }),
  ],
};

方式三. 手動按需引入組件

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

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

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

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

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

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

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

常見問題

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

1. 主題定制

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

2. 覆蓋默認樣式

如果主題定制不能滿足你的需求，也可以通過自定義樣式類來覆蓋默認樣式，參考下面的示例：

<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 中無法正確渲染組件？

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

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

這是因為 HTML 并不支持自閉合的自定義元素，也就是說 <van-cell /> 這樣的語法是不被識別的，使用完整的閉合標(biāo)簽可以避免這個問題：

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

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