快速开始
阅读此处时，默认您已经完全熟悉字典包的相关配置，如还未完全了解，请阅读使用须知。
下列一堆文字，您懒得阅读的话，您可以阅读SKILL技能包方式快速完成vant4字典包初始化
安装
vant4的使用请阅读vant4的官方文档，此处不再赘述。
shell
npm i vue3-vant4-dict -S新建一个src/assets/data/dict.js文件
此文件为存储本地字典数据，文件位置您可以自定义，只要在配置项引入时路径正确即可，建议路径为 src/assets/data/dict.js
示例本地字典数据如下：
js
export default {
// 性别
SEX_DEMO: [
{ label: '男', value: ‘1’ },
{ label: '女', value: ‘2’ },
],
// 状态
STATUS_DEMO: [
{ label: '启用', value: ‘1’ },
{ label: '禁用', value: ‘0’ },
],
}新建一个src/api/modules/common-api.js文件
暴露获取字典的接口，供配置时使用。文件位置一样的，您可以自行选择路径，但请确保路径正确。建议路径为 src/api/modules/common-api.js
此处使用promise模拟一个字典接口示例，使用时自行替换为您自己的接口，您的字典接口请求数据格式、接口返回数据格式与字典包要求不一致时，可详细阅读配置说明， 通通都能转化成可以使用的字典数据。
js
//模拟的获取字典数据接口 有接口时 请使用接口替代
export function getDictCodeApi(options) {
var promise = new Promise(function (resolve) {
const dictCodeList = {
FRUTS_DEMO: [
{
value: "1",
label: "苹果",
},
{
value: "2",
label: "草莓",
},
],
VEGETABLES_DEMO: [
{
value: "1",
label: "西红柿",
},
{
value: "2",
label: "西蓝花",
},
],
AREA_DEMO: [
{
id: "35060000", // 树形数据 的id 字段 可配置 treeSetting.idField 字段修改 此字段用于 将一维数组转化为树形结构的依据
parentId: "0", // 树形数据的 父级id 字段 可配置 treeSetting.parentIdField 字段修改 此字段用于 将一维数组转化为树形结构的依据
value: "1", // 树形数据 的value 字段 可配置 format.value 字段修改 如果与 一维数组的value字段不一致时，那可以配置 treeSetting.valueField 字段修改
label: "漳州市", // 树形数据 的label 字段 可配置 format.label 字段修改 如果与 一维数组的label字段不一致时，那可以配置 treeSetting.labelField 字段修改
},
{
id: "35062400",
parentId: "35060000",
value: "2",
label: "诏安县",
},
{
id: "35062401",
parentId: "35062400",
value: "3",
label: "太平镇",
disabled: true,
},
{
id: "35062402",
parentId: "35062400",
value: "4",
label: "金星乡",
},
{
id: "35062403",
parentId: "35062400",
value: "5",
label: "南诏镇",
},
{
id: "35062404",
parentId: "35062400",
value: "6",
label: "霞葛镇",
},
{
id: "35062300",
parentId: "35060000",
value: "7",
label: "云霄县",
},
{
id: "35062301",
parentId: "35062300",
value: "8",
label: "列屿镇",
},
{
id: "35062302",
parentId: "35062300",
value: "9",
label: "陈岱镇",
},
{
id: "35062303",
parentId: "35062300",
value: "10",
label: "云陵镇",
},
{
id: "35062304",
parentId: "35062300",
value: "11",
label: "火田镇",
},
],
};
let codeData = {};
if (options && options.dictType) {
const typeList = options.dictType.split(",");
for (let i = 0; i < typeList.length; i++) {
const dictType = typeList[i];
codeData[dictType] = dictCodeList[dictType];
}
} else {
codeData = dictCodeList;
}
const data = {
dictData: codeData,
dictVersion: "5.2.0",
};
setTimeout(() => {
resolve(data);
}, 1000);
});
return promise;
}
//获取全局配置 包含版本号
export function getGlobalConfigApi() {
return new Promise((resolve, reject) => {
resolve({ version: "5.2.0" });
});
}新建一个src/dict-config.js文件
此文件为字典包的配置文件，此处列举一下必填项配置
js
import { getDictCodeApi } from "@/api/modules/common-api.js";
import localDictCodes from "@/assets/data/dict.js";
export default {
autoRegisterComponent: false, // 默认为false 手动引入， 配置为true时 则会将字典包全部组件都注册
componentsPreFix: "dict", // 配置成你喜欢的组件前缀 如配置为 bu 使用方式则为 bu-select
getDictCodeApi, //必传 获取字典数据接口
localDictCodes, //选填 项目写死的字典数据
query: "dictType", // 这个是配置 请求参数的字段名字段 如 {dictType: "FRUTS"} 中的 dictType 默认为dictType 不一致时可改
/**
* 请求参数转换
* query 就是上述配置的query的值 您的接口不需要用到query时，上述query配置可以忽略不计
* dictType 就是请求的字典类型的数据
*/
formatterRequest: (query, dictType) => {
if (!dictType) {
return { [query]: "" };
}
return { [query]: dictType };
},
/**
* 响应数据转换
* data是接口响应数据
* dictType 就是请求的字典类型的数据 是为了解决有些后端开发出来的接口响应数据data中没有dictType导致无法拼凑成符合字典包的数据格式的问题
*/
formatterDictList: (data, dictType) => {
if (!data || !data.dictData) {
return {};
}
return data.dictData;
},
/**
* 获取字典版本号 如果您无字典版本号的概念 下面两个配置可忽略不计
* data 字典接口返回的数据
*/
formatterDictVersion: (data) => {
if (!data || !data.version) {
return "unknow";
}
return data.version;
},
// 无字典数据版本号概念时 无需配置 (或者配置成和formatterDictVersion返回值一致的值即可) 有字典版本号时 在main.js中 获取字典数据版本号后再配置
// version: "unknow",
};新建一个 src/plugins/vue3-vant4-dict.js文件
当不自动全部注册字典包所有组件时配置，即autoRegisterComponent：false时需要，请自行注册字典包组件
js
import {
Field,
Button,
Cascader,
Buttons,
Cells,
DropdownItem,
Select,
Date,
MultipleSelect,
Time,
Datetime,
DynamicComponents,
} from 'vue3-vant4-dict'
/**
* 下面这些需要引入的vant的样式 在浏览器控制台会提示 复制过来即可 每引入一个组件，
* 需要重新引入对应的最新的样式，引入顺序是有差的哟，严格复制浏览器控制台打印的内容
* */
import "vant/es/icon/style"
import "vant/es/field/style"
import "vant/es/button/style"
import "vant/es/cell/style"
import "vant/es/cell-group/style"
import "vant/es/popup/style"
import "vant/es/checkbox/style"
import "vant/es/checkbox-group/style"
import "vant/es/picker/style"
import "vant/es/picker-group/style"
import "vant/es/time-picker/style"
import "vant/es/date-picker/style"
import "vant/es/cascader/style"
import "vant/es/dropdown-item/style"
import "vant/es/empty/style"
import "vant/es/form/style"
import "vant/es/search/style"
import "vant/es/toast/style"
const registerDictComponents = (app) => {
// 第二个参数为组件前缀 默认为Dict
app.use(Field)
app.use(Cells)
app.use(Cascader)
app.use(Button)
app.use(Buttons)
app.use(Select)
app.use(Date)
app.use(DropdownItem)
app.use(MultipleSelect)
app.use(Time)
app.use(Datetime)
app.use(DynamicComponents)
}
export default registerDictComponents常规用法 全量引入vant组件库样式
全量引入vant的css样式时：
js
import { createApp } from "vue";
import App from "./App.vue";
import vue3Vant4Dict from "vue3-vant4-dict";
import "vant/lib/index.css"; // 引入vant全量样式
import "vue3-vant4-dict/lib/style.css"; // 需放在vant样式之后 重置vant的样式之前
const app = createApp();
// 引入字典包配置
import dictConfig from "@/dict-config.js";
app.use(vue3Vant4Dict, dictConfig);
// 引入vant全量样式 且 autoRegisterComponent 配置为true时， 将下列代码注释
import registerDictComponents from "@/plugins/vue3-vant4-dict";
registerDictComponents(app);
app.mount("#app");TIP
提示：Vant 默认支持 Tree Shaking，因此你不需要配置任何插件，通过 Tree Shaking 即可移除不需要的 JS 代码，但 CSS 样式无法通过这种方式优化，如果需要按需引入 CSS 样式，请参考下面的按需引入。
按需引入一（非全量引入vant的css）
在基于 Rsbuild、Vite、webpack 或 vue-cli 的项目中使用 Vant 时，可以使用 unplugin-vue-components 插件，它可以自动引入组件。
Vant 官方基于 unplugin-vue-components 提供了自动导入样式的解析器 @vant/auto-import-resolver，两者可以配合使用。
相比于常规用法，这种方式可以按需引入组件的 CSS 样式，从而减少一部分代码体积，但使用起来会变得繁琐一些。如果业务对 CSS 的体积要求不是特别极致，我们推荐使用更简便的常规用法。
安装插件
shell
# 通过 npm 安装
npm i @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D配置插件
在 vite.config.js 文件中配置插件：
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 引入
js
import { createApp } from "vue";
import App from "./App.vue";
import vue3Vant4Dict from "vue3-vant4-dict";
import "vue3-vant4-dict/lib/style.css"; // 需要放在重置vant的样式之前
// 配置自动引入后 此处就无需自己引入 vant组件了 使用时会自动导入
const app = createApp();
// 引入字典包配置
import dictConfig from "@/dict-config.js";
app.use(vue3Vant4Dict, dictConfig);
app.mount("#app");使用组件时就会自动注册组件，自动引入vant的样式
按需引入二
上述按需引入依赖于项目静态文件，当项目上使用到该组件时才会跑自动导入相应css文件，假如项目中的组件为动态导入的时候，上述按需导入将失效，此时需要使用到按需引入二
js
import { createApp } from "vue";
import App from "./App.vue";
import vue3Vant4Dict from "vue3-vant4-dict";
// 配置自动引入后 此处就无需自己引入 vant组件了 使用时会自动导入
const app = createApp();
// 引入字典包配置
import dictConfig from "@/dict-config.js";
app.use(vue3Vant4Dict, dictConfig);
// 引入vant全量样式 且 autoRegisterComponent 配置为true时， 将下列代码注释
import registerDictComponents from "@/plugins/vue3-vant4-dict";
registerDictComponents(app);
app.mount("#app");使用
在页面中使用
vue
<dict-field
label="姓名"
maskType="name"
clearable
placeholder="请输入姓名"
v-model="name"
></dict-field>当聚焦的时候可以输入，输入姓名后失去焦点时会脱敏展示，说明组件引入成功了。
验证字典组件配置是否成功就可尝试如下代码, dictType 传入接口存在的字典类型
vue
<dict-select
label="喜欢的运动"
dictType="SPORTS"
placeholder="请选择"
v-model="sport"
clearable
></dict-select>验证失败
非常遗憾，验证失败了，请再次阅读配置说明并理解配置项的含义及作用。
验证成功
恭喜您，验证成功啦，可以继续阅读下列具体文档来使用啦。
注意
上述例子仅做参考，真实案例可参照demo项目，抽离出来 dict-config.js、 /plugins/vue3-vant4-dict.js等文件使代码更加易读。