基于 ant design 的表单组件,配置化实现表单功能。
安装
npm i -S antd-form-mate
开发
$ git clone https://github.com/zpr1g/antd-form-mate.git
$ cd antd-form-mate
$ npm install
$ npm start
使用
内建类型
类型
备注
1
custom
自定义组件类型,通过 component 属性传入组件
2
date
3
time
4
datetime
5
date-range
日期范围
6
time-range
时间范围
7
datetime-range
日期时间范围
8
number
9
select
10
textarea
11
password
12
picture
内置预览组件
13
switch
14
slider
滑动输入
15
file-dragger
可拖拽文件上传
16
string
默认类型
17
check-group
多选框
18
radio-group
单选框
19
number-range
数字区间, { min?: number, max?: number }
20
cascader
级联选择
除此之外,可通过 registerComponent 方法注册组件实现类型扩展或重写除 custom 类型外的组件。
内部组件除了 switch 和 custom 外,默认宽度均为 100% 。
新增功能
日期相关
disabledPastDays - 禁用过去的日期,包含今天
disabledFutureDays - 禁用未来的日期
select
onReload - 配置后可渲染一个后置的刷新按钮
addonAfter - 自定义后置标签
文件相关
filesCountLimit - 上传文件个数限制
fileSizeLimit - 上传文件大小限制
dimensionLimit - 上传图片时,分辨率限制
checkImage - 额外判断图片上传的限制,返回错误提示
check-group 、radio-group
cols 可配置分为几列渲染
关于文件上传的函数 uploadFn ,可统一配置,也可对 file-dragger 和 picture 单独配置。内部默认转换成 base64 字符串。配置后则通过接口上传,成功直接返回图片链接即可,否者返回 falsy 值即可。此外,内部默认截取以 / 分割链接后最后一个元素为文件名,当类型为 picture 时,几乎无影响(不会显示展示)。如果为 file-dragger 时,由于需要显示展示,故可能截取的文件名不合适,可通过 postInitialValues 修改。另,由于现在内部只在初始值时自动格式化值的类型,故当通过 formMate 设值时,切记需要转换值类型。
API
FormMate 表单容器
参数
说明
类型
默认值
renderChildren
自定义 children 渲染
(children: React.ReactNode) => React.ReactNode
-
renderItem
自定义每个子项的渲染
(item: React.ReactNode, name: string | null, index?: number) => React.ReactNode
-
postInitialValues
对于内部已经处理过的初始值再次处理
Function
-
grid
由于通过 flex 布局输入项较为常见,故集成了该配置
-
formMate
继承自 Form 组件的 form 属性,用于管理表单初始值
-
type
统一设置表单中的所有类型
-
plainRender
自定义 plain 类型的渲染函数
-
关于 initialValues
为了简化使用,FormMate 组件会在内部统一转换 initialValues 且可初始值可重写,方便在实际业务场景中的使用和处理,故输入项( FormMate.Item 和 FormMate.Dynamic )必须作为 FormMate 组件的直接子组件,不能被其他组件包裹,这样才能让 FormMate 组件内部正确转换相关初始值。
直接在 FormMate 配置 initialValues ,此法需自己转换相应的值类型。由于如果要实现法二的效果,还需要保存初始值的前一个状态并做深比较,私以为过于冗余了,故保留为 Form 组件原始的 API 。
[推荐]通过 formMate 配置 initialValues 。可参考示例用法。这样就可以异步设置初始值了,如果需要重置表单,通过 formMate 调用 resetFieldsValue() 即可。此外,该方案还可以反复擦写初始值。
type 与 plainRender
配置 type 为 'plain' ,即可实现详情展示的功能,内部已初始化一个默认的对于不同类型渲染函数 defaultPlainRender ,当然也可以通过 plainRender 属性重写默认的渲染函数。
FormMate.Item 表单项
参数
说明
类型
默认值
type
上述类型
string
name
字段名
-
dense
使得 Form.Item 的 marginBottom 为 0
boolean
false
componentProps
额外的输入组件属性
-
其他属性可参考 Form.Item 组件属性,特别的 children 属性仅当类型为 custom 时可用。
FormMate.Dynamic 动态表单项
参数
说明
类型
默认值
render
判断是否渲染
(form: FormInstance) => boolean | null | undefined
-
其他属性可参考 FormMate.Item 组件属性,可配置 children 。
ConfigProvider 全局默认配置
参考类型定义即可
其他
内部使用的部分组件和函数已导出。
基础用法
import * as React from 'react';
import { Button } from 'antd';
import FormMate from 'antd-form-mate';
const BasicForm: React.FC = (props) => {
const handleFinish = (values) => {
console.log('Received values of form: ', values);
};
const handleFinishFailed = (errors) => {
console.log('Errors:', errors);
};
return (
style={{
maxWidth: 1200,
margin: '0 auto',
paddingTop: 20,
}}
labelCol={{ span: 8 }}
wrapperCol={{ span: 12 }}
onFinish={handleFinish}
onFinishFailed={handleFinishFailed}
>
type='string'
name='dynamic'
label='动态字段'
render={({ getFieldValue }) => {
return getFieldValue('name') === 'form';
}}
/>
提交
);
};
export default BasicForm;
模块化
注册新组件
可参考 antd-form-mate-location - 高德地图地理位置录入组件的注册使用。
扩展
将基于本组件实现新功能的模块称为扩展。
To Do
升级
从 v5 到 v6
使用 father 编译,而不是直接使用 webpack 打包成一个文件的方式。另外,为组件做减法,移除一些不需要内置的逻辑,减小打包体积。下面总结 v5 到 v6 的一些使用上的变化:
移除 datetime 和 datetime-range 类型,可通过 date 和 date-range 派生。
移除内置的快捷日期禁用配置。
从 v4 到 v5
表单组件升级到 antd 4.0 后,由于 initialValues 提升到 Form 组件中统一配置,且由于之前组件并没有对 Form 组件进行封装,导致了一些使用上的不便,故再次重构,旨在让整个组件的结构和使用更优雅。下面总结 v4 到 v5 的变更:
文件结构调整,使其更清晰合理
基于 Form 封装 FormMate 组件
在 FormMate 中处理表单初始值,统一字段值类型
switch -> boolean
date 相关 -> Moment
文件相关 -> UploadFile[] ,内部默认使用以 / 分割后的 url 数组的最后一个字符串作为文件名称
特别的,如果像文件相关的内部字段转换不满足实际需求,可通过 postInitialValues() 属性对内部转换的结果再次进行处理
重构表单项创建方式,使用 FormMate.Item 和 FormMate.Dynamic 组件创建
移除不必要的默认配置,如 defaultItemLayout 等,完全可以在实际场景中二次封装即可
从 v3 到 v4
根据官方的表单升级说明——从 v3 到 v4,也对本组件进行了相应的重构,v3 版本时,可不使用 Form 组件包裹生成的表单项,新版本充分利用了 Form 组件管理数据。下面总结几点本组件从 v3 到 v4 的注意事项:
移除 hidden 类型,新版表单组件通过 initialValues 统一配置初始值,当需要隐藏类型的字段时,直接添加到 initialValues 即可。
新增 dynamic 类型,可根据条件动态渲染某个字段。结合 generateFn 属性,可以快速实现本组件支持的其他类型组件的动态渲染。具体可参考 stories/BasicForm/index.tsx 。
移除 afmLocale 属性,通过 IntlProvider 配置国际化。
移除扩展 DatePicker 中的 onlyAfterToday 和 todayAndBefore 属性,使用 disabledPastDays 和 disabledFutureDays 代替。
重命名 pictureFormateLimit 属性为 pictureAccept ,并将默认值设为 'image/*' 。
移除默认文件大小为 500M 的限制。
修正笔误,配置全局属性中的 commen 改为 common
移除默认的 extra 属性:
export const defaultExtra = {
picture: '请上传图片',
};
新增 registerComponent 功能,可通过注册组件实现类型扩展或重写已有类型的组件。此外通过这种方式将 location 类型组件剥离到 antd-form-mate-location ,可单独安装使用。
新增 withCol 属性,可直接让每个组件被 Col 组件包裹。特别的,当同时使用了 withCol 功能 、 dynamic 类型和 component 字段时,切记返回组件时一定要使用 Col 组件包裹,因此,该场景下尽可能的使用 generateFn 即可避免这样繁琐的问题(如果内建组件没有需要的组件,可以试试 registerComponent )。之所以这样是由于该函数由 Form 组件去执行,当主动去调用时,form 的实例还没与 Form 绑定,会报警告:
Warning: Instance created by `useForm` is not connect to any Form element. Forget to pass `form` prop?
移除上传组件的 countLimitHint ,sizeLimitHint 和 imageLimitHint ,使用国际化的 hint 字段实现。
移除 EditableTable 组件和 addDivider 工具方法。剥离到 antd-form-mate-editable ,单独安装使用。
替换 select , check-group 和 radio-group 中选项的 text 字段,使用默认的 label 字段。