一个表单除了 Form 之外还是需要一系列的表单项,ProForm 自带了数量可观的表单项, 这些组件本质上是 Form.Item 和 组件的结合,我们可以帮他们当成一个 FormItem 来使用,并且支持各种 props
。每个表单项都支持 fieldProps
属性来支持设置输入组件的props
。 我们支持了 placeholder
的透传,你可以直接在组件上设置 placeholder
。
每个表单项同时也支持了 readonly
,不同的组件会有不同的只读样式,与 disable
相比 readonly
展示更加友好。生成的 dom 也更小,比如 ProFormDigit 会自动格式化小数位数。
ProFormText 是 FormItem + Input 的产物,可以类比于以下的代码:
const ProFormText = (props) => {return (<ProForm.Item {...props}><Input placeholder={props.placeholder} {...props.fieldProps} /></ProForm.Item>);};
所以我们给 ProFormText 设置的 props 其实是 Form.Item 的,fieldProps 才是包含的组件的,要切记。
组件 | 使用场景 |
---|---|
ProFormText | 用于输入各类文本 |
ProFormDigit | 用于输入数字,它自带了一个格式化(保留 2 位小数,最小值为 0),有需要你可以关掉它。 |
ProFormText.Password | 用于输入密码 |
ProFormTextArea | 用于输入多行文本 |
ProFormCaptcha | 用于输入验证码, 一般需要与发送验证码接口一起使用 |
ProFormDatePicker | 日期选择器用于输入日期 |
ProFormDateTimePicker | 日期+时间选择器,用于输入日期和时间 |
ProFormDateRangePicker | 日期区间选择器用于输入一个日期区间 |
ProFormDateTimeRangePicker | 日期+时间区间选择器,用于输入一个日期+时间的区间 |
ProFormSelect | 支持 request 和 valueEnum 两种方式来生成子项,用于从两项以上中选择一项 |
ProFormTreeSelect | 支持 request 和 valueEnum 两种方式来生成子项,用于从两项以上中选择一项 |
ProFormCheckbox | 在 Checkbox 基础上支持了 layout,也支持 request 和 valueEnum 两种方式来生成子项 |
ProFormRadio.Group | 在 Radio 基础上也支持 request 和 valueEnum 两种方式来生成子项,用于单选某项,但是可以展示出来所有选项。 |
ProFormSlider | 当用户需要在数值区间/自定义区间内进行选择时,可为连续或离散值。 |
ProFormSwitch | 用于输入互斥的两个选项,一般是 true 和 false |
ProFormUploadButton | 按钮样式的上传文件 |
ProFormUploadDragger | 区域的上传文件,一般用于突出上传文件的表单中 |
ProFormMoney | 通用金额输入组件 |
ProForm 自带的 Filed ,与 valueType 基本上一一对应。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
width | Field 的长度,我们归纳了常用的 Field 长度以及适合的场景,支持了一些枚举 "xs" , "sm" , "md" ,"lg" , "xl" | number | "xs" | "sm" | "md" | "lg" | "xl" | - |
rowProps | RowProps | 开启 grid 模式时传递给 Row, 仅在ProFormGroup , ProFormList , ProFormFieldSet 中有效 | { gutter: 8 } |
colProps | ColProps | 开启 grid 模式时传递给 Col | { xs: 24 } |
tooltip | 会在 label 旁增加一个 icon,悬浮后展示配置的信息 | string | tooltipProps | - |
secondary | 是否是次要控件,只针对 LightFilter 下有效 | boolean | false |
allowClear | 支持清除,针对 LightFilter 下有效,主动设置情况下同时也会透传给 fieldProps | boolean | true |
在某些场景下,我们需要根据页面展示效果对输入框进行自适应处理,除此以外一个表单区域应默认使用定宽规则。
XS=104px
适用于短数字、短文本或选项。SM=216px
适用于较短字段录入、如姓名、电话、ID 等。MD=328px
标准宽度,适用于大部分字段长度。LG=440px
适用于较长字段录入,如长网址、标签组、文件路径等。XL=552px
适用于长文本录入,如长链接、描述、备注等,通常搭配自适应多行输入框或定高文本域使用。与 Input 相同。
<ProFormText name="text" label="名称" placeholder="请输入名称" fieldProps={inputProps} />
ProFormCaptcha 是为了支持中后台中常见的验证码功能开发的组件。
<ProFormCaptchafieldProps={{size: 'large',prefix: <MailTwoTone />,}}captchaProps={{size: 'large',}}// 手机号的 name,onGetCaptcha 会注入这个值phoneName="phone"name="captcha"rules={[{required: true,message: '请输入验证码',},]}placeholder="请输入验证码"// 如果需要失败可以 throw 一个错误出来,onGetCaptcha 会自动停止// throw new Error("获取验证码错误")onGetCaptcha={async (phone) => {await waitTime(1000);message.success(`手机号 ${phone} 验证码发送成功!`);}}/>
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
onGetCaptcha | 点击获取验证码的事件,如果配置了 phoneName 会自动注入 | (phone)=>Promise<any> | - |
captchaProps | 获取验证码按钮的 props,与 antd 的 props 相同 | ButtonProps | - |
countDown | 倒计时的秒数 | number | 60 |
captchaTextRender | 渲染计时的文案 | (timing: boolean, count: number) => React.ReactNode | - |
与 Input.Password 相同。
<ProFormText.Password label="InputPassword" name="input-password" />
与 Input.TextArea 相同。
<ProFormTextAreaname="text"label="名称"placeholder="请输入名称"fieldProps={inputTextAreaProps}/>
与 inputNumber 相同。它自带了一个格式化(保留 2 位小数,最小值为 0),有需要你可以关掉它。
<ProFormDigit label="InputNumber" name="input-number" min={1} max={10} />
如果要修改小数位数:
<ProFormDigitlabel="InputNumber"name="input-number"min={1}max={10}fieldProps={{ precision: 0 }}/>
与 inputNumber 类似。 它提供输入数字范围。
<ProFormDigitRange label="InputNumberRange" name="input-number-range" />
与 DatePicker 相同。
<ProFormDatePicker name="date" label="日期" />
与 DatePicker 相同。
<ProFormDateTimePicker name="datetime" label="日期时间" />
与 DatePicker.RangePicker 相同。
<ProFormDateRangePicker name="dateRange" label="日期" />
与 DatePicker.RangePicker 相同。
<ProFormDateTimeRangePicker name="datetimeRange" label="日期时间" />
与 DatePicker 相同
<ProFormTimePicker name="time" label="时间" /><ProFormTimePicker.RangePicker name="timeRange" label="时间区间" />
与 select 相同。支持了 request 和 valueEnum 两种方式来生成 options。
请求远程数据比较复杂,详细可以看这里。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
valueEnum | 当前列值的枚举 valueEnum | Record | - |
request | 从网络请求枚举数据 | ()=>Promise<{label,value}> | - |
debounceTime | 防抖动时间,与 request 配合使用 | number | - |
params | 发起网络请求的参数,与 request 配合使用 | Record | - |
fieldProps | antd 组件的 props | (form,config)=>SelectProps`| `SelectProps | - |
有了 options 为什么要支持 valueEnum 呢? valueEnum 可以与 table,descriptions 共用,在工程化上有优势。
<><ProFormSelectname="select"label="Select"valueEnum={{open: '未解决',closed: '已解决',}}placeholder="Please select a country"rules={[{ required: true, message: 'Please select your country!' }]}/><ProFormSelectname="select2"label="Select"request={async () => [{ label: '全部', value: 'all' },{ label: '未解决', value: 'open' },{ label: '已解决', value: 'closed' },{ label: '解决中', value: 'processing' },]}placeholder="Please select a country"rules={[{ required: true, message: 'Please select your country!' }]}/></>
联动的 ProFormSelect
<ProFormText name="name" label="姓名" /><ProFormSelectname="addr"width="md"label="与 name 联动的选择器"// dependencies 的内容会注入 request 中dependencies={['name']}request={async (params) => [{ label: params.name, value: 'all' },{ label: 'Unresolved', value: 'open' },{ label: 'Resolved', value: 'closed' },{ label: 'Resolving', value: 'processing' },]}/>```自定义选项:```tsx | pure<ProFormSelectname="select"label="Select"options={[{ label: '全部', value: 'all' },{ label: '未解决', value: 'open' },{ label: '已解决', value: 'closed' },{ label: '解决中', value: 'processing' },]}fieldProps={{optionItemRender(item) {return item.label + ' - ' + item.value;},}}placeholder="Please select a country"rules={[{ required: true, message: 'Please select your country!' }]}/>
与 tree-select 相同。支持了 request 和 valueEnum 两种方式来生成 options。
请求远程数据比较复杂,详细可以看这里。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
valueEnum | 当前列值的枚举 valueEnum | Record | - |
request | 从网络请求枚举数据 | ()=>Promise<{label,value}> | - |
debounceTime | 防抖动时间,与 request 配合使用 | number | - |
params | 发起网络请求的参数,与 request 配合使用 | Record | - |
fieldProps | antd 组件的 props | (form,config)=>TreeSelectProps`| `TreeSelectProps | - |
有了 options 为什么要支持 valueEnum 呢? valueEnum 可以与 table,descriptions 共用,在工程化上有优势。
<ProFormTreeSelectname="name"placeholder="Please select"allowClearwidth={330}secondaryrequest={async () => {return [{title: 'Node1',value: '0-0',children: [{title: 'Child Node1',value: '0-0-0',},],},{title: 'Node2',value: '0-1',children: [{title: 'Child Node3',value: '0-1-0',},{title: 'Child Node4',value: '0-1-1',},{title: 'Child Node5',value: '0-1-2',},],},];}}// tree-select argsfieldProps={{showArrow: false,filterTreeNode: true,showSearch: true,dropdownMatchSelectWidth: false,labelInValue: true,autoClearSearchValue: true,multiple: true,treeNodeFilterProp: 'title',fieldNames: {label: 'title',},}}/>
请求远程数据比较复杂,详细可以看这里。
与 checkbox 相同,但是支持了 options
与 layout
。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
options | 与 select 相同,根据 options 生成子节点,推荐使用。 | string[] | {label:ReactNode,value:string}[] | - |
layout | 配置 checkbox 的样子,支持垂直vertical 和 horizontal | horizontal | vertical | - |
request | 从网络请求枚举数据 | ()=>Promise<{label,value}> | - |
params | 发起网络请求的参数,与 request 配合使用 | Record | - |
fieldProps | antd 组件的 props | (form,config)=>CheckboxProps | CheckboxProps | - |
<ProFormCheckbox.Groupname="checkbox"layout="vertical"label="行业分布"options={['农业', '制造业', '互联网']}/>
请求远程数据比较复杂,详细可以看这里。
与 radio 相同,但是支持了 options
。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
options | 与 select 相同,根据 options 生成子节点,推荐使用。 | string[] | {label:ReactNode,value:string}[] | - |
request | 从网络请求枚举数据 | ()=>Promise<{label,value}> | - |
radioType | 设置是按钮模式还是 radio 模式 | button |radio | radio |
params | 发起网络请求的参数,与 request 配合使用 | Record | - |
fieldProps | antd 组件的 props | (form,config)=>RadioProps |RadioProps | - |
<ProFormRadio.Groupname="radio-group"label="Radio.Group"options={[{label: 'item 1',value: 'a',},{label: 'item 2',value: 'b',},{label: 'item 3',value: 'c',},]}/>
与 cascader 相同,通过 filedProps 配置 cascader 的数据。
请求远程数据比较复杂,详细可以看这里。
<ProFormCascadername="area"label="区域"fieldProps={{options: [{value: 'zhejiang',label: 'Zhejiang',children: [{value: 'hangzhou',label: 'Hangzhou',children: [{value: 'xihu',label: 'West Lake',},],},],},],}}/>
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
options | 与 cascader 相同,根据 options 生成子节点,推荐使用。 | string[] | {label:ReactNode,value:string}[] | - |
request | 从网络请求枚举数据 | ()=>Promise<{label,value}> | - |
params | 发起网络请求的参数,与 request 配合使用 | Record | - |
fieldProps | antd 组件的 props | (form,config)=>CascaderProps | CascaderProps | - |
与 switch 相同,通过 filedProps 配置 switch 的数据。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
fieldProps | antd 组件的 props | (form,config)=>SwitchProps | SwitchProps | - |
<ProFormSwitch name="switch" label="Switch" />
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
fieldProps | antd 组件的 props | (form,config)=>RateProps | RateProps | - |
与 rate 相同,通过 filedProps 配置 rate 的数据。
<ProFormRate name="rate" label="Rate" />
与 slider 相同,通过 filedProps 配置 slider 的数据。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
fieldProps | antd 组件的 props | (form,config)=>SliderProps | SliderProps | - |
<ProFormSlidername="slider"label="Slider"marks={{0: 'A',20: 'B',40: 'C',60: 'D',80: 'E',100: 'F',}}/>
与 upload 相同。预设了 Dragger 的样式,其他与 Upload 相同。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
icon | Dragger 的图标 | ReactNode | InboxOutlined |
title | Dragger 的标题 | ReactNode | '单击或拖动文件到此区域进行上传' |
description | Dragger 的描述 | ReactNode | '支持单次或批量上传' |
<ProFormUploadDragger label="Dragger" name="dragger" action="upload.do" />
与 upload 相同。预设了 Button 的样式,其他与 Upload 相同。
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
icon | Button 的图标 | ReactNode | UploadOutlined |
title | Button 的标题 | ReactNode | 单击上传 |
max | 最大上传数量, 超过最大数量就会隐藏上传按钮 | number | - |
<ProFormUploadButton label="upload" name="upload" action="upload.do" />
ProFormMoney 用于输入金额的输入框,支持根据全局国际化显示货币符号,支持输入负数、支持自定义货币符号等
<ProFormMoneylabel="限制金额最小为0"name="amount1"locale="en-US"initialValue={22.22}min={0}/><ProFormMoneylabel="不限制金额大小"name="amount2"locale="en-GB"initialValue={22.22}/><ProFormMoneylabel="货币符号跟随全局国际化"name="amount3"initialValue={22.22}/><ProFormMoneylabel="自定义货币符号"name="amount4"initialValue={22.22}customSymbol="💰"/>
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
locale | 单独设置的国际化地区值,根据不同的地区显示不同的货币符号,支持地区详见下面的地区目录 | string | zh-Hans-CN |
customSymbol | 自定义金额符号 | string | - |
numberPopoverRender | 自定义 Popover 的值,false 可以关闭他 | ((props: InputNumberProps, defaultText: string) => React.ReactNode) | boolean | false |
numberFormatOptions | NumberFormat 的配置,文档可以查看 mdn | NumberFormatOptions | - |
min | 最小值 | number | - |
max | 最大值 | number | - |
{"ar-EG": "$","zh-CN": "¥","en-US": "$","en-GB": "£","vi-VN": "₫","it-IT": "€","ja-JP": "¥","es-ES": "€","ru-RU": "₽","sr-RS": "RSD","ms-MY": "RM","zh-TW": "NT$""fr-FR": "€","pt-BR": "R$","ko-KR": "₩","id-ID": "RP","de-DE": "€","fa-IR": "تومان","tr-TR": "₺","pl-PL": "zł","hr-HR": "kn",}