使用须知
字典包使用时，需要依赖于字典数据，那就难免需要字典数据接口。因此需要讲一下接口需要满足什么条件才能完美的与此字典包配合使用。（不支持的情况也是可以用的，没那么完美而已）
字典接口需要满足的条件
- 能够根据不同的参数，支持获取一个、多个或者全部字典数据。
- 返回字典数据的同时，需要返回字典数据的最新版本号（用于判断浏览器中的字典数据是否是最新的）。
- 再多一个获取全局配置的接口，用于进入项目前获取到字典版本号后，初始化字典包时使用。
当然，接口不满足上述情况时，字典包还是可以使用的，上述要求是完美配合情况下的条件。
当不满足上述要求时，请将字典缓存位置存储在浏览器的sessionStorage中，即配置 storage 为 sessionStorage
默认字典接口响应数据格式
字典包默认一种字典接口响应数据格式，如下
{
dictData: {
"字典类型1": [
{
label: "字典项名称1", // 字典项名称默认字段为 label 可配置 format.label 配置修改对应字段
value: "字典项值1", // 字典项值默认字段为 value 可配置 format.value 配置修改对应字段
disabled: false, // 是否可以选择 为true时 在组件中为禁止选择状态 字典项是否禁用字段你 可以配置 format.disabled 配置修改对应字段
type: "priamry", // 按钮 标签 等字典组件使用时 会自动渲染对应类型 字典项类型字段可配置 format.type 配置修改对应字段
color: "" // 按钮 标签 等字典组件使用时 会自动渲染对应颜色 字典项颜色字段可配置 format.color 配置修改对应字段
},
{
label: "字典项名称2",
value: "字典项值2",
disabled: false,
type: "success",
color: ""
}
],
"字典类型2": [
{
label: "字典项名称1",
value: "字典项值1",
disabled: false,
type: "success",
color: ""
},
{
label: "字典项名称2",
value: "字典项值2",
disabled: false,
type: "danger", // 按钮 标签 字典组件使用时 会自动渲染对应类型
color: "pink"
}
],
"树形数据字典类型": [
{
"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": "火田镇"
}
],
},
version: "字典数据具体版本号"
}上述对象为接口响应数据拦截格式化后的对象。
假如接口响应数据格式不符合上述默认格式，可通过配置formatterDictList(data, dictType)来将数据格式化成默认格式。data就是接口响应拦截格式化后的data，dictType为字典请求类型的参数如SEX（兼容有些接口响应数据并未提供字典类型导致无法配置成默认格式的情况）
// 默认格式化方法
formatterDictList: (
data,
query
) => {
if (!data || !data.dictData) {
return {}
}
return data.dictData
}当返回数据的具体列表字段与默认的不一致时 可以配置 format 字段，此字段为对象，对象内包含 label、value、disabled、type、color、icon 六个字段，分别对应字典项名称、字典项值、字典项是否禁用、字典项类型、字典项颜色。树形数据还可以配置treeSetting。
format: {
value: "value", // 配置字典项值的字段
label: "label", // 配置字典项名称的字段
disabled: "disabled", // 配置字典项是否禁用的字段
type: "type", // 配置字典项类型字段
color: "color", // 配置字典项颜色字段
icon: "icon", // 配置字典项图标字段
}
//配置数组数据转化成树形数据
treeSetting: {
idField: "id", //唯一标识字段名 一般数据库以id作为父子嵌套关系的依据 因此默认值为id
parentIdField: "parentId", //父节点唯一标识字段名 一般数据库以parentId作为父子嵌套关系的依据 因此默认值为parentId
childrenField: "children", //子节点标识字段名 通过数据库一维表生成树形数据后 子元素的 字段名称配置 默认为children
firstId: "0", // 根节点值 根节点id 一般数据库以0作为根节点的id 因此默认值为0
valueField: "", // value字典名 此处不填则使用 上述 format.value字段
valueArrField: "valueArr", /* 通过一维数组生成树形数据时 顺带把value对应的层级关系 存储在数据中 免去需要用到时再去生成的步骤
如 valueArr: ["1","2","3"] 此数组就位该数据对应的层级关系数据
*/
labelField: "", //label字段名 此处不填时 则使用上述 format.label字段
labelArrField: "labelArr", /* 通过一维数组生成树形数据时 顺带把label对应的层级关系 存储在数据中 免去需要用到时再去生成的步骤
如 labelArr: ["福建省","漳州市","诏安县"] 此数组就位该数据对应的层级关系数据
*/
idArrField: "idArr", /* 通过一维数组生成树形数据时 顺带把value对应的层级关系 存储在数据中 免去需要用到时再去生成的步骤
如 idArr: ["1","2","3"] 此数组就位该数据对应的层级关系数据
*/
levelField: "level", // 通过一维数组生成树形数据时 顺带给对象新增 一个层级字段名 方便迅速知道该对象处于第几级
level: 0, // 给第一级展示的层级 默认为0
leafField: "leaf", //叶子节点标识字段名 用于方便知道此对象是否是叶子节点，方便部分需要用到的地方使用
}默认字典接口请求参数
字典包默认字典接口请求入参格式为
- 当请求入参为 {dictType: ""} 时，则请求全部字典数据
- 当请求入参为 {dictType: "字典类型1"} 时，则请求指定字典类型为1的数据
- 当请求入参为 {dictType: "字典类型1,字典类型2"} 时，则请求指定字典类型为1和2的数据
注意
当字典接口请求参数仅仅只是 dictType 不一致时，可配置 query 字段，此字段默认值为 dictType。
当字典接口请求参数完全不一致时，可配置 formatterRequest(query, dictType) 将请求参数格式化成符合字典接口请求的参数。query为您配置的query字段对应的值，没配置则默认值为"dictType"，dictType为请求的字典类型。
formatterRequest 默认配置如下
formatterRequest: (query, dictType) => {
if (!dictType) {
return { [query]: "" };
}
return { [query]: dictType };
}接口相关配置结论
字典包通过上述格式化请求参数及格式化响应结果的配置，可以轻松兼容所有类型的后端开发人员开发出来的字典接口,再也不用因为字典接口的格式问题而烦恼。
本地字典数据默认格式
本地字典数据默认格式如下
export default {
SEX: [
{
label: '男',
value: '1',
},
{
label: '女',
value: '2',
},
],
STATUS: [
{
label: 'primary',
value: '1',
type: 'primary',
},
{
label: 'danger',
value: '2',
type: 'danger',
},
{
label: 'success',
value: '3',
type: 'success',
disabled: true,
},
{
label: 'warning',
value: '4',
type: 'warning',
},
{
label: 'default',
value: '5',
type: 'default',
},
],
AREA: [
{
id: 1,
parentId: 0,
value: "350000",
label: "福建省",
},
{
id: 2,
parentId: 1,
value: "350600",
label: "漳州市",
},
{
id: 3,
parentId: 1,
value: "350624",
label: "诏安县",
},
{
id: 3,
parentId: 1,
value: "350623",
label: "云霄县",
}
]
}本地字典数据 label value等字段跟随上述 format 配置，如果配置成别的 此处必须与配置后的一致。树形结构数据的字段名 同理，跟随treeSetting配置
组件相关使用须知
内置组件同时使用了vant4组件库的多个类型的组件，内置组件为了继承每个组件的属性、事件及插槽且防止vant组件之间的属性、事件及插槽命名冲突。因此做了如下命名约定，以dict-select组件为例，dict-select组件结构大致如下：
<div>
<van-field ref="VanFieldRef">
</van-field>
<van-popup ref="VanPopupRef">
<van-picker ref="VanPickerRef"></van-picker>
</van-popup>
</div>其中 field 组件的属性、事件、插槽跟随vant4组件库的field组件配置。
popup 组件的属性、事件、插槽则在vant4组件库的popup组件配置的基础上 添加 popup- 前缀
picker 组件的属性、事件、插槽则在vant4组件库的picker组件配置的基础上 添加 picker- 前缀
且组件会显式地向父组件暴露其内部获取这些组件的方法，且命名规则也有一定规律
const VanFieldRef = ref(null)
const getVanFieldRef = () => {
return VanFieldRef.value
}
const VanPopupRef = ref(null)
const getVanPopupRef = () => {
return VanPopupRef.value
}
const VanPickerRef = ref(null)
const getVanPickerRef = () => {
return VanPickerRef.value
}
defineExpose({ getVanFieldRef, getVanPopupRef, getVanPickerRef })上述规则适用于所有内置组件，后续其他组件仅会提供代码大致结构，不提供具体组件属性、事件及插槽的配置。
注意
dict-date-range 组件 由于用到了两个 van-date-picker 组件，因此分别使用 start-date-picker- 前缀，end-date-picker 前缀做区分。
dict-time-range 组件 由于用到了两个 van-time-picker 组件，因此分别使用 start-time-picker- 前缀，end-time-picker 前缀做区分。
总结
请一定阅读并理解字典包相关配置的作用，以便更好的使用字典包。