swizzle
FormRenderVue

npmNPM downloadsNPM all downloadsPRs Welcome

一站式中后台表单解决方案

FormRenderVue 是借鉴 React 版 FormRender 实现的 Vue 版表单解决方案，具体功能介绍可详见 react 版的FormRender

安装

FormRenderVue 依赖 ant design vue，单独使用不要忘记同时安装 ant-design-vue,同时引入 ant-design-vue 的样式

npm
npm i form-render-vue3 --save
yarn
yarn add form-render-vue3
main.ts
import 'form-render-vue3/dist/style.css';

使用

换一个更复杂一点的 schema，FR 支持数据绑定、antd 的 props 透传、表单联动等一系列功能：

从 demo 中我们不难发现 FormRenderVue 的一些设计是遵循FormRender React 的设计的：

  1. 以 schema 来描述表单展示，提交方式与 antd v4 的方式类似
  2. schema 以国际标准的 JSON schema 为基础，同时能够方便使用任何 antd 的 props
  3. 通过 bind 字段，我们允许数据的双向绑定，数据展示和真实提交的数据可以根据开发需求不同（例如从服务端接口拿到不规则数据时，也能直接使用）
  4. 使用{{...}}书写表达式来完成简单的联动，值得一提的是，这里表达式支持所有 js 语法。FR 还提供自定义组件、dependencies 声明、watch 等工具用于更加复杂的定制
  5. 可以通过displayType,labelWidth等字段轻易修改展示

高级用法

组件 Props

import FR, { useForm } from 'form-render-vue';

<FR /> props

参数描述类型是否必填默认值
id表单的 id，一般用于标识一个表单的语义化名称string/number否
form表单的 form 对象如下object是
schema描述表单的 schema，详见object是
finish提交后的回调，执行 submit() 后触发(data, errors: Error[]) => void否() => {}
beforeFinish在 finish 前触发，一般用于外部校验逻辑的回填，入参是个对象，便于扩展({ data, errors, schema, ...rest }) => Error[] 或 Promise<Error[]>否() => {}
configProviderant-design-vue 的 configProvider，配置透传object否{}
widgets自定义组件，当内置组件无法满足时使用object否{}
mappingschema 与组件的映射关系表，当内置的表不满足时使用object否{}
allCollapsed对象组件是否默认折叠（全局）boolean否false
validateMessages修改默认的校验提示信息。详见下object否{}
style顶层 styleobject否{}
className顶层 classNamestring否''
globalProps全局配置object否{}
labelWidth一行展示多少列string/number否110
column一行展示多少列number否1
debounceInput是否开启输入时使用快照模式。仅建议在表单巨大且表达式非常多时开启boolean否false
debug开启 debug 模式，时时显示表单内部状态，开发的时候强烈建议打开boolean否false
size表单大小string('large' / 'small' / 'default')否'small'
displayType表单元素与 label 同行 or 分两行展示, inline 则整个展示自然顺排string('column' / 'row' / 'inline')否'column'
disabled禁用模式，全部表单元素禁用boolean否false
readOnly只读模式，一般用于预览展示，全文 text 展示boolean否false
locale展示语言，目前只支持中文、英文string('cn'/'en')否'cn'
theme展示主题string('1'/'2')否

useForm 参数

参数描述类型是否必填默认值
formData表单的初始值object否
onChange表单发生改变时触发的方法(data: formData) => void否
onValidate表单校验不成功后触发(errors: Error[]) => void否() => {}
showValidate是否显示表单校验boolean否false
logOnMount数据分析接口，表单展示完成渲染时触发logOnMount?: (stats: any) => void否() => {}
logOnSubmit数据分析接口，表单提交成功时触发，获得本次表单填写的总时长logOnSubmit?: (stats: any) => void否() => {}
removeHiddenData提交数据的时候是否去掉已经被隐藏的元素的数据，默认不隐藏boolean否false

validateMessages

Form 为验证提供了默认的错误提示信息，你可以通过配置 validateMessages 属性，修改对应的提示模板。一种常见的使用方式，是配置国际化提示信息：

const validateMessages = {
  required: '${title}是必选字段',
  // ...
};

<FormRenderVue validateMessages={validateMessages} />;

目前可以用的转义字段为 ${title}/${min}/${max}/${len}/${pattern}, 如果有更多需求请提 issue

form 方法

参数描述类型
submit触发提交流程，一般在提交按钮上使用() => void
resetFields清空表单（也会清空一些内置状态，例如校验）({formData?: any, submitData?: any, errorFields?: Error[], touchedKeys?: any[], allTouched?: boolean}) => void
errorFields表单校验错误的数组array,[{name, error: []}]
setErrorFields外部手动修改 errorFields 校验信息，用于外部校验回填(error: Error | Error[]) => void
setValues外部手动修改 formData，用于已填写的表单的数据回填(formData: any) => void
setValueByPath外部修改指定单个 field 的数据(原名 onItemChange)(path: string, value: any) => void
setSchemaByPath指定路径修改 schema(path: string, value: any) => void
setSchema指定多个路径修改 schema。注 1({ path1: value1, path2: value2 }) => void
getValues获取表单内部维护的数据 formData() => void
schema表单的 schemaobject
touchedKeys已经触碰过的 field 的数据路径string[]
removeErrorField外部手动删除某一个 path 下所有的校验信息(path: string) => void
formData表单内部维护的数据，建议使用 getValues/setValuesobject

如何速写 Schema

对于初学者来说记住 schema 所有的字段和使用方式并非易事。为了让大家能够快速上手，建议以以下的顺序尝试：

  1. 去 react 版本 Playground 逛逛，那里有从基础玩法、高级功能到完整样例的所有 schema 样例，FormRenderVue 基本参照了 FormRender 的 schema 设计， 如有不一致请提 issue

  2. 玩转一下 表单设计器，拖拖拽拽导出 schema，丢到代码里生成可用表单。本质上这是一个可视化的 schema 生成器，支持 schema 的导入 & 导出

    schema编辑器

  3. 详细的 schema 规范见 schema 的文档。同时在 vscode 上搜索 formrender 可以找到 snippets 插件，手熟起来一整页表单的 schema 弹指间完成

上次更新: