Vant 快速上手

腳手架

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

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

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

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

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

通過 npm 安裝

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

# 通過 npm 安裝
npm i vant -S

# 通過 yarn 安裝
yarn add vant

示例工程

我們提供了一個基于 Vue Cli 的示例工程，示例工程會幫助你了解如下內(nèi)容：

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

引入組件

方式一. 自動按需引入組件 (推薦)

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

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

// 在.babelrc 中添加配置
// 注意：webpack 1 無需設(shè)置 libraryDirectory
{
  "plugins": [
    ["import", {
      "libraryName": "vant",
      "libraryDirectory": "es",
      "style": true
    }]
  ]
}

// 對于使用 babel7 的用戶，可以在 babel.config.js 中配置
module.exports = {
  plugins: [
    ['import', {
      libraryName: 'vant',
      libraryDirectory: 'es',
      style: true
    }, 'vant']
  ]
};

// 接著你可以在代碼中直接引入 Vant 組件
// 插件會自動將代碼轉(zhuǎn)化為方式二中的按需引入形式
import { Button } from 'vant';

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

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

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

import Button from 'vant/lib/button';
import 'vant/lib/button/style';

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

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

import Vue from 'vue';
import Vant from 'vant';
import 'vant/lib/index.css';

Vue.use(Vant);

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

方式四. 通過 CDN 引入

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

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

<!-- 引入 Vue 和 Vant 的 JS 文件 -->
<script src="https://unpkg.com/vue@2.6/dist/vue.min.js" rel="external nofollow" ></script>
<script src="https://unpkg.com/vant@2.12/lib/vant.min.js" rel="external nofollow" ></script>

<script>
    // 在 #app 標(biāo)簽下渲染一個按鈕組件
    new Vue({
        el: '#app',
        template: `<van-button>按鈕</van-button>`,
    });

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

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

進(jìn)階用法

Rem 適配

Vant 中的樣式默認(rèn)使用px作為單位，如果需要使用rem單位，推薦使用以下兩個工具：

• postcss-pxtorem 是一款 postcss 插件，用于將單位轉(zhuǎn)化為 rem
• lib-flexible 用于設(shè)置 rem 基準(zhǔn)值

PostCSS 配置

下面提供了一份基本的 postcss 配置，可以在此配置的基礎(chǔ)上根據(jù)項目需求進(jìn)行修改

module.exports = {
  plugins: {
    'autoprefixer': {
      browsers: ['Android >= 4.0', 'iOS >= 8']
    },
    'postcss-pxtorem': {
      rootValue: 37.5,
      propList: ['*']
    }
  }
}

在配置 postcss-loader 時，應(yīng)避免 ignore node_modules 目錄，否則將導(dǎo)致 Vant 樣式無法被編譯

在桌面端使用

Vant 是一個面向移動端的組件庫，因此默認(rèn)只適配了移動端設(shè)備，這意味著組件只監(jiān)聽了移動端的 touch 事件，沒有監(jiān)聽桌面端的 mouse 事件。

如果你需要在桌面端使用 Vant，可以引入我們提供的 @vant/touch-emulator，這個庫會在桌面端自動將 mouse 事件轉(zhuǎn)換成對應(yīng)的 touch 事件，使得組件能夠在桌面端使用。

# 安裝模塊
npm i @vant/touch-emulator -S

// 引入模塊后自動生效
import '@vant/touch-emulator';

底部安全區(qū)適配

iPhone X 等機(jī)型底部存在底部指示條，指示條的操作區(qū)域與頁面底部存在重合，容易導(dǎo)致用戶誤操作，因此我們需要針對這些機(jī)型進(jìn)行底部安全區(qū)適配。Vant 中部分組件提供了 safe-area-inset-bottom 屬性，設(shè)置該屬性后，即可在對應(yīng)的機(jī)型上開啟適配，如下示例：

<!-- 在 head 標(biāo)簽中添加 meta 標(biāo)簽，并設(shè)置 viewport-fit=cover 值 -->
<meta
  name="viewport"
  content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover"
/>

<!-- 開啟 safe-area-inset-bottom 屬性 -->
<van-number-keyboard safe-area-inset-bottom />

組件實例方法

Vant 中的許多組件提供了實例方法，調(diào)用實例方法時，我們需要通過 ref 來注冊組件引用信息，引用信息將會注冊在父組件的$refs對象上。注冊完成后，我們可以通過 this.$refs.xxx 訪問到對應(yīng)的組件實例，并調(diào)用上面的實例方法。

<!-- 將該組件綁定到 this.$refs.checkbox 上 -->
<van-checkbox v-model="checked" ref="checkbox">
  復(fù)選框
</van-checkbox>

export default {
  data() {
    return {
      checked: false
    };
  },
  // 注意：組件掛載后才能訪問到 ref 對象
  mounted() {
    this.$refs.checkbox.toggle();
  }
}

常見問題

在 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)這個問題。