fast-crud 值转换完全指南:valueBuilder 与 valueResolve 双向数据转换
fast-crud 值转换完全指南:valueBuilder 与 valueResolve 双向数据转换
fast-crud 是一个面向配置的 Vue3 crud 框架,开发 crud 快如闪电。在实际项目中,你经常会遇到一个头疼的问题:后台返回的数据格式和前端组件需要的值不一致。比如数据库存的是 "a.jpg,b.jpg" 字符串,但图片组件需要数组;或者日期是时间戳,而日期组件需要 Date 对象。fast-crud 通过 valueBuilder 与 valueResolve 这对"双向数据转换"机制,让你在字段配置中优雅地解决所有值转换问题。
为什么需要值转换?
先来看两个最常见的真实场景:
| 场景 | 后台的值 | 前端组件需要的值 |
|---|---|---|
| 图片上传 | 逗号分隔的字符串 a.jpg,b.jpg |
数组 ["a.jpg", "b.jpg"] |
| 日期时间 | 时间戳或字符串 | Date / dayjs 对象 |
| 省市区选择 | province、city、county 三个字段 | 一个级联数组 |
| 角色多选 | 角色对象数组 | 角色 id 数组 |
如果没有值转换机制,你就得在页面里写一堆 watch、computed 和手动赋值逻辑,又乱又容易出 bug。fast-crud 的思路是:转换逻辑跟着字段走,写在哪里、什么时候执行,框架自动帮你安排好。
两个核心方法:一分钟理解
valueBuilder:后台值 → 前端值
valueBuilder(值构建器)负责把后台传过来的值,转换成前端组件能识别的值。
- 配置在字段根节点:在
pageRequest请求完列表数据之后执行,转换结果直接放到表格里显示,此时操作的是context.row。 - 配置在
form下:在点击"编辑"、弹出表单对话框之前执行,把行数据转换成表单组件需要的值,此时操作的是context.form。
valueResolve:前端值 → 后台值
valueResolve(值解析器)负责反向转换:在表单点击保存、提交到后台之前执行,把组件输出的值转换成后台需要的格式,此时操作的也是 context.form。
可以记一个简单公式:
builder 是"读"的时候转换,resolve 是"写"的时候转换。
完整示例:图片上传字段
下面是一个最典型的完整用法,以 imageUrl 字段为例:
const crudOptions = {
columns: {
imageUrl: {
title: '图片',
type: 'img',
// 列表展示:后台字符串 → 前端数组
valueBuilder(context) {
context.row.imageUrl = context.row.imageUrl?.split(',')
},
// 提交表单:前端数组 → 后台字符串
valueResolve(context) {
context.form.imageUrl = context.form.imageUrl?.join(',')
}
}
}
}
就这两段代码,"数据库 ↔ 页面"的双向转换就完成了,不需要任何额外的胶水代码。
form 下的独立转换:行展示和表单值不一样时
有时候,表格行里展示的值和表单里编辑的值都不相同。例如后台返回的 roles 是角色对象数组 [{roleId: 1, roleName: '管理员'}],表格里直接展示没问题,但多选框组件只需要 id 数组 [1]。
这时把转换配置在 form 下面即可:
columns: {
roles: {
form: {
// 打开编辑表单前执行:对象数组 → id数组
valueBuilder(context) {
context.form.roles = context.form.roles.map(item => item.roleId)
},
// 提交时反向转换(可选)
valueResolve(context) {
// ...
}
}
}
}
context 里有哪些参数可用?
valueBuilder 和 valueResolve 都会收到一个上下文对象 context(类型为 ValueBuilderContext),常用字段如下:
{
value: any, // 当前字段的值
key: string, // 当前字段 key
row: object, // 当前行数据(列表场景)
form: object, // 表单数据(表单场景)
index: number, // 行号
mode: string // 当前模式 add / edit / view
}
类型定义可以在这里查看:ValueBuilderContext 类型定义。
💡 小技巧:如果你不想手动写 context.row.xxx = ...,也可以直接 return 新值,框架会自动把返回值写回字段。例如日期字段常用:
valueBuilder({ value }) {
return dayjs(value) // 日期组件只能接受 dayjs 或 Date 对象
}
搜索表单也会自动转换
除了列表和表单,fast-crud 的查询框字段同样支持这两个方法:search 字段在初始化时会先从 columns 中继承 valueBuilder 和 valueResolve 配置,所以搜索条件里的值转换也能自动生效,不用重复配置。
手动触发转换:doValueBuilder / doValueResolve
框架在请求、编辑、提交等关键节点会自动执行转换。如果你在自定义逻辑中需要手动触发(比如手动 setFormData 之后),可以通过 expose 暴露的两个方法实现:
doValueBuilder(rows, columns?):对一批表格数据执行 valueBuilderdoValueResolve({ form }, columns?):对表单数据执行 valueResolve
这两个方法的实现在 use-expose.ts,表单侧的自动执行逻辑在 fs-form.vue。
常见错误与注意事项
⚠️ 新手最容易踩的坑:
- 改错了对象:字段根节点的
valueBuilder操作context.row;form下的操作context.form。写混了不会报错,但数据不生效。 - 忘记处理空值:转换前先判断
value是否存在,推荐用?.可选链,避免undefined.split is not a function这类错误。 - 双向要对称:builder 用了
split(','),resolve 就要配join(','),保证"来"和"去"格式一致。
总结
| 对比项 | valueBuilder | valueResolve |
|---|---|---|
| 方向 | 后台值 → 前端值 | 前端值 → 后台值 |
| 时机(字段根节点) | pageRequest 之后 | 表单提交之前 |
| 时机(form 下) | 打开编辑表单之前 | 表单提交之前 |
| 操作对象 | 根节点操作 row,form 下操作 form | form |
一句话记住:读数据用 builder,写数据用 resolve。掌握了这对方法,fast-crud 里所有"后台值和前端值不一致"的问题都可以一行配置解决。
更多字段复合配置请参考官方文档:columns 字段配置说明,以及 columns.md 中的 valueBuilder 章节。


