当前位置：首页 > article >正文

yup 使用 3 - 利用 meta 实现表单字段与表格列的统一结构配置（适配 React Table）

article 2025/9/29 3:43:42

yup 使用 3 - 利用 meta 实现表单字段与表格列的统一结构配置（适配 React Table）

Categories: Tools
Last edited time: May 11, 2025 7:45 PM
Status: Done
Tags: form validation, schema design, yup

本文介绍如何通过 Yup 的 meta() 字段，在 React 项目中实现表单字段与表格列的统一配置，适配多区域字段展示与结构共用需求。

前情提要：

yup 基础使用以及 jest 测试
yup 的基础使用，这里不会过多涉及 yup 的使用，所以对 yup 0 了解的可以看看
yup 使用 2 - 获取默认值，循环依赖，超大数字验证，本地化
和本篇内容关系不大，想要对 yup 更深入的了解一下的可以看看
[React] 如何用 Zustand 构建一个响应式 Enum Store？附 RTKQ 实战与 TS 架构落地
本篇笔记的 base code 一部分是来自于这篇笔记，主要是下面拿值的时候方便一些

之前在写完 yup 这两个系列的时候，我其实就有在考虑用 yup 处理一个问题——结合 yup 的 meta 属性，然后合并管理表单/表格的定义逻辑，这样可以更好地集中处理现有项目中，关于每一个属性的定义及实现

在经过了一系列反复测试和修改后，算是拿出了一个还可以的解决方案，故此记录一下

问题 - 重复的定义

我做的 B2B 和 B2C 的很多项目都是重表单的项目，因此从很久以前我就已经在想怎么要处理表单和结构的问题，总体来说也是经历了这么几种情况：

手写验证+自己抽离 UI 逻辑
这个是最初开始接触 React 时，在写了几个项目需求的表单后，自己琢磨出来的一套，在当时的项目里可以使用的功能。因为当时项目的需求要求 bundle 要小，需要 minimal dependency，所以很多东西都必须自己实现，也就自己造了些轮子
大体的逻辑是，每个 state 抽出来这样的逻辑：
```
const form = [{type: "str",header: "Label for this field",key: "attributeName",validations: [minLength(3), maxLength(5)],},
];
```
作为一个基础的实现，这样可以比较快的遍历整个 state，获取当前这个 field 的 type，attribute name，displayed name，完成表单的渲染，同时 validations 中也提供了一部分的验证，可以完成一些比较基础的，包括 min/max，nullable，isNotEmpty 之类的验证
这个时候的实现其实已经可以看到一些工具的影子了，只不过当时确实没有想这么多就是了
手写验证+使用工具生成表单
这已经是不同的项目了，不过因为 tech debt，整体的项目处在一种又老又新的状态。老是因为确实不少的工具——比如说 redux form，有些年头了，虽然当时用起来比较舒服，不过对于日新月异的更新来说，还是稍显疲软。新则是因为当时确实也在从 class based components 转向 functional components，并且大量的资源放在了 React 方面的重写，对于之前存在工具和验证还是采取了保留的状态
当然，我没有在这个项目停留很久，只是作为 supportive resource 帮助完成了 React 方面的 refactor 就跑路了，不过我开始慢慢意识到了，验证和结构的分离，似乎在很多项目里都存在，也是不少项目都在头疼的地方
忽略验证+手写 structure
这也是最近这些年在工作的项目，忽略验证的原因是因为所有的验证 backend 都有 cover，当时是没有考虑做前端的验证，也是属于 tech debt。之所以单独把这项目拎出来的原因，则是因为手写 structure 的部分——structure 做起来其实还是有点麻烦的，因为它需要同时支持 table 和 form 两个 level 的显示
除此之外，这个项目因为要做 multi-region support，因此每个 region 都会有对应的 structure。这也就意味着，当一个页面逻辑比较复杂的时候，它的管理难度就会直线上升：
- 对于同一个属性来说，它在 table/form 层的逻辑可能不一样
  如，在 table 层，它可能是 dropdown，但是在 form 层它可以打开一个 modal
  或者在 table 层要做最简渲染，因此 table 层不会显示该属性，但是在 form 层有足够的空间显示完整的数据，因此需要显示
- 对于不同 region 来说，显示的 attribute 也不一样
  针对这种情况，我其实已经做了一部分的 refactor，将类似 手写验证+自己抽离 UI 逻辑中的逻辑，从 array based 换成 object based，使用下来大体如下：
```
const regionA = { attributeA, attributeB, attributeC };
const regionB = { attributeA, attributeC };
```
在 component 中，则通过获取属性名称的方法进行重写，这样解决了一部分的问题——属性可以统一管理，修改显示名之类的只需要修改 base object，不需要重复 cv 多个地方，在 react 组件中的重写也比较方便，比起版本 1 来说是一个有效的提升了
但是本质上来说，重复的 declaration 还是没有办法解决，尤其是在看特定属性，在不同 region 中的表现——是否存在、是否可编辑——也非常的困难
尤其在使用 yup 后，就会发现，schema 和 structure 出现了很大的重复，这也是我现在主要想解决的问题

以上是已经有 tech debt 中的项目会遇到的问题，如果没有的话，我个人建议还是优先考虑使用 react hook form 这种已经可以原生支持 yup/zod 等 schema validators 的工具。如果确实有一个 schema/structure 需要同时支持 form 和 table 的需求，再往下看

dummy data

这里放一下页面中要渲染的数据：

const demoStudentCourseRecords = [{studentName: "Alice Johnson",studentId: "S1001",courseLevel: "beginner",timeSlot: "morning",courseTaken: ["ml"],},{studentName: "Bob Smith",studentId: "S1002",courseLevel: "intermediate",timeSlot: "afternoon",courseTaken: ["db", "stats"],},{studentName: "Charlie Lee",studentId: "S1003",courseLevel: "advanced",timeSlot: "evening",courseTaken: ["ds"],},{studentName: "Diana Wang",studentId: "S1004",courseLevel: "beginner",timeSlot: "morning",courseTaken: ["stats"],},{studentName: "Ethan Brown",studentId: "S1005",courseLevel: "intermediate",timeSlot: "evening",courseTaken: ["ml", "ds", "stats"],},
];

这里所有的 courseTaken 能和具体的课程有显著的不同，其他的都是大小写的区别，这个是缩写和全称的区别。也就是说，完整渲染的表格上，如果不能显示完整的名称，那就证明下拉框的实现出现问题了

`meta` 基础定义

这里是一些基础的 meta data，验证部分暂时略过：

export function createStudentCourseRecordSchema(courseLevels: string[],timeSlots: string[],courseList: string[],courseLevelOptions: { id: string; label: string }[],timeSlotOptions: { id: string; label: string }[],courseOptions: { id: string; label: string }[]
): yup.AnySchema {return yup.object().shape({studentName: studentNameField,studentId: studentIdField,courseLevel: yup.string().required(`${FIELD_LABELS.courseLevel} is required`).oneOf(courseLevels, `Invalid ${FIELD_LABELS.courseLevel.toLowerCase()}`).meta({label: FIELD_LABELS.courseLevel,table: { header: FIELD_LABELS.courseLevel, accessorKey: "courseLevel" },type: "enum",options: courseLevelOptions,}),timeSlot: yup.string().required(`${FIELD_LABELS.timeSlot} is required`).oneOf(timeSlots, `Invalid ${FIELD_LABELS.timeSlot.toLowerCase()}`).meta({label: FIELD_LABELS.timeSlot,table: { header: FIELD_LABELS.timeSlot, accessorKey: "timeSlot" },type: "enum",options: timeSlotOptions,}),courseTaken: yup.array().of(yup.string().oneOf(courseList, `Invalid course taken`)).min(1,`At least one ${FIELD_LABELS.courseTaken.toLowerCase()} must be selected`).required(`${FIELD_LABELS.courseTaken} is required`).meta({label: FIELD_LABELS.courseTaken,table: { header: FIELD_LABELS.courseTaken, accessorKey: "courseTaken" },type: "multi-enum",options: courseOptions,}),});
}

这里注意一下 type ： type: "enum" 和 type: "multi-enum"，分别对应的是单选和多选，这个在后面转化成 react table 时需要用到

这里也是一个比较初期的想法，因此在选择创建 createStudentCourseRecordSchema 的时候采取了传值的方法。现在的想法是，之后抽空回到 zustand 的实现，然后通过 pub/sub 的方法，在获取数据后自动 publish 相应的变化，然后让 yup 通过 subscribe 去自动更新

生成 table column

方法如下：

export function generateTableColumnsFromSchema(schema: yup.AnySchema
): ColumnDef<any, any>[] {console.log(schema);if (!schema) return [];const description = schema.describe() as ObjectSchemaDescription;if (description.type !== "object" || !description.fields) {throw new Error("Schema must be a Yup object schema.");}const fields = description.fields;const columns: ColumnDef<any, any>[] = [];for (const [_, fieldDesc] of Object.entries(fields)) {const meta = fieldDesc.meta as any;const { header, accessorKey } = meta.table;const type = meta?.type;const options = meta?.options;let cell;if (type === "enum" && options) {const optionMap = new Map(options.map((opt: any) => [opt.id, opt.label]));cell = ({ getValue }: { getValue: () => any }) => {const rawValue = getValue();return optionMap.get(rawValue) ?? rawValue;};} else if (type === "multi-enum" && options) {const optionMap = new Map(options.map((opt: any) => [opt.id, opt.label]));cell = ({ getValue }: { getValue: () => any }) => {const rawValues = getValue() as string[];if (!Array.isArray(rawValues)) return null;return rawValues.map((val) => optionMap.get(val) ?? val).join(", ");};} else {cell = ({ getValue }: { getValue: () => any }) => {const rawValue = getValue();return rawValue;};}columns.push({header,accessorKey,cell,});}return columns;
}

这里对于 cell 的处理就是依据不同的类型做的，具体是要通过 key 去获得 value。

渲染效果如下：

可以看到，所有的 course 都从缩写变成了完整的课程，这也可以证明数据获取和渲染都是没有问题的

拓展 - 动态支持

拓展部分会用到一个 package：sift，sift 实现了一种类似 mongodb 的语法，我在用的过程中发现，至少对大多数的项目来说，一个简单的 $or 用法就够了

schema 部分的拓展

代码如下：

// 更新一下 props 定义，如果要写多个 util 方法的话，可以让 AnySchema 拓展下面的 meta 部分
// 这样可以获取更好的支持
export type Region = "us" | "apac" | "eu";
export type Env = "dev" | "uat" | "prod";
export type FieldVisibility = "form" | "table" | "both";
export type Context = {env?: Env;region?: Region;fieldVisibility?: FieldVisibility;
}[];export interface IFieldMeta {label?: string;table?: {header?: string;accessorKey?: string;};type?: string;options?: { id: string; label: string }[];isAvailable?: boolean | Context;
}// ========================================export function createStudentCourseRecordSchema(courseLevels: string[],timeSlots: string[],courseList: string[],courseLevelOptions: { id: string; label: string }[],timeSlotOptions: { id: string; label: string }[],courseOptions: { id: string; label: string }[]
): yup.AnySchema {return yup.object().shape({studentName: studentNameField,studentId: studentIdField,courseLevel: yup.string().required(`${FIELD_LABELS.courseLevel} is required`).oneOf(courseLevels, `Invalid ${FIELD_LABELS.courseLevel.toLowerCase()}`).meta({label: FIELD_LABELS.courseLevel,table: { header: FIELD_LABELS.courseLevel, accessorKey: "courseLevel" },type: "enum",options: courseLevelOptions,isAvailable: [{ fieldVisibility: "form" }],}),timeSlot: yup.string().required(`${FIELD_LABELS.timeSlot} is required`).oneOf(timeSlots, `Invalid ${FIELD_LABELS.timeSlot.toLowerCase()}`).meta({label: FIELD_LABELS.timeSlot,table: { header: FIELD_LABELS.timeSlot, accessorKey: "timeSlot" },type: "enum",options: timeSlotOptions,isAvailable: [{ fieldVisibility: "both" }],}),courseTaken: yup.array().of(yup.string().oneOf(courseList, `Invalid course taken`)).min(1,`At least one ${FIELD_LABELS.courseTaken.toLowerCase()} must be selected`).required(`${FIELD_LABELS.courseTaken} is required`).meta({label: FIELD_LABELS.courseTaken,table: { header: FIELD_LABELS.courseTaken, accessorKey: "courseTaken" },type: "multi-enum",options: courseOptions,}),});
}

这里主要更新的就是类型，以及 courseLevel 和 timeSlot 的 isAvailable 部分，这一部分需要包含所有的选项，让 sift 可以去做 filter → 具体用法在下面

Context 单独抽出来是因为，这里可以不止可以用在 isAvailable 里，同样的逻辑也可以放在 isVisible, isEditable 等其他可拓展的逻辑中

这样就可以做一个非常直观且 fine grain 的控制：

当前属性在 form/table/region 中是否包含
当前属性在 form/table/region 中是否可见
当前属性在 form/table/region 中是否可变
…

如果没有设置的话，则是默认 true ，同时也支持通过 boolean 的方式强制重写，这个优先权会高于 context 的设置

util 部分的拓展

代码如下：

export function generateTableColumnsFromSchema(schema: yup.AnySchema
): ColumnDef<any, any>[] {console.log(schema);if (!schema) return [];const description = schema.describe() as ObjectSchemaDescription;if (description.type !== "object" || !description.fields) {throw new Error("Schema must be a Yup object schema.");}const fields = description.fields;const columns: ColumnDef<any, any>[] = [];for (const [_, fieldDesc] of Object.entries(fields)) {const meta = fieldDesc.meta as any;const { header, accessorKey } = meta.table;const type = meta?.type;const options = meta?.options;let cell;if (type === "enum") {const optionMap = new Map(options.map((opt: any) => [opt.id, opt.label]));cell = ({ getValue }: { getValue: () => any }) => {const rawValue = getValue();return optionMap.get(rawValue) ?? rawValue;};} else if (type === "multi-enum") {const optionMap = new Map(options.map((opt: any) => [opt.id, opt.label]));cell = ({ getValue }: { getValue: () => any }) => {const rawValues = getValue() as string[];if (!Array.isArray(rawValues)) return null;return rawValues.map((val) => optionMap.get(val) ?? val).join(", ");};} else {cell = ({ getValue }: { getValue: () => any }) => {const rawValue = getValue();return rawValue;};}let isColAvailable = true;// const currEnv = {//   region: 'us'// };const currEnv = {$or: [{ env: "dev" },{ region: "us" },{ fieldVisibility: "table" },{ fieldVisibility: "both" },],};if (meta?.isAvailable) {// 添加 typeof 的检查，保证 boolean 的优先权isColAvailable = meta.isAvailable.filter(sift(currEnv)).length > 0;}if (!isColAvailable) continue;columns.push({header,accessorKey,cell,});}return columns;
}

这里为了展示一下做的稍微简化了一些，本来的做法是写三个方法的：

第一个是 generateTableColumnsFromSchema
第二个是 generateFormFieldsFromSchema

然后二者通过 sift 过滤一下 isColAvailable ，获取一个 IFieldMeta[] 结构的 columns，传到最后集中处理逻辑的 util function 里

这里核心的修改逻辑是这个：

let isColAvailable = true;
// const currEnv = {
//   region: 'us'
// };
const currEnv = {$or: [{ env: "dev" },{ region: "us" },{ fieldVisibility: "table" },{ fieldVisibility: "both" },],
};
if (meta?.isAvailable) {// 添加 typeof 的检查，保证 boolean 的优先权isColAvailable = meta.isAvailable.filter(sift(currEnv)).length > 0;
}if (!isColAvailable) continue;

这一段代码可以实现对当前 attribute 的控制，并且，我会建议把这个 context 再分一下，分成 global context 和 local context。global context，如 region，env 这种，在特定环境下是不会变化的，这个就完全可以抽出来放到其他的 constant 或是 util 中，等到要用的时候再 extend 即可

最终渲染效果如下：

Course Level 成了一个 form only 的选项，因此在 table view 中被忽略了，而 Time Slot 则是因为会出现在 form 和 table 中得以被保留，可以正常的在页面中渲染

yup 使用 3 - 利用 meta 实现表单字段与表格列的统一结构配置（适配 React Table）