ProFormFields 表单项

一个表单除了 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支持 requestvalueEnum 两种方式来生成子项,用于从两项以上中选择一项
ProFormTreeSelect支持 requestvalueEnum 两种方式来生成子项,用于从两项以上中选择一项
ProFormCheckbox在 Checkbox 基础上支持了 layout,也支持 requestvalueEnum 两种方式来生成子项
ProFormRadio.Group在 Radio 基础上也支持 requestvalueEnum 两种方式来生成子项,用于单选某项,但是可以展示出来所有选项。
ProFormSlider当用户需要在数值区间/自定义区间内进行选择时,可为连续或离散值。
ProFormSwitch用于输入互斥的两个选项,一般是 true 和 false
ProFormUploadButton按钮样式的上传文件
ProFormUploadDragger区域的上传文件,一般用于突出上传文件的表单中
ProFormMoney通用金额输入组件

代码示例

表单项

查询表单

结构化数据

日期表单

上传表单

只读表单

API

ProForm 自带的 Filed ,与 valueType 基本上一一对应。

通用的属性

参数说明类型默认值
widthField 的长度,我们归纳了常用的 Field 长度以及适合的场景,支持了一些枚举 "xs" , "sm" , "md" ,"lg" , "xl"number | "xs" | "sm" | "md" | "lg" | "xl"-
tooltip会在 label 旁增加一个 icon,悬浮后展示配置的信息string | tooltipProps-
secondary是否是次要控件,只针对 LightFilter 下有效booleanfalse
allowClear支持清除,针对 LightFilter 下有效,主动设置情况下同时也会透传给 fieldPropsbooleantrue

宽度

在某些场景下,我们需要根据页面展示效果对输入框进行自适应处理,除此以外一个表单区域应默认使用定宽规则。

width info

  • XS=104px 适用于短数字、短文本或选项。
  • SM=216px 适用于较短字段录入、如姓名、电话、ID 等。
  • MD=328px 标准宽度,适用于大部分字段长度。
  • LG=440px 适用于较长字段录入,如长网址、标签组、文件路径等。
  • XL=552px 适用于长文本录入,如长链接、描述、备注等,通常搭配自适应多行输入框或定高文本域使用。

ProFormText

Input 相同。

<ProFormText name="text" label="名称" placeholder="请输入名称" fieldProps={inputProps} />

ProFormCaptcha

ProFormCaptcha 是为了支持中后台中常见的验证码功能开发的组件。

<ProFormCaptcha
fieldProps={{
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倒计时的秒数number60
captchaTextRender渲染计时的文案(timing: boolean, count: number) => React.ReactNode-

ProFormText.Password

Input.Password 相同。

<ProFormText.Password label="InputPassword" name="input-password" />

ProFormTextArea

Input.TextArea 相同。

<ProFormTextArea
name="text"
label="名称"
placeholder="请输入名称"
fieldProps={inputTextAreaProps}
/>

ProFormDigit

inputNumber 相同。它自带了一个格式化(保留 2 位小数,最小值为 0),有需要你可以关掉它。

<ProFormDigit label="InputNumber" name="input-number" min={1} max={10} />

如果要修改小数位数:

<ProFormDigit
label="InputNumber"
name="input-number"
min={1}
max={10}
fieldProps={{ precision: 0 }}
/>

ProFormDigitRange

inputNumber 类似。 它提供输入数字范围。

<ProFormDigitRange label='InputNumberRange' name='input-number-range'>

ProFormDatePicker

DatePicker 相同。

<ProFormDatePicker name="date" label="日期" />

ProFormDateTimePicker

DatePicker 相同。

<ProFormDateTimePicker name="datetime" label="日期时间" />

ProFormDateRangePicker

DatePicker.RangePicker 相同。

<ProFormDateRangePicker name="dateRange" label="日期" />

ProFormDateTimeRangePicker

DatePicker.RangePicker 相同。

<ProFormDateTimeRangePicker name="datetimeRange" label="日期时间" />

ProFormTimePicker

DatePicker 相同

<ProFormTimePicker name="time" label="时间" />
<ProFormTimePicker.RangePicker name="timeRange" label="时间区间" />

ProFormSelect

select 相同。支持了 request 和 valueEnum 两种方式来生成 options。

请求远程数据比较复杂,详细可以看这里

参数说明类型默认值
valueEnum当前列值的枚举 valueEnumRecord-
request从网络请求枚举数据()=>Promise<{label,value}>-
debounceTime防抖动时间,与 request 配合使用number-
params发起网络请求的参数,与 request 配合使用Record-
fieldPropsantd 组件的 props(form,config)=>SelectProps`| `SelectProps-

有了 options 为什么要支持 valueEnum 呢? valueEnum 可以与 table,descriptions 共用,在工程化上有优势。

<>
<ProFormSelect
name="select"
label="Select"
valueEnum={{
open: '未解决',
closed: '已解决',
}}
placeholder="Please select a country"
rules={[{ required: true, message: 'Please select your country!' }]}
/>
<ProFormSelect
name="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="姓名" />
<ProFormSelect
name="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
<ProFormSelect
name="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!' }]}
/>

ProFormTreeSelect

tree-select 相同。支持了 request 和 valueEnum 两种方式来生成 options。

请求远程数据比较复杂,详细可以看这里

参数说明类型默认值
valueEnum当前列值的枚举 valueEnumRecord-
request从网络请求枚举数据()=>Promise<{label,value}>-
debounceTime防抖动时间,与 request 配合使用number-
params发起网络请求的参数,与 request 配合使用Record-
fieldPropsantd 组件的 props(form,config)=>TreeSelectProps`| `TreeSelectProps-

有了 options 为什么要支持 valueEnum 呢? valueEnum 可以与 table,descriptions 共用,在工程化上有优势。

<ProFormTreeSelect
name="name"
placeholder="Please select"
allowClear
width={330}
secondary
request={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 args
fieldProps={{
showArrow: false,
filterTreeNode: true,
showSearch: true,
dropdownMatchSelectWidth: false,
labelInValue: true,
autoClearSearchValue: true,
multiple: true,
treeNodeFilterProp: 'title',
fieldNames: {
label: 'title',
},
}}
/>

ProFormCheckbox

请求远程数据比较复杂,详细可以看这里

checkbox 相同,但是支持了 optionslayout

参数说明类型默认值
options与 select 相同,根据 options 生成子节点,推荐使用。string[] | {label:ReactNode,value:string}[]-
layout配置 checkbox 的样子,支持垂直verticalhorizontalhorizontal | vertical-
request从网络请求枚举数据()=>Promise<{label,value}>-
params发起网络请求的参数,与 request 配合使用Record-
fieldPropsantd 组件的 props(form,config)=>CheckboxProps | CheckboxProps-
<ProFormCheckbox.Group
name="checkbox"
layout="vertical"
label="行业分布"
options={['农业', '制造业', '互联网']}
/>

ProFormRadio.Group

请求远程数据比较复杂,详细可以看这里

radio 相同,但是支持了 options

参数说明类型默认值
options与 select 相同,根据 options 生成子节点,推荐使用。string[] | {label:ReactNode,value:string}[]-
request从网络请求枚举数据()=>Promise<{label,value}>-
radioType设置是按钮模式还是 radio 模式button|radioradio
params发起网络请求的参数,与 request 配合使用Record-
fieldPropsantd 组件的 props(form,config)=>RadioProps |RadioProps-
<ProFormRadio.Group
name="radio-group"
label="Radio.Group"
options={[
{
label: 'item 1',
value: 'a',
},
{
label: 'item 2',
value: 'b',
},
{
label: 'item 3',
value: 'c',
},
]}
/>

ProFormCascader

cascader 相同,通过 filedProps 配置 cascader 的数据。

请求远程数据比较复杂,详细可以看这里

<ProFormCascader
name="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-
fieldPropsantd 组件的 props(form,config)=>CascaderProps | CascaderProps-

ProFormSwitch

switch 相同,通过 filedProps 配置 switch 的数据。

参数说明类型默认值
fieldPropsantd 组件的 props(form,config)=>SwitchProps | SwitchProps-
<ProFormSwitch name="switch" label="Switch" />

ProFormRate

参数说明类型默认值
fieldPropsantd 组件的 props(form,config)=>RateProps | RateProps-

rate 相同,通过 filedProps 配置 rate 的数据。

<ProFormRate name="rate" label="Rate" />

ProFormSlider

slider 相同,通过 filedProps 配置 slider 的数据。

参数说明类型默认值
fieldPropsantd 组件的 props(form,config)=>SliderProps | SliderProps-
<ProFormSlider
name="slider"
label="Slider"
marks={{
0: 'A',
20: 'B',
40: 'C',
60: 'D',
80: 'E',
100: 'F',
}}
/>

ProFormUploadDragger

upload 相同。预设了 Dragger 的样式,其他与 Upload 相同。

参数说明类型默认值
iconDragger 的图标ReactNodeInboxOutlined
titleDragger 的标题ReactNode'单击或拖动文件到此区域进行上传'
descriptionDragger 的描述ReactNode'支持单次或批量上传'
<ProFormUploadDragger label="Dragger" name="dragger" action="upload.do" />

ProFormUploadButton

upload 相同。预设了 Button 的样式,其他与 Upload 相同。

参数说明类型默认值
iconButton 的图标ReactNodeUploadOutlined
titleButton 的标题ReactNode单击上传
max最大上传数量, 超过最大数量就会隐藏上传按钮number-
<ProFormUploadButton label="upload" name="upload" action="upload.do" />

ProFormMoney

ProFormMoney 用于输入金额的输入框,支持根据全局国际化显示货币符号,支持输入负数、支持自定义货币符号等

<ProFormMoney
label="限制金额最小为0"
name="amount1"
locale="en-US"
initialValue={22.22}
min={0}
/>
<ProFormMoney
label="不限制金额大小"
name="amount2"
locale="en-GB"
initialValue={22.22}
/>
<ProFormMoney
label="货币符号跟随全局国际化"
name="amount3"
initialValue={22.22}
/>
<ProFormMoney
label="自定义货币符号"
name="amount4"
initialValue={22.22}
customSymbol="💰"
/>
参数说明类型默认值
locale单独设置的国际化地区值,根据不同的地区显示不同的货币符号,支持地区详见下面的地区目录stringzh-Hans-CN
customSymbol自定义金额符号string-
numberPopoverRender自定义 Popover 的值,false 可以关闭他((props: InputNumberProps, defaultText: string) => React.ReactNode)| booleanfalse
numberFormatOptionsNumberFormat 的配置,文档可以查看 mdnNumberFormatOptions-
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": "$"
"fr-FR": "€",
"pt-BR": "R$",
"ko-KR": "₩",
"id-ID": "RP",
"de-DE": "€",
"fa-IR": "تومان",
"tr-TR": "$",
"pl-PL": "zł",
}