進階用法

🚀 介紹

透過本章節你可以了解到 Vant 的一些進階用法，比如組件插槽用法、多種瀏覽器適配方式。掌握這些技巧，讓你的開發更加得心應手！

組件用法

組件註冊

Vant 支援多種組件註冊方式，請根據實際業務需要進行選擇。靈活的註冊方式，滿足不同場景的開發需求！

全域註冊

全域註冊後，你可以在 app 下的任意子組件中使用註冊的 Vant 組件。一次註冊，全域可用！

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

const app = createApp();

// 方式一. 透過 app.use 註冊
// 註冊完成後，在模板中透過 <van-button> 或 <VanButton> 標籤來使用按鈕組件
app.use(Button);

// 方式二. 透過 app.component 註冊
// 註冊完成後，在模板中透過 <van-button> 標籤來使用按鈕組件
app.component(Button.name, Button);

全量註冊

你也可以在全域一次性註冊所有 Vant 組件，省時省力！

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

const app = createApp();

app.use(Vant);

// Lazyload 指令需要單獨進行註冊
app.use(vant.Lazyload);

注意：註冊所有組件會引入所有組件的程式碼，導致包體積增大。

局部註冊

局部註冊後，你可以在目前組件中使用註冊的 Vant 組件。

import { Button } from 'vant';

export default {
  components: {
    [Button.name]: Button,
  },
};

對於組件註冊更詳細的介紹，請參考 Vue 官方文件 - 組件註冊。

<script setup>

在 \<script setup> 中可以直接使用 Vant 組件，不需要進行組件註冊。

<script setup>
  import { Button } from 'vant';
</script>

<template>
  <Button />
</template>

JSX/TSX

在 JSX 和 TSX 中可以直接使用 Vant 組件，不需要進行組件註冊。

import { Button } from 'vant';

export default {
  render() {
    return <Button />;
  },
};

組件插槽

Vant 提供了豐富的組件插槽，透過插槽可以對組件的某一部分進行個性化定製。如果你對 Vue 的插槽不太熟悉，可以閱讀 Vue 官方文件中的插槽章節。下面是透過插槽來定製 Checkbox 圖示的範例：

<van-checkbox v-model="checked">
  <!-- 使用組件提供的 icon 插槽 -->
  <!-- 將預設圖示替換為個性化圖片 -->
  <template #icon="props">
    <img :src="props.checked ? activeIcon : inactiveIcon" />
  </template>
</van-checkbox>

export default {
  data() {
    return {
      checked: true,
      activeIcon:
        'https://fastly.jsdelivr.net/npm/@vant/assets/user-active.png',
      inactiveIcon:
        'https://fastly.jsdelivr.net/npm/@vant/assets/user-inactive.png',
    };
  },
};

組件實例方法

Vant 中的許多組件提供了實例方法，呼叫實例方法時，我們需要透過 ref 來註冊組件引用資訊，引用資訊將會註冊在父組件的$refs物件上。註冊完成後，我們可以透過this.$refs.xxx存取到對應的組件實例，並呼叫上面的實例方法。

<!-- 透過 ref 屬性將組件綁定到 this.$refs.checkbox 上 -->
<van-checkbox v-model="checked" ref="checkbox"> 複選框 </van-checkbox>

export default {
  data() {
    return {
      checked: false,
    };
  },
  // 注意：組件掛載後才能存取到 ref 物件
  mounted() {
    this.$refs.checkbox.toggle();
  },
};

瀏覽器適配

Viewport 佈局

Vant 預設使用 px 作為樣式單位，如果需要使用 viewport 單位 (vw, vh, vmin, vmax)，推薦使用 postcss-px-to-viewport 進行轉換。

postcss-px-to-viewport 是一款 PostCSS 外掛，用於將 px 單位轉化為 vw/vh 單位。

PostCSS PostCSS 範例配置

下面提供了一份基本的 PostCSS 範例配置，可以在此配置的基礎上根據專案需求進行修改。

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
    },
  },
};

Tips: 在配置 postcss-loader 時，應避免 ignore node_modules 目錄，否則將導致 Vant 樣式無法被編譯。

Rem 佈局適配

如果需要使用 rem 單位進行適配，推薦使用以下兩個工具：

• postcss-pxtorem 是一款 PostCSS 外掛，用於將 px 單位轉化為 rem 單位
• lib-flexible 用於設定 rem 基準值

PostCSS 範例配置

下面提供了一份基本的 PostCSS 範例配置，可以在此配置的基礎上根據專案需求進行修改。

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-pxtorem': {
      rootValue: 37.5,
      propList: ['*'],
    },
  },
};

Tips: 在配置 postcss-pxtorem 時，同樣應避免 ignore node_modules 目錄，否則會導致 Vant 樣式無法被編譯。

其他設計稿尺寸

如果設計稿的尺寸不是 375，而是 750 或其他大小，可以將 rootValue 配置調整為:

// postcss.config.js
module.exports = {
  plugins: {
    // postcss-pxtorem 外掛的版本需要 >= 5.0.0
    'postcss-pxtorem': {
      rootValue({ file }) {
        return file.indexOf('vant') !== -1 ? 37.5 : 75;
      },
      propList: ['*'],
    },
  },
};

桌面端適配

Vant 是一個面向行動端的組件庫，因此預設只適配了行動端裝置，這意味著組件只監聽了行動端的 touch 事件，沒有監聽桌面端的 mouse 事件。

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

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

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

底部安全區適配

iPhone X 等機型底部存在底部指示條，指示條的操作區域與頁面底部存在重合，容易導致使用者誤操作，因此我們需要針對這些機型進行安全區適配。Vant 中部分組件提供了 safe-area-inset-top 或 safe-area-inset-bottom 屬性，設定該屬性後，即可在對應的機型上開啟適配，如下範例：

<!-- 在 head 標籤中新增 meta 標籤，並設定 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"
/>

<!-- 開啟頂部安全區適配 -->
<van-nav-bar safe-area-inset-top />

<!-- 開啟底部安全區適配 -->
<van-number-keyboard safe-area-inset-bottom />

📝 總結

恭喜你掌握了 Vant 的進階用法！🎉 透過本章節的學習，你已經了解了組件註冊的多種方式、插槽的靈活運用、實例方法的呼叫技巧，以及各種瀏覽器適配方案。這些進階技能將讓你在實際開發中更加游刃有餘！

🎯 核心要點回顧：

• 🔧 組件註冊：全域註冊、局部註冊、script setup 等多種方式任你選擇
• 🎨 插槽定製：透過插槽實現個性化的組件定製
• ⚡ 實例方法：透過 ref 呼叫組件實例方法，實現更複雜的互動
• 📱 行動端適配：Viewport 和 Rem 佈局方案，完美適配各種螢幕
• 🖥️ 桌面端支援：透過 touch-emulator 讓行動端組件在桌面端也能正常使用
• 🛡️ 安全區適配：完美適配 iPhone X 等全螢幕裝置

掌握這些技巧後，你就能充分發揮 Vant 的強大功能，構建出更加優秀的行動端應用！

🔗 相關內容

• 快速開始 - 從零開始使用 Vant
• 主題定製 - 打造專屬的視覺風格
• 最佳實踐 - 開發經驗和技巧分享
• 行動端適配 - 完美適配各種裝置
• TypeScript 指南 - 類型安全的開發體驗
• Vue3 整合指南 - 與 Vue3 的完美結合