FastForm 配置驱动表单

通过一份 schema 配置描述表单结构，自动渲染对应控件、栅格布局与校验规则，免去手写大量 c-form-item 的重复劳动。底层基于 c-form / c-form-item 实现。

基础用法

传入 model（数据对象）与 schema（表单结构）即可。控件的值会自动双向写回 model，无需为每个字段手写 v-model。

全部控件类型

下面演示了 schema 支持的全部内置控件。select / radio / checkbox / cascader 通过 options 提供选项，treeselect 通过 props.data 提供树数据。

表单校验

设置 required: true 会自动追加一条必填规则；更复杂的规则通过 rules 配置，结构与 c-form-item 的 rules 一致。通过组件实例的 validate() 方法触发校验，返回 Promise<boolean>。

栅格布局

通过表单级 span（默认 24，即整行）与每项的 span 控制列宽（取值 1-24），配合 gutter 设置列间距，可轻松实现多列表单。单项的 span 会覆盖表单级默认值。

联动控制

disabled 与 hidden 支持函数式写法，入参为当前 model，可据此实现表单项之间的联动显隐 / 禁用。下例中“会员编号”仅在开启 VIP 时显示，“门店”仅在渠道为线下时可填。

自定义插槽

当内置控件无法满足需求时，将 type 设为 slot，并通过 slot 指定插槽名（默认取 field）。插槽作用域提供 item、model、value，可在其中渲染任意自定义内容。

内置操作区

设置 show-actions 显示内置的提交 / 重置按钮。点击提交会先校验，通过后触发 submit 事件并携带表单数据；点击重置会清空字段、恢复默认值并触发 reset 事件。按钮文案可通过 submit-text / reset-text 自定义，show-reset 可隐藏重置按钮。

实例方法

通过 ref 获取组件实例，调用暴露的方法进行校验、重置、清空校验或读取数据。

控件类型映射

type 支持以下取值，分别渲染不同的底层组件：

type	渲染组件	选项来源	说明
input	c-input	—	文本输入框
textarea	c-input	—	多行文本
password	c-input	—	密码框（带显隐切换）
number	c-input	—	数字输入框
select	c-select	options	下拉选择
radio	c-radio-group	options	单选组
checkbox	c-checkbox-group	options	多选组
switch	c-switch	—	开关
date	c-date-picker	—	日期选择
daterange	c-date-range-picker	—	日期范围
cascader	c-cascader	options	级联选择
treeselect	c-tree-select	props.data	树形选择
rate	c-rate	—	评分
color	c-color-picker	—	颜色选择
slot	—	—	自定义插槽

控件的专属属性通过表单项的 props 透传，原生事件通过 on 透传：

{
  field: "tel",
  type: "input",
  label: "电话",
  props: { clearable: true, maxlength: 11 },   // 透传给 c-input 的 props
  on: { blur: () => console.log("失焦") },      // 透传给 c-input 的事件
}

API

Props

属性	说明	类型	默认值
model	表单数据对象	Record<string, any>	{}
schema	表单结构配置	FastFormItem[]	[]
label-width	标签宽度	string | number	'100px'
label-position	标签位置	'left' | 'right' | 'top'	'right'
size	控件尺寸	'large' | 'default' | 'small'	'default'
disabled	是否整体禁用	boolean	false
gutter	栅格列间距	number	0
span	默认每项占据的栅格列数	number	24
show-actions	是否显示内置操作区	boolean	false
show-reset	是否显示重置按钮	boolean	true
submit-text	提交按钮文案	string	'提交'
reset-text	重置按钮文案	string	'重置'

FastFormItem 配置项

字段	说明	类型
field	字段名，对应 model 中的 key	string
type	控件类型	FastFormItemType
label	标签文本	string
placeholder	占位提示	string
defaultValue	默认值（model 中无该字段时写入）	any
required	快捷必填（自动追加一条 required 规则）	boolean
rules	校验规则，透传给 FormItem	FormRule | FormRule[]
options	选项数据（select/radio/checkbox/cascader）	FastFormOption[]
props	透传给底层控件的 props	Record<string, any>
on	透传给底层控件的事件	Record<string, Function>
span	栅格列宽（1-24）	number
labelWidth	单独设置标签宽度	string | number
slot	type 为 slot 时的插槽名（默认取 field）	string
disabled	是否禁用，支持函数式联动	boolean | ((model) => boolean)
hidden	是否隐藏，支持函数式联动	boolean | ((model) => boolean)

FastFormOption

字段	说明	类型
label	选项文本	string
value	选项值	string | number | boolean
disabled	是否禁用	boolean

Events

事件名	说明	回调参数
change	任意字段变更	(field: string, value: any, model: object)
submit	校验通过后提交	(model: object)
validate-error	校验失败	(errors: any[])
reset	重置	—

实例方法（Expose）

方法	说明	签名
validate	校验整个表单	() => Promise<boolean>
validateField	校验单个字段	(field: string) => Promise<boolean>
clearValidate	清空校验状态	(fields?: string | string[]) => void
resetFields	重置字段并恢复默认值	() => void
getModel	获取当前表单数据	() => Record<string, any>
formRef	底层 CForm 实例	Ref

Slots

插槽名	说明	作用域参数
自定义插槽名	由 type: 'slot' 的表单项 slot 字段指定	{ item, model, value }