From 2e9af2513796dd4714c13d46863ddffd280e506c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=B0=A2=E6=A0=8B=E7=A5=A5?= Date: Thu, 9 Jan 2025 15:04:31 +0800 Subject: [PATCH] docs: improve English docs for ProFormFields, ProFormList and ProField MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 谢栋祥 --- packages/field/src/components/field.en-US.md | 42 ++ .../src/components/FieldSet/index.en-US.md | 468 ++++++++++++------ .../form/src/components/FieldSet/index.md | 8 +- .../form/src/components/Group/index.en-US.md | 87 +++- 4 files changed, 425 insertions(+), 180 deletions(-) create mode 100644 packages/field/src/components/field.en-US.md diff --git a/packages/field/src/components/field.en-US.md b/packages/field/src/components/field.en-US.md new file mode 100644 index 000000000000..49e441106f13 --- /dev/null +++ b/packages/field/src/components/field.en-US.md @@ -0,0 +1,42 @@ +--- +title: ProField +--- + +# ProField + +> This component is an internal component, please do not use it directly. + +It is an atomic information component that standardizes field definitions across components such as ProForm, ProTable, ProList, and Filter. + +## DEMO + + + + + + + + + + + + + +## API + +```typescript | pure +import Field from '@ant-design/pro-field'; + +return ; +``` + +### Properties + +| Parameters | Description | Type | Default Value | +| --- | --- | --- | --- | +| text | The value to be formatted | any | - | +| valueType | The type of formatting | ValueType | - | +| mode | The mode of the component | - | - | +| plain | Simplified mode | - | - | +| renderFormItem | Custom DOM rendering when `mode=update \| edit`, typically used for rendering input boxes | - | - | +| render | Custom DOM rendering when `mode=read`, purely for display purposes | - | - | diff --git a/packages/form/src/components/FieldSet/index.en-US.md b/packages/form/src/components/FieldSet/index.en-US.md index dc9ccc19f598..b1c8616c1fdb 100644 --- a/packages/form/src/components/FieldSet/index.en-US.md +++ b/packages/form/src/components/FieldSet/index.en-US.md @@ -17,48 +17,62 @@ ProFormText is the product of FormItem + Input and can be analogous to the follo ```tsx | pure const ProFormText = (props) => { return ( - - - + + ); }; ``` So the props we set for ProFormText are actually for Form.Item, and the fieldProps are for the included Input, remember. -## Demo +## Component List -### Full amount of form field +| Component | Usage Scenario | +| --- | --- | +| [ProFormText](https://ant.design/components/input-cn/#Input.Password) | Suitable for various text inputs | +| [ProFormDigit](https://ant.design/components/input-number-cn/) | Numeric input component with formatting support (default: two decimal places, minimum value: 0), formatting can be disabled if needed. | +| [ProFormText.Password](https://ant.design/components/input-cn/#Input.Password) | Suitable for password input | +| [ProFormTextArea](https://ant.design/components/input-cn/#Input.Password) | Supports multi-line text input, ideal for longer text content | +| ProFormCaptcha | Used for verification code input, typically combined with a verification code API | +| [ProFormDatePicker](https://ant.design/components/date-picker-cn/) | Date picker, suitable for selecting a single date | +| [ProFormDateTimePicker](https://ant.design/components/date-picker-cn/) | Date + Time picker, suitable for combined date and time selection scenarios | +| [ProFormDateRangePicker](https://ant.design/components/date-picker-cn/) | Date range picker, suitable for selecting a date range | +| [ProFormDateTimeRangePicker](https://ant.design/components/date-picker-cn/) | Date + Time range picker, suitable for selecting a date and time range | +| [ProFormSelect](https://ant.design/components/select-cn/) | Supports generating options using `request` and `valueEnum`, suitable for selecting one item from multiple options. | +| [ProFormTreeSelect](https://ant.design/components/tree-select-cn/) | Supports generating options using `request` and `valueEnum`, suitable for tree-structured option selection. | +| [ProFormCheckbox](https://ant.design/components/checkbox-cn/) | Supports `layout`, and options can be generated using `request` and `valueEnum` | +| [ProFormRadio.Group](https://ant.design/components/radio-cn/) | Supports generating options using `request` and `valueEnum`, suitable for single-option selection with all options displayed | +| [ProFormSlider](https://ant.design/components/slider-cn/) | Suitable for selecting values within a numeric or custom range, supports continuous and discrete values. | +| [ProFormSwitch](https://ant.design/components/switch-cn/) | Suitable for toggling between two mutually exclusive options, typically `true` and `false` | +| [ProFormUploadButton](https://ant.design/components/upload-cn/) | Button-style file uploader | +| [ProFormUploadDragger](https://ant.design/components/upload-cn/) | Drag-and-drop file uploader, commonly used in prominent upload form areas | +| ProFormMoney | General-purpose monetary input component | +| [ProFormSegmented](https://ant.design/components/segmented-cn/) | Segmented control for dividing options into sections | - +## Code examples -### Query form + - + -### Date form + - + -### Upload form + - + -### Structured data + - - -### Read-only for form field - - - -## ProForm.Item +## API ProForm comes with Filed , which basically corresponds to the valueType one by one. ### Generic properties -| parameter | description | type | default | +| Parameters | Description | Type | Default | | --- | --- | --- | --- | | width | The length of the Field, we summarize the common Field lengths and suitable scenarios, support some enumeration "xs" , "s" , "m" , "l" , "x" | `number \| "xs" \| "s" \| "m" \| "l" \| "x"` | - | | rowProps | Passed to `Row` when `grid` mode is enabled, Applies only to `ProFormGroup`, `ProFormList`, `ProFormFieldSet` | [RowProps](https://ant.design/components/grid/#Row) | { gutter: 8 } | @@ -71,7 +85,7 @@ ProForm comes with Filed , which basically corresponds to the valueType one by o In some cases, we need to adapt the input box according to the page display, except that a form area should use the fixed width rule by default. -! [width info](https://gw.alipayobjects.com/zos/antfincdn/CyJPTSL07y/1574664269794-254db9de-2574-4361-bcf1-b82c6db0c80a.png) +![width info](https://gw.alipayobjects.com/zos/alicdn/oEHLxX9DO/22.jpg) - `XS=104px` for short numbers, short text or options. - `S=216px` for shorter field entries, such as name, phone, ID, etc. @@ -96,6 +110,8 @@ Same as [Input](https://ant.design/components/input/). ProFormCaptcha is a component developed to support common CAPTCHA functionality in the middle and backend. + + ```tsx | pure ``` -| parameters | description | type | default | +| Parameters | Description | Type | Default | | --- | --- | --- | --- | | onGetCaptcha | The event to click to get the captcha, if phoneName is configured it will be injected automatically | `(phone)=>Promise` | - | | captchaProps | The props of the Get Captcha button, same as antd's props | `ButtonProps` | - | @@ -141,46 +157,6 @@ Same as [Input.Password](https://ant.design/components/input/#Input.Password). ``` -### ProFormDatePicker - -Same as [DatePicker](https://ant.design/components/date-picker/). - -```tsx | pure - -``` - -### ProFormDateTimePicker - -Same as [DatePicker](https://ant.design/components/date-picker/). - -```tsx | pure - -``` - -### ProFormDateRangePicker - -Same as [DatePicker.RangePicker](https://ant.design/components/date-picker/#RangePicker). - -```tsx | pure - -``` - -### ProFormDateTimeRangePicker - -Same as [DatePicker.RangePicker](https://ant.design/components/date-picker/#RangePicker). - -```tsx | pure - -``` - -### ProFormTimePicker - -Same as [DatePicker](https://ant.design/components/date-picker/) - -```tsx | pure - -``` - ### ProFormTextArea Same as [Input.TextArea](https://ant.design/components/input/#Input.TextArea). @@ -194,132 +170,89 @@ Same as [Input.TextArea](https://ant.design/components/input/#Input.TextArea). /> ``` -### ProFormCheckbox +### ProFormDigit -> Requesting remote data is more complicated, see \[here]\(/components/field#remote data) for details. +Same as [inputNumber](https://ant.design/components/input-number/). It comes with a formatting (retains 2 decimal places, minimum value is 0), you can turn it off if needed. -Same as [checkbox](https://ant.design/components/checkbox/), but supports `options` and `layout`. +```tsx | pure + +``` -| parameters | description | type | default | -| --- | --- | --- | --- | -| options | Same as select, generates child nodes based on options, recommended. | `string[]` \| `{label:ReactNode,value:string}[]` | - | -| layout | Configure the look of the checkbox to support vertical `vertical` and `horizontal` | `horizontal` \| `vertical` | - | +If you want to change the number of decimal places. ```tsx | pure - ``` -### ProFormRadio.Group - -> Requesting remote data is more complicated, see \[here]\(/components/field#remote data) for details. +### ProFormDigitRange -Same as [radio](https://ant.design/components/radio/) but with support for `options`. - -| parameters | description | type | default | -| --- | --- | --- | --- | -| options | Same as select, generates child nodes based on options, recommended. | `string[]` \| `{label:ReactNode,value:string}[]` | - | -| radioType | Set whether button mode or radio mode | `default` \| `button` | `default` | +Same as [inputNumber](https://ant.design/components/input-number/). It provides numeric range input. ```tsx | pure - + ``` -### ProFormSwitch +### ProFormDatePicker -Same as [switch](https://ant.design/components/switch/). +Same as [DatePicker](https://ant.design/components/date-picker/). ```tsx | pure - + ``` -### ProFormRate +### ProFormDateTimePicker -Same as [rate](https://ant.design/components/rate/). +Same as [DatePicker](https://ant.design/components/date-picker/). ```tsx | pure - + ``` -### ProFormSlider +### ProFormDateRangePicker -Same as [slider](https://ant.design/components/slider/). +Same as [DatePicker.RangePicker](https://ant.design/components/date-picker/#RangePicker). ```tsx | pure - + ``` -### ProFormUploadDragger - -Same as [upload](https://ant.design/components/upload/). Dragger style is preset, otherwise it is the same as Upload. +### ProFormDateTimeRangePicker -| Parameters | Description | Type | Default | -| --- | --- | --- | --- | -| icon | The chart of the Dragger. | `ReactNode` | InboxOutlined | -| title | Dragger's title | `ReactNode` | 'Click or drag files to this area to upload' | -| description | Dragger's description | `ReactNode` | 'Support single or bulk uploads' | +Same as [DatePicker.RangePicker](https://ant.design/components/date-picker/#RangePicker). ```tsx | pure - + ``` -### ProFormUploadButton - -Same as [upload](https://ant.design/components/upload/). The Button style is preset, otherwise it is the same as Upload. +### ProFormTimePicker -| Parameters | Description | Type | Default | -| ---------- | --------------------- | ----------- | --------------- | -| icon | The chart of Dragger. | `ReactNode` | UploadOutlined | -| title | Dragger's title | `ReactNode` | Click to upload | +Same as [DatePicker](https://ant.design/components/date-picker/) ```tsx | pure - + ``` ### ProFormSelect Same as [select](https://ant.design/components/select/). Both request and valueEnum are supported to generate options. -> Requesting remote data is more complicated, see \[here]\(/components/field#remote data) for details. +> Requesting remote data is more complicated, see [here](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params) for details. -> Why support valueEnum when you have options? valueEnum can be used with tables, descriptions, and has engineering advantages. - -| parameters | description | type | default | +| Parameters | Description | Type | Default | | --- | --- | --- | --- | | valueEnum | Enumeration of current values [valueEnum](/components/table#valueenum) | `Record` | - | | request | Enumerate data from network requests | `()=>Promise<{[key:string`\|`number]:any}>` | - | +| debounceTime | Debounce time, used in conjunction with `request` | `number` | - | +| params | Parameters for initiating network requests, used in conjunction with `request`. | `Record` | - | +| fieldProps | Props of Ant Design component | `SelectProps ` | - | + +> Why support valueEnum when you have options? valueEnum can be used with tables, descriptions, and has engineering advantages. ```tsx | pure <> @@ -349,6 +282,25 @@ Same as [select](https://ant.design/components/select/). Both request and valueE ``` +Related ProFormSelect + +```tsx | pure + + [ + { label: params.name, value: 'all' }, + { label: 'Unresolved', value: 'open' }, + { label: 'Resolved', value: 'closed' }, + { label: 'Resolving', value: 'processing' }, + ]} + /> +``` + Customize options： ```tsx | pure @@ -375,14 +327,19 @@ Customize options： Same as [tree-select](https://ant.design/components/tree-select/). Both request and valueEnum are supported to generate options. -> Requesting remote data is more complicated, see \[here]\(/components/field#remote data) for details. +> Requesting remote data is more complicated, see [here](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params) for details. -> Why support valueEnum when you have options? valueEnum can be used with tables, descriptions, and has engineering advantages. +> When using `onDropdownVisibleChange` in `fieldProps`, you need to separately manage the `open` state. For details, refer to [#8876](https://github.com/ant-design/pro-components/issues/8876) -| parameters | description | type | default | +| Parameters | Description | Type | Default | | --- | --- | --- | --- | | valueEnum | Enumeration of current values [valueEnum](/components/table#valueenum) | `Record` | - | | request | Enumerate data from network requests | `()=>Promise<{[key:string`\|`number]:any}>` | - | +| debounceTime | Debounce time, used in conjunction with `request` | `number` | - | +| params | Parameters for initiating network requests, used in conjunction with `request`. | `Record` | - | +| fieldProps | Props of Ant Design component | `TreeSelectProps` | - | + +> Why support valueEnum when you have options? valueEnum can be used with tables, descriptions, and has engineering advantages. ```tsx | pure ``` -### ProFormDigit +### ProFormCheckbox -Same as [inputNumber](https://ant.design/components/input-number/). It comes with a formatting (retains 2 decimal places, minimum value is 0), you can turn it off if needed. +> Requesting remote data is more complicated, see [here](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params) for details. + +Same as [checkbox](https://ant.design/components/checkbox/), but supports `options` and `layout`. + +| Parameters | Description | Type | Default | +| --- | --- | --- | --- | +| options | Same as select, generates child nodes based on options, recommended. | `string[]` \| `{label:ReactNode,value:string}[]` | - | +| layout | Configure the look of the checkbox to support vertical `vertical` and `horizontal` | `horizontal` \| `vertical` | - | +| request | Enumerate data from network requests | `()=>Promise<{label,value}>` | - | +| params | Parameters for initiating network requests, used in conjunction with `request`. | `Record` | - | +| fieldProps | Props of Ant Design component | `CheckboxProps` | - | ```tsx | pure - + ``` -If you want to change the number of decimal places. +### ProFormRadio.Group + +> Requesting remote data is more complicated, see [here](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params) for details. + +Same as [radio](https://ant.design/components/radio/) but with support for `options`. + +| Parameters | Description | Type | Default | +| --- | --- | --- | --- | +| options | Same as select, generates child nodes based on options, recommended. | `string[]` \| `{label:ReactNode,value:string}[]` | - | +| request | Enumerate data from network requests | `()=>Promise<{label,value}>` | - | +| radioType | Set whether button mode or radio mode | `default` \| `button` | `default` | +| params | Parameters for initiating network requests, used in conjunction with `request`. | `Record` | - | +| fieldProps | Props of Ant Design component | `RadioProps` | - | ```tsx | pure - +``` + +### ProFormCascader + +Same as [cascader](https://ant.design/components/cascader-cn/), configure Cascader data through `fieldProps`. + +> Requesting remote data is more complicated, see [here](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params) for details. + +```tsx | pure + ``` +| Parameters | Description | Type | Default | +| --- | --- | --- | --- | +| options | Similar to Cascader, generates child nodes based on options. It is recommended to use. | `string[]` \| `{label:ReactNode,value:string}[]` | - | +| request | Enumerate data from network requests | `()=>Promise<{label,value}>` | - | +| params | Parameters for initiating network requests, used in conjunction with `request`. | `Record` | - | +| fieldProps | Props of Ant Design component | `CascaderProps` | - | + +### ProFormSwitch + +Same as [switch](https://ant.design/components/switch/), configure Switch data through `fieldProps`. + +| Parameters | Description | Type | Default | +| ---------- | ----------------- | ------------- | ------ | +| fieldProps | Props of Ant Design component | `SwitchProps` | - | + +```tsx | pure + +``` + +### ProFormRate + +Same as [rate](https://ant.design/components/rate/), configure Rate data through `fieldProps`. + +| Parameters | Description | Type | Default | +| ---------- | ----------------- | ------------- | ------ | +| fieldProps | Props of Ant Design component | `RateProps` | - | + +```tsx | pure + +``` + +### ProFormSlider + +Same as [slider](https://ant.design/components/slider/), configure Slider data through `fieldProps`. + +| Parameters | Description | Type | Default | +| ---------- | ----------------- | ------------- | ------ | +| fieldProps | Props of Ant Design component | `SliderProps` | - | + +```tsx | pure + +``` + +### ProFormUploadDragger + +Same as [upload](https://ant.design/components/upload/). Dragger style is preset, otherwise it is the same as Upload. + +| Parameters | Description | Type | Default | +| --- | --- | --- | --- | +| icon | The chart of the Dragger. | `ReactNode` | InboxOutlined | +| title | Dragger's title | `ReactNode` | 'Click or drag files to this area to upload' | +| description | Dragger's description | `ReactNode` | 'Support single or bulk uploads' | + +```tsx | pure + +``` + +### ProFormUploadButton + +Same as [upload](https://ant.design/components/upload/). The Button style is preset, otherwise it is the same as Upload. + +| Parameters | Description | Type | Default | +| ---------- | --------------------- | ----------- | --------------- | +| icon | The chart of Dragger. | `ReactNode` | UploadOutlined | +| title | Dragger's title | `ReactNode` | Click to upload | +| max | Maximum upload quantity. The upload button will be hidden if the maximum quantity is exceeded | `number` | - | + +```tsx | pure + +``` + ### ProFormMoney ProFormMoney's input box for entering amounts supports the display of currency symbols based on global internationalization, negative input, custom currency symbols, and more. @@ -491,7 +601,7 @@ ProFormMoney's input box for entering amounts supports the display of currency s /> ``` -| parameters | description | type | default | +| Parameters | Description | Type | Default | | --- | --- | --- | --- | | locale | The internationalized region values set separately show different currency symbols depending on the region, as detailed in the region directory below | `string` | `zh-Hans-CN` | | customSymbol | Custom amount symbol | `string` | - | @@ -527,3 +637,47 @@ ProFormMoney's input box for entering amounts supports the display of currency s "hr-HR": "kn", } ``` + +### ProFormSegmented + +> Ant Design version needs to be >= antd\@4.20.0." + +Same as [Segmented](https://ant.design/components/segmented-cn/). Supports both `request` and `valueEnum` methods to generate options. + +> Requesting remote data is more complicated, see [here](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params) for details. + +| Parameters | Description | Type | Default | +| --- | --- | --- | --- | +| valueEnum | Enumeration of current values [valueEnum](/components/table#valueenum) | `Record` | - | +| request | Enumerate data from network requests | `()=>Promise<{[key:string`\|`number]:any}>` | - | +| debounceTime | Debounce time, used in conjunction with `request` | `number` | - | +| params | Parameters for initiating network requests, used in conjunction with `request`. | `Record` | - | +| fieldProps | Props of Ant Design component | `Segmented ` | - | + +> Why support valueEnum when you have options? valueEnum can be used with tables, descriptions, and has engineering advantages. + +```tsx | pure +<> + + + [ + { label: 'All', value: 'all' }, + { label: 'Unresolved', value: 'open' }, + { label: 'Resolved', value: 'closed' }, + { label: 'In Progress', value: 'processing' }, + ]} + rules={[{ required: true, message: 'Please select your country!' }]} + /> + +``` \ No newline at end of file diff --git a/packages/form/src/components/FieldSet/index.md b/packages/form/src/components/FieldSet/index.md index 32565abaee84..86be2bd3fa2e 100644 --- a/packages/form/src/components/FieldSet/index.md +++ b/packages/form/src/components/FieldSet/index.md @@ -282,7 +282,7 @@ ProFormCaptcha 是为了支持中后台中常见的验证码功能开发的组 联动的 ProFormSelect -````tsx | pure +```tsx | pure -```` +``` ### ProFormTreeSelect @@ -506,12 +506,12 @@ ProFormCaptcha 是为了支持中后台中常见的验证码功能开发的组 ### ProFormRate +与 [rate](https://ant.design/components/rate-cn/) 相同，通过 fieldProps 配置 rate 的数据。 + | 参数 | 说明 | 类型 | 默认值 | | ---------- | ----------------- | ----------- | ------ | | fieldProps | antd 组件的 props | `RateProps` | - | -与 [rate](https://ant.design/components/rate-cn/) 相同，通过 fieldProps 配置 rate 的数据。 - ```tsx | pure ``` diff --git a/packages/form/src/components/Group/index.en-US.md b/packages/form/src/components/Group/index.en-US.md index 078b03f67e05..01c9bb7fba0b 100644 --- a/packages/form/src/components/Group/index.en-US.md +++ b/packages/form/src/components/Group/index.en-US.md @@ -7,27 +7,13 @@ nav: title: Components --- -# ProFormFields +# Structured data -ProForm comes with a significant number of form items, which are essentially a combination of Form.Item and components. Each form item supports the `fieldProps` property to support setting the `props` of the input component. We support pass-through of `placeholder`, so you can set `placeholder` directly on the component. +We also provide components for structured data input: -Each form item also supports `readonly`, which has different read-only styles for different components, making `readonly` display more friendly compared to `disable`. The generated dom is also smaller, e.g. ProFormDigit automatically formats decimal digits. - -ProFormText is the product of FormItem + Input and can be analogous to the following code. - -```tsx | pure -const ProFormText = (props) => { - return ( - - - ReactNode` | - | | creatorRecord | Default value of a new line | `Record` | - | | creatorButtonProps | Configuration of a new line of buttons | `buttonProps & {creatorButtonText:string,position:"top"\|"bottom" }` | `{creatorButtonText:"Create a new line"}` | | label | Same as From.Item | `ReactNode` | - | @@ -84,6 +71,8 @@ ProFormList is basically the same as the [Form.List](https://ant.design/componen | copyIconProps | Copy button configuration, false to cancel | `{ Icon?: React.FC; tooltipText?: string; } \| false` | - | | deleteIconProps | Delete button configuration, false can cancel | `{ Icon?: React.FC; tooltipText?: string; } \| false` | - | | actionRender | custom action button | `(field,action,defaultActionDom,count)=>React.ReactNode[]` | - | +| onAfterAdd | Hook after adding data | `(defaultValue: StoreValue, insertIndex: number, count: number) => void` | - | +| onAfterRemove | Hook after deleting data | `(index: number, count: number) => void` | - | ### actionRef Action item instance @@ -324,3 +313,63 @@ ProFormFieldSet can combine the values of multiple children inside and store the + {({ name }) => { + return ( + + ); + }} + +``` + +## Code examples + +### Custom tooltip for delete and copy + + + +### FormList with dependent fields + + + +### Adjustable position for the create button + + + +### Forms nested within each other + + + +### Complex field dependencies + + + +### Behavior guard + + + +### Limitations on adding or deleting items + + + +### Horizontal layout + +