fast-crud 值转换完全指南:valueBuilder 与 valueResolve 双向数据转换

原创2026-10-13 23:44:372,333 阅读
文章标签:前端低代码UI组件开发工具

fast-crud 值转换完全指南:valueBuilder 与 valueResolve 双向数据转换

fast-crud 是一个面向配置的 Vue3 crud 框架,开发 crud 快如闪电。在实际项目中,你经常会遇到一个头疼的问题:后台返回的数据格式和前端组件需要的值不一致。比如数据库存的是 "a.jpg,b.jpg" 字符串,但图片组件需要数组;或者日期是时间戳,而日期组件需要 Date 对象。fast-crud 通过 valueBuilder 与 valueResolve 这对"双向数据转换"机制,让你在字段配置中优雅地解决所有值转换问题。

fast-crud crud框架整体介绍

为什么需要值转换?

先来看两个最常见的真实场景:

场景 后台的值 前端组件需要的值
图片上传 逗号分隔的字符串 a.jpg,b.jpg 数组 ["a.jpg", "b.jpg"]
日期时间 时间戳或字符串 Date / dayjs 对象
省市区选择 province、city、county 三个字段 一个级联数组
角色多选 角色对象数组 角色 id 数组

如果没有值转换机制,你就得在页面里写一堆 watch、computed 和手动赋值逻辑,又乱又容易出 bug。fast-crud 的思路是:转换逻辑跟着字段走,写在哪里、什么时候执行,框架自动帮你安排好。

fast-crud 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(',')
      }
    }
  }
}

就这两段代码,"数据库 ↔ 页面"的双向转换就完成了,不需要任何额外的胶水代码。

fast-crud 表单布局展示

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?):对一批表格数据执行 valueBuilder
  • doValueResolve({ form }, columns?):对表单数据执行 valueResolve

这两个方法的实现在 use-expose.ts,表单侧的自动执行逻辑在 fs-form.vue。

常见错误与注意事项

⚠️ 新手最容易踩的坑:

  1. 改错了对象:字段根节点的 valueBuilder 操作 context.row;form 下的操作 context.form。写混了不会报错,但数据不生效。
  2. 忘记处理空值:转换前先判断 value 是否存在,推荐用 ?. 可选链,避免 undefined.split is not a function 这类错误。
  3. 双向要对称:builder 用了 split(','),resolve 就要配 join(','),保证"来"和"去"格式一致。

总结

对比项 valueBuilder valueResolve
方向 后台值 → 前端值 前端值 → 后台值
时机(字段根节点) pageRequest 之后 表单提交之前
时机(form 下) 打开编辑表单之前 表单提交之前
操作对象 根节点操作 row,form 下操作 form form

一句话记住:读数据用 builder,写数据用 resolve。掌握了这对方法,fast-crud 里所有"后台值和前端值不一致"的问题都可以一行配置解决。

更多字段复合配置请参考官方文档:columns 字段配置说明,以及 columns.md 中的 valueBuilder 章节。

登录后查看全文
fast-crud