Vant4 快速上手

介紹

通過本章節(jié)你可以了解到 Vant 的安裝方法和基本使用姿勢。

安裝

通過 npm 安裝

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

# Vue 3 項(xiàng)目，安裝最新版 Vant
npm i vant

# Vue 2 項(xiàng)目，安裝 Vant 2
npm i vant@latest-v2

當(dāng)然，你也可以通過 ?yarn? 或 ?pnpm? 進(jìn)行安裝：

# 通過 yarn 安裝
yarn add vant

# 通過 pnpm 安裝
pnpm add vant

通過 CDN 安裝

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

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

<!-- 引入 Vue 和 Vant 的 JS 文件 -->
<script src="https://fastly.jsdelivr.net/npm/vue@3" rel="external nofollow" ></script>
<script src="https://fastly.jsdelivr.net/npm/vant@4/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.showToast('提示');

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

免費(fèi) CDN

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

• jsdelivr
• cdnjs
• unpkg

注意：免費(fèi) CDN 一般用于制作原型或個人小型項(xiàng)目，不推薦在企業(yè)生產(chǎn)環(huán)境中使用免費(fèi) CDN。

對于企業(yè)開發(fā)者，建議使用以下方式：

• 通過 npm 引入，并通過構(gòu)建工具進(jìn)行打包
• 下載對應(yīng)文件，并托管在你自己的服務(wù)器或 CDN 上

示例

示例工程

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

• 基于 Vite 和 Vant 搭建應(yīng)用
• 基于 Nuxt 和 Vant 搭建應(yīng)用
• 基于 Vue CLI 和 Vant 搭建應(yīng)用
• 配置按需引入組件
• 配置基于 Rem 的適配方案
• 配置基于 Viewport 的適配方案
• 配置基于 TypeScript 的工程

引入組件

方法一. 常規(guī)用法

下面是使用 Vant 組件的用法示例：

import { createApp } from 'vue';
// 1. 引入你需要的組件
import { Button } from 'vant';
// 2. 引入組件樣式
import 'vant/lib/index.css';

const app = createApp();

// 3. 注冊你需要的組件
app.use(Button);

Vant 支持多種組件注冊方式，除了在 app 上全局注冊組件，你也可以選擇其他的方式，比如局部注冊，詳見 組件注冊 章節(jié)。

提示：Vant 默認(rèn)支持 Tree Shaking，因此你不需要配置任何插件，通過 Tree Shaking 即可移除不需要的 JS 代碼，但 CSS 樣式無法通過這種方式優(yōu)化，如果需要按需引入 CSS 樣式，請參考下面的方法二。

方法二. 按需引入組件樣式

在基于 ?vite?、?webpack? 或 ?vue-cli? 的項(xiàng)目中使用 Vant 時，可以使用 unplugin-vue-components 插件，它可以自動引入組件，并按需引入組件的樣式。

相比于常規(guī)用法，這種方式可以按需引入組件的 CSS 樣式，從而減少一部分代碼體積，但使用起來會變得繁瑣一些。如果業(yè)務(wù)對 CSS 的體積要求不是特別極致，我們推薦使用更簡便的常規(guī)用法。

1. 安裝插件

# 通過 npm 安裝
npm i unplugin-vue-components -D

# 通過 yarn 安裝
yarn add unplugin-vue-components -D

# 通過 pnpm 安裝
pnpm add unplugin-vue-components -D

2. 配置插件

如果是基于 ?vite? 的項(xiàng)目，在 ?vite.config.js? 文件中配置插件：

import vue from '@vitejs/plugin-vue';
import Components from 'unplugin-vue-components/vite';
import { VantResolver } from 'unplugin-vue-components/resolvers';

export default {
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],
    }),
  ],
};

如果是基于 ?vue-cli? 的項(xiàng)目，在 ?vue.config.js? 文件中配置插件：

const { VantResolver } = require('unplugin-vue-components/resolvers');
const ComponentsPlugin = require('unplugin-vue-components/webpack');

module.exports = {
  configureWebpack: {
    plugins: [
      ComponentsPlugin({
        resolvers: [VantResolver()],
      }),
    ],
  },
};

如果是基于 ?webpack? 的項(xiàng)目，在 ?webpack.config.js? 文件中配置插件：

const { VantResolver } = require('unplugin-vue-components/resolvers');
const ComponentsPlugin = require('unplugin-vue-components/webpack');

module.exports = {
  plugins: [
    ComponentsPlugin({
      resolvers: [VantResolver()],
    }),
  ],
};

3. 使用組件

完成以上兩步，就可以直接在模板中使用 Vant 組件了，?unplugin-vue-components? 會解析模板并自動注冊對應(yīng)的組件。

<template>
  <van-button type="primary" />
</template>

4. 引入函數(shù)組件的樣式

Vant 中有個別組件是以函數(shù)的形式提供的，包括 ?Toast?，?Dialog?，?Notify? 和 ?ImagePreview? 組件。在使用函數(shù)組件時，?unplugin-vue-components? 無法自動引入對應(yīng)的樣式，因此需要手動引入樣式。

// Toast
import { showToast } from 'vant';
import 'vant/es/toast/style';

// Dialog
import { showDialog } from 'vant';
import 'vant/es/dialog/style';

// Notify
import { showNotify } from 'vant';
import 'vant/es/notify/style';

// ImagePreview
import { showImagePreview } from 'vant';
import 'vant/es/image-preview/style';

你可以在項(xiàng)目的入口文件或公共模塊中引入以上組件的樣式，這樣在業(yè)務(wù)代碼中使用組件時，便不再需要重復(fù)引入樣式了。

使用提示

• 請避免同時使用「全量引入」和「按需引入」這兩種引入方式，否則會導(dǎo)致代碼重復(fù)、樣式錯亂等問題。
• unplugin-vue-components 并不是 Vant 官方維護(hù)的插件，如果在使用過程中遇到問題，建議優(yōu)先到 antfu/unplugin-vue-components 倉庫下反饋。

在框架中使用

在 Nuxt 3 中使用

在 Nuxt 3 中使用 Vant 時，由于 Nuxt 3 框架本身的限制，需要在 ?nuxt.config.ts? 中添加以下配置：

import { defineNuxtConfig } from 'nuxt';

export default defineNuxtConfig({
  experimental: {
    externalVue: true,
  },
});

關(guān)于該問題的背景，可以參考以下 issue：

• nuxt/framework#6761
• nuxt/framework#4084

遷移提示

移除 babel-plugin-import

從 Vant 4.0 版本開始，將不再支持 ?babel-plugin-import?，請移除項(xiàng)目中依賴的 ?babel-plugin-import? 插件。

只需要刪除 ?babel.config.js? 中的以下代碼即可：

module.exports = {
  plugins: [
-    ['import', {
-      libraryName: 'vant',
-      libraryDirectory: 'es',
-      style: true
-    }, 'vant']
  ]
};

收益

移除 ?babel-plugin-import? 有以下收益：

• 不再強(qiáng)依賴 babel，項(xiàng)目可以使用 esbuild、swc 等更高效的編譯工具，大幅度提升編譯效率。
• 不再受到 ?babel-plugin-import? 的 import 寫法限制，可以從 vant 中導(dǎo)入除了組件以外的其他內(nèi)容，比如 Vant 4 中新增的 ?showToast? 等方法：

import { showToast, showDialog } from 'vant';