快速开始

本指南将帮助您快速在项目中集成和使用Vant移动端UI组件库。

📦 安装

npm 安装

npm install vant

yarn 安装

yarn add vant

pnpm 安装

pnpm add vant

🚀 引入组件

方式一：自动按需引入（推荐）

安装插件：

npm install unplugin-vue-components -D

配置 vite.config.js：

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

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

方式二：手动按需引入

import { createApp } from 'vue'
import { Button, Cell } from 'vant'

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

方式三：完整引入

import { createApp } from 'vue'
import Vant from 'vant'
import 'vant/lib/index.css'

const app = createApp()
app.use(Vant)

💡 基础用法

第一个组件

<template>
  <div>
    <van-button type="primary">主要按钮</van-button>
    <van-button type="success">成功按钮</van-button>
  </div>
</template>

移动端适配

在HTML头部添加viewport meta标签：

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover">

Rem适配

安装postcss-pxtorem：

npm install postcss-pxtorem -D

配置 postcss.config.js：

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

🎨 主题定制

CSS变量定制

:root {
  --van-primary-color: #1989fa;
  --van-success-color: #07c160;
  --van-danger-color: #ee0a24;
  --van-warning-color: #ff976a;
  --van-text-color: #323233;
  --van-active-color: #f2f3f5;
  --van-active-opacity: 0.7;
  --van-disabled-opacity: 0.5;
  --van-background-color: #f7f8fa;
  --van-background-color-light: #fafafa;
}

Less变量定制

@primary-color: #1989fa;
@success-color: #07c160;
@danger-color: #ee0a24;
@warning-color: #ff976a;
@text-color: #323233;
@border-color: #ebedf0;
@active-color: #f2f3f5;
@background-color: #f7f8fa;
@background-color-light: #fafafa;

📱 移动端调试

在桌面端调试

安装 @vant/touch-emulator：

npm install @vant/touch-emulator -D

引入模拟器：

import '@vant/touch-emulator'

真机调试

1. 确保手机和电脑在同一网络
2. 启动开发服务器
3. 在手机浏览器中访问电脑IP地址

🔧 TypeScript支持

Vant完全支持TypeScript，无需额外配置：

import { Button } from 'vant'
import type { ButtonType } from 'vant'

const buttonType: ButtonType = 'primary'

🌍 国际化

引入语言包

import { Locale } from 'vant'
import enUS from 'vant/es/locale/lang/en-US'

Locale.use('en-US', enUS)

支持的语言

• 简体中文 (zh-CN)
• 繁体中文 (zh-TW)
• 英语 (en-US)
• 德语 (de-DE)
• 日语 (ja-JP)
• 等30+种语言

⚡ 性能优化

按需引入

只引入使用的组件，减小打包体积：

import { Button, Cell } from 'vant'

图片懒加载

使用Lazyload指令：

import { Lazyload } from 'vant'

app.use(Lazyload)

<template>
  <img v-lazy="imageUrl" />
</template>

🚀 下一步

• 组件使用指南 - 了解所有组件的详细用法
• 最佳实践 - 学习企业级开发经验
• 常见问题 - 解决开发中的常见问题

💬 获得帮助

• GitHub Issues
• 官方文档
• 社区讨论