Schema 驱动:一份配置同时生成表格、搜索、表单,聊聊我写的 vue-crud-schemas

6 阅读3分钟

中后台最累的是什么?不是业务逻辑,是把同一份字段配置反复写三遍——表格列写一遍、搜索表单写一遍、编辑表单再写一遍。字段一改,三个地方跟着改,改到崩溃。

我把这个痛点抽成了一个开源库 vue-crud-schemas:一份列配置,同时驱动表格、搜索、表单。这篇文章聊聊它的设计思路。

一、先看效果

定义一个字段配置:

const columns: CrudColumn[] = [
  { field: 'name', label: '商品名称', search: true, form: true },
  {
    field: 'status', label: '状态', type: 'select',
    search: true, form: true,
    options: [{ label: '上架', value: 1 }, { label: '下架', value: 0 }],
  },
  { field: 'createdAt', label: '创建时间', type: 'datetime', form: true },
  { field: 'operation', label: '操作', type: 'slot', slot: 'operation' },
]

然后一行推导:

const schemas = useCrudSchemas(columns)
// schemas.tableColumns / searchColumns / formColumns
// schemas.searchModel / formModel

模板里三个组件直接渲染:

<SchemaSearch v-model="schemas.searchModel" :columns="schemas.searchColumns" @search="fetchData" />
<SchemaTable :columns="schemas.tableColumns" :data="list" :total="total" v-model:page="page" v-model:page-size="pageSize" />
<SchemaForm v-model="schemas.formModel" :columns="schemas.formColumns" />

表格、搜索、表单三块,从同一份配置生成,字段增删改只动一个地方。

在线 demo:lcy-24.github.io/vue-crud-sc…

二、核心:CrudColumn 数据结构

Schema 驱动的本质,是把「界面描述」抽象成「数据」。我用一个 CrudColumn 类型统一描述一个字段在三个场景下的表现:

export interface CrudColumn {
  field: string            // 字段名
  label: string            // 表头 / 表单项 label
  type?: FieldType         // 控件类型

  // 表格列
  width?: number | string
  fixed?: boolean | 'left' | 'right'
  sortable?: boolean | 'custom'
  formatter?: (row, column, value) => string
  slot?: string            // 自定义插槽名

  // 搜索
  search?: boolean
  searchType?: FieldType
  // 表单
  form?: boolean
  formType?: FieldType

  options?: SelectOption[] // select/radio/checkbox 的选项
  rules?: any[]            // 表单校验
  defaultValue?: any
}

几个设计决策:

  1. table / search / form 三个布尔开关决定字段出现在哪。默认只在表格出现;search: true 进搜索,form: true 进表单。
  2. type 是通用控件类型,searchType / formType 允许搜索和表单用不同的控件(比如表格展示纯文本,表单用日期选择器)。
  3. slot 名支持自定义渲染,表格单元格和表单项都能用具名插槽接管,灵活性兜底。

三、useCrudSchemas:配置的推导入口

export function useCrudSchemas(columns: CrudColumn[]): CrudSchemas {
  const tableColumns = columns.filter((c) => c.table !== false)
  const searchColumns = columns.filter((c) => c.search === true)
  const formColumns = columns.filter((c) => c.form === true)

  const searchModel = reactive<Record<string, any>>({})
  const formModel = reactive<Record<string, any>>({})

  for (const c of searchColumns) searchModel[c.field] = c.defaultValue ?? defaultValue(c.type)
  for (const c of formColumns) formModel[c.field] = c.defaultValue ?? defaultValue(c.type)

  return { columns, tableColumns, searchColumns, formColumns, searchModel, formModel }
}

关键点:searchModel / formModel 是 reactive 对象,直接 v-model 绑定就能用,不用额外管理状态。这一步把「配置」和「运行时状态」解耦了。

四、三个组件怎么接

SchemaTable:遍历 columns,每个字段渲染一个 el-table-column。单元格内容分三种情况:

<el-table-column v-for="col in columns" :key="col.field" :prop="col.field" :label="col.label" ...>
  
  <template v-if="col.type === 'slot' || col.slot" #default="{ row }">
    <slot :name="col.slot" :row="row" :value="row[col.field]" />
  </template>
  
  <template v-else-if="col.formatter" #default="{ row }">
    {{ col.formatter(row, col, row[col.field]) }}
  </template>
</el-table-column>

分页直接用 el-pagination,通过 update:page / update:pageSize 事件外抛,配合 v-model:page 用起来就是原生体验。

SchemaSearch / SchemaForm:核心是一个 FieldControl 组件,把 type 映射到具体控件:

<el-input v-if="type === 'input' || type === 'textarea'" ... />
<el-select v-else-if="type === 'select'" ...>...</el-select>
<el-radio-group v-else-if="type === 'radio'" ...>...</el-radio-group>
<el-date-picker v-else-if="type === 'date' || type === 'datetime'" ... />
<el-switch v-else-if="type === 'switch'" ... />

搜索和表单复用同一个 FieldControl,只是布局不同(搜索行内、表单栅格)。

五、类型安全是底线

整个库全量 TypeScript。CrudColumn、SelectOption、FieldType 全部导出,配置对象有完整提示和校验。写错字段类型,编译期就报,不用等到运行时。

六、踩过的坑

  1. 组件库的类型产物:用 vite-plugin-dts 的 rollupTypes 打包类型时,.vue 组件里 defineProps<Props>() 的本地 Props 接口会导致「无法命名」报错。最终改成 vite build 出 JS + vue-tsc 单独出声明文件,稳。
  2. Element Plus 全局组件:库内部直接用 <el-table> 这类全局标签,因此要求使用方 app.use(ElementPlus) 全局注册。README 里写清楚即可,避免 on-demand 场景下的坑。

写在最后

Schema 驱动不是新概念,但把它做得「够用、类型安全、开箱即用」是有价值的。这个库源自我在做中后台时对 shared-ui 组件库的沉淀,开源出来希望能帮到同样被 CRUD 折磨的人。

欢迎 star、提 issue、一起完善。