Vue3移动端UI框架Vant的使用

发表于 | 分类于
Vue3移动端UI框架Vant的使用

Vant

官方文档

https://vant.pro/vant/#/zh-CN/home

特点

  • 🚀 性能极佳，组件平均体积小于 1KB（min+gzip）
  • 🚀 80+ 个高质量组件，覆盖移动端主流场景
  • 🚀 零外部依赖，不依赖三方 npm 包
  • 💪 使用 TypeScript 编写，提供完整的类型定义
  • 💪 单元测试覆盖率超过 90%，提供稳定性保障
  • 📖 提供丰富的中英文文档和组件示例
  • 📖 提供 Sketch 和 Axure 设计资源
  • 🍭 支持 Vue 2、Vue 3 和微信小程序
  • 🍭 支持主题定制，内置 700+ 个主题变量
  • 🍭 支持按需引入和 Tree Shaking
  • 🌍 支持国际化，内置 30+ 种语言包

安装依赖

1
2
3
4
5
# Vue 3 项目，安装最新版 Vant
npm i vant

# Vue 2 项目，安装 Vant 2
npm i vant@latest-v2

组件注册

全局注册

1
2
3
4
5
6
7
8
9
10
11
import { createApp } from 'vue'
const app = createApp()

// 1. 引入你需要的组件
import { Button, NavBar, NumberKeyboard } from 'vant'
// 2. 引入组件样式
import 'vant/lib/index.css'
// 3. 注册组件
app.use(Button)
app.use(NavBar)
app.use(NumberKeyboard)

页面中使用van-组件名小写方式使用，不能使用组件名大写的方式。

1
<van-button type="primary">主要按钮</van-button>

注意

个人更推荐使用这种方式，官方示例中也基本使用这种方式。

全量注册

1
2
3
4
5
6
7
8
9
import Vant from 'vant'
import { createApp } from 'vue'

const app = createApp()

app.use(Vant)

// Lazyload 指令需要单独进行注册
app.use(vant.Lazyload)

注意

注册所有组件会引入所有组件的代码，导致包体积增大。

局部注册

局部注册后，你可以在当前组件中使用注册的 Vant 组件。

1
2
3
4
5
6
7
import { Button } from 'vant';

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

setup中

在 <script setup> 中可以直接使用 Vant 组件，不需要进行组件注册。

1
2
3
4
5
6
7
<template>
  <Button />
</template>

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

注意

通过这种方式使用的时候组件名要和引用名一样，不能使用van-button形式。

自动引用

相比于常规用法，这种方式可以按需引入组件的 CSS 样式，从而减少一部分代码体积，但使用起来会变得繁琐一些。

如果业务对 CSS 的体积要求不是特别极致，我们推荐使用更简便的常规用法。

安装插件

1
npm i @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D

配置插件

如果是基于 Vite 的项目，在 vite.config.js 文件中配置插件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import vue from '@vitejs/plugin-vue';
import AutoImport from 'unplugin-auto-import/vite';
import Components from 'unplugin-vue-components/vite';
import { VantResolver } from '@vant/auto-import-resolver';

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

使用组件和 API

完成以上两步，就可以直接在模板中使用 Vant 组件了，unplugin-vue-components 会解析模板并自动注册对应的组件, @vant/auto-import-resolver 会自动引入对应的组件样式。

1
2
3
<template>
  <van-button type="primary" />
</template>

unplugin-auto-import 会自动导入对应的 Vant API 以及样式。

1
2
3
<script>
  showToast('No need to import showToast');
</script>

底部安全区适配

iPhone X 等机型底部存在底部指示条，指示条的操作区域与页面底部存在重合，容易导致用户误操作，因此我们需要针对这些机型进行安全区适配。

Vant 中部分组件提供了 safe-area-inset-top 或 safe-area-inset-bottom 属性，设置该属性后，即可在对应的机型上开启适配，如下示例：

1
2
3
4
5
6
7
8
9
10
11
<!-- 在 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"
/>

<!-- 开启顶部安全区适配 -->
<NavBar safe-area-inset-top />

<!-- 开启底部安全区适配 -->
<NumberKeyboard safe-area-inset-bottom />

添加引用

1
import { NavBar, NumberKeyboard } from 'vant'
1
2
3
4
5
<!-- 开启顶部安全区适配 -->
<van-nav-bar safe-area-inset-top />
<RouterView />
<!-- 开启底部安全区适配 -->
<van-number-keyboard safe-area-inset-bottom />

桌面端适配

Vant 是一个面向移动端的组件库，因此默认只适配了移动端设备，这意味着组件只监听了移动端的 touch 事件，没有监听桌面端的 mouse 事件。

如果你需要在桌面端使用 Vant，可以引入我们提供的 @vant/touch-emulator，这个库会在桌面端自动将 mouse 事件转换成对应的 touch 事件，使得组件能够在桌面端使用。

1
2
3
4
# 安装模块
npm i @vant/touch-emulator -S
// 引入模块后自动生效
import '@vant/touch-emulator';