Vant组件库快速入门指南-优快云博客

本文链接：https://blog.youkuaiyun.com/qq_52731473/article/details/124481822

本文介绍了Vant，一个轻量级的移动端Vue组件库，包括其特点、安装方式（npm、CDN）、按需引入组件的方法以及解决在不同场景下遇到的问题，如在HTML中渲染组件和iOS上的点击反馈效果。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

简介

Vant是一套轻量、可靠的移动端Vue组件库，可以快速搭建出风格统一的页面，提升开发效率。

vant 官网

特点

60+ 高质量组件
95% 单元测试覆盖率
完善的中英文文档和示例
支持按需引入
支持主题定制
支持国际化
支持 TS
支持 SSR

建议搭配 webpack，babel 使用 Vant，这样可以使用 webpack 提供的丰富插件和个性化配置。Vant 支持了 babel-plugin-import，通过 babel 插件使用 Vant，可以优化代码体积，提高前端性能。

安装

通过 npm 安装

在现有项目中使用 Vant 时，可以通过 npm 进行安装：

# Vue 3 项目，安装最新版 Vant
npm i vant

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

当然，你也可以通过 yarn 或 pnpm 进行安装：

# 通过 yarn 安装
yarn add vant

# 通过 pnpm 安装
pnpm add vant

通过 CDN 安装

使用 Vant 最简单的方法是直接在 html 文件中引入 CDN 链接，之后你可以通过全局变量 vant 访问到所有组件。

<!-- 引入样式文件 -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/vant@3/lib/index.css"
/>

<!-- 引入 Vue 和 Vant 的 JS 文件 -->
<script src="https://cdn.jsdelivr.net/npm/vue@3"></script>
<script src="https://cdn.jsdelivr.net/npm/vant@3/lib/vant.min.js"></script>

<script>
  // 在 #app 标签下渲染一个按钮组件
  const app = Vue.createApp({
    template: `<van-button>按钮</van-button>`,
  });
  app.use(vant);

  // 通过 CDN 引入时不会自动注册 Lazyload 组件
  // 可以通过下面的方式手动注册
  app.use(vant.Lazyload);

  // 调用函数组件，弹出一个 Toast
  vant.Toast('提示');

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

引入组件

在 vite 项目中按需引入组件（推荐）

在 vite 项目中使用 Vant 时，推荐安装 vite-plugin-style-import 插件，它可以自动按需引入组件的样式。

1. 安装插件

# 通过 npm 安装
npm i vite-plugin-style-import@1.4.1 -D

# 通过 yarn 安装
yarn add vite-plugin-style-import@1.4.1 -D

# 通过 pnpm 安装
pnpm add vite-plugin-style-import@1.4.1 -D

2. 配置插件

安装完成后，在 vite.config.js 文件中配置插件：

import vue from '@vitejs/plugin-vue';
import styleImport, { VantResolve } from 'vite-plugin-style-import';

export default {
  plugins: [
    vue(),
    styleImport({
      resolves: [VantResolve()],
    }),
  ],
};

3. 引入组件

完成以上两步，就可以直接使用 Vant 组件了：

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

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

Vant 默认支持通过 Tree Shaking 实现 script 的按需引入。

在非 vite 项目中按需引入组件（推荐）

在非 vite 的项目中，可以通过 babel 插件来实现按需引入组件。我们需要安装 babel-plugin-import 插件，它会在编译过程中将 import 语句自动转换为按需引入的方式。

1. 安装插件

npm i babel-plugin-import -D

2. 配置插件

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

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

3. 引入组件

接着你可以在代码中直接引入 Vant 组件，插件会自动将代码转化为按需引入的形式。

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

// 编译后代码
import Button from 'vant/es/button';
import 'vant/es/button/style';

如果你在使用 TypeScript，可以使用 ts-import-plugin 实现按需引入。

全局注册

全局注册后，你可以在 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 { Button } from 'vant';

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

对于组件注册更详细的介绍，请参考 Vue 官方文档 - 组件注册。

如何自定义 Vant 组件的样式？

1. 主题定制

Vant 基于 CSS 变量提供了主题定制的能力，可以对组件样式进行统一修改，详见 ConfigProvider 全局配置组件。

2. 覆盖默认样式

如果主题定制不能满足你的需求，也可以通过自定义样式类来覆盖默认样式，参考下面的示例：

<template>
  <van-button class="my-button">按钮</van-button>
</template>

<style>
  /** 覆盖 Button 最外层元素的样式 */
  .my-button {
    width: 200px;
  }

  /** 覆盖 Button 内部子元素的样式 */
  .my-button .van-button__text {
    color: red;
  }
</style>

在 HTML 中无法正确渲染组件？

在 HTML 中使用 Vant 组件时，你可能会碰到部分示例代码无法正确渲染的情况，比如下面的用法：

<van-cell-group>
  <van-cell title="单元格" value="内容" />
  <van-cell title="单元格" value="内容" />
</van-cell-group>

这是因为 HTML 并不支持自闭合的自定义元素，也就是说 <van-cell /> 这样的语法是不被识别的，使用完整的闭合标签可以避免这个问题：

<van-cell-group>
  <van-cell title="单元格" value="内容"></van-cell>
  <van-cell title="单元格" value="内容"></van-cell>
</van-cell-group>

在单文件组件、字符串模板和 JSX 中可以使用自闭合的自定义元素，因此不会出现这个问题。

在 iOS 上点击组件时，无法触发点击反馈效果？

这是因为 iOS Safari 默认不会触发 :active 伪类，解决方法是在 body 标签上添加一个空的 ontouchstart 属性：

<body ontouchstart="">
  ...
</body>

参考链接：stackoverflow - :active pseudo-class doesn't work in mobile safari

为什么没有 Select 组件？

Select 是桌面端常用的组件，但它的交互形式不适合移动端。

在移动端，我们推荐使用 Picker 选择器组件作为代替。