快速开始

阅读此处时，默认您已经完全熟悉字典包的相关配置，如还未完全了解，请阅读使用须知。

安装

npm i vue3-vant4-dict -S

常规用法

全量引入vant的css样式时：

import { createApp } from "vue";
import App from "./App.vue";
// 1. 引入你需要的组件
import { ... } from 'vant';
import vue3Vant4Dict from 'vue3-vant4-dict'
import "vant/lib/index.css"; // 引入vant全量样式
import "vue3-vant4-dict/lib/index.css" // 需放在vant样式之后  重置vant的样式之前
const app = createApp();
app.use(...)
// ... 重置vant-css的样式 有的话
// ... 如果有字典版本号的功能  获取字典版本号接口 得到version后再继续
const dictConfig = { // 配置众多，可另建创建一个文件，引入此处
  autoRegisterComponent: true, // 全量注册css时  可配置成 自动注册组件 项目中直接使用
  componentsPreFix: "Bu", // 配置成你喜欢的组件前缀  此时将  bu-select 使用
  version,
  // ...等等其他配置
}
app.use(vue3Vant4Dict, dictConfig)
app.mount("#app");

TIP

提示：Vant 默认支持 Tree Shaking，因此你不需要配置任何插件，通过 Tree Shaking 即可移除不需要的 JS 代码，但 CSS 样式无法通过这种方式优化，如果需要按需引入 CSS 样式，请参考下面的按需引入。

按需引入一

在基于 Rsbuild、Vite、webpack 或 vue-cli 的项目中使用 Vant 时，可以使用 unplugin-vue-components 插件，它可以自动引入组件。

Vant 官方基于 unplugin-vue-components 提供了自动导入样式的解析器 @vant/auto-import-resolver，两者可以配合使用。

相比于常规用法，这种方式可以按需引入组件的 CSS 样式，从而减少一部分代码体积，但使用起来会变得繁琐一些。如果业务对 CSS 的体积要求不是特别极致，我们推荐使用更简便的常规用法。

安装插件

# 通过 npm 安装
npm i @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D

配置插件

在 vite.config.js 文件中配置插件：

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';
import { dictResolver } from 'vue3-vant4-dict'

export default {
  plugins: [
    vue(),
    AutoImport({
      resolvers: [VantResolver()],
    }),
    Components({
      resolvers: [
        // 可配置组件前缀  按需引入时 在此处配置  默认为 Dict
        dictResolver({ componentsPreFix: 'Bu'}),
        VantResolver()
      ],
    }),
  ],
};

main.js 引入

import { createApp } from "vue";
import App from "./App.vue";
import vue3Vant4Dict from 'vue3-vant4-dict'
import "vue3-vant4-dict/lib/index.css" // 需要放在重置vant的样式之前
// 配置自动引入后 此处就无需自己引入 vant组件了 使用时会自动导入 
const app = createApp();
// ... 如果有字典版本号的功能  获取字典版本号接口 得到version后再继续
const dictConfig = { // 配置众多，可另建创建一个文件，引入此处
  // 此处无需配置自动导入组件为true了 使用到时 自动会注册
  version,
  ...
}
app.use(vue3Vant4Dict, dictConfig)
app.mount("#app");

按需引入二

上述按需引入依赖于项目静态文件，当项目上使用到该组件时才会跑自动导入相应css文件，假如项目中的组件为动态导入的时候，上述按需导入将失效，此时需要使用到按需引入二

import { createApp } from "vue";
import App from "./App.vue";
import vue3Vant4Dict, {Select, Cascader, Date...} from 'vue3-vant4-dict'
import "vue3-vant4-dict/lib/index.css" // 需要放在重置vant的样式之前
// 配置自动引入后 此处就无需自己引入 vant组件了 使用时会自动导入 
const app = createApp();
// ... 如果有字典版本号的功能  获取字典版本号接口 得到version后再继续
const dictConfig = { // 配置众多，可另建创建一个文件，引入此处
  // 此处无需配置自动导入组件为true了 使用到时 自动会注册
  version,
  ...
}
app.use(vue3Vant4Dict, dictConfig)
// 得在 包挂在之后  使用按需引入, 第二个参数为  componentsPreFix 组件名称前缀配置
app.use(Select, "Bu").use(Button, "Bu").use(Date, "Bu")
// app.use相应字典包的组件后  跑一下项目 此时控制台会 输出我们 使用到上述组件 所需要用到的 vant相应组件的样式  在下面引入即可
import 'vant/es/icon/style'
import 'vant/es/field/style'
import 'vant/es/button/style'
import 'vant/es/popup/style'
import 'vant/es/picker/style'
import 'vant/es/date-picker/style'
app.mount("#app");

使用

在页面中使用

<dict-field label="姓名" maskType="name" clearable placeholder="请输入姓名" v-model="name"></dict-field>

当聚焦的时候可以输入，输入姓名后失去焦点时会脱敏展示，说明组件引入成功了。

验证字典组件配置是否成功就可尝试如下代码, dictType 传入接口存在的字典类型

<dict-select label="喜欢的运动" dictType="SPORTS" placeholder="请选择" v-model="sport" clearable></dict-select>

验证失败

非常遗憾，验证失败了，请再次阅读配置说明并理解配置项的含义及作用。

验证成功

恭喜您，验证成功啦，可以继续阅读下列具体文档来使用啦。

注意

上述例子仅做参考，真实案例可参照demo项目，抽离出来 dict-config.js、 /plugins/vue3-vant4-dict.js等文件使代码更加易读。