feat: add `htmlFor` in Form.Item (#16278)

* add htmlFor in Form.Item

* update doc

components/form/FormItem.tsx

@@ -20,6 +20,7 @@ export interface FormItemProps {
   prefixCls?: string;
   className?: string;
   id?: string;
+  htmlFor?: string;
   label?: React.ReactNode;
   labelAlign?: FormLabelAlign;
   labelCol?: ColProps;
@@ -60,7 +61,7 @@ export default class FormItem extends React.Component<FormItemProps, any> {
   helpShow = false;
 
   componentDidMount() {
-    const { children, help, validateStatus } = this.props;
+    const { children, help, validateStatus, id } = this.props;
     warning(
       this.getControls(children, true).length <= 1 ||
         (help !== undefined || validateStatus !== undefined),
@@ -68,6 +69,12 @@ export default class FormItem extends React.Component<FormItemProps, any> {
       'Cannot generate `validateStatus` and `help` automatically, ' +
         'while there are more than one `getFieldDecorator` in it.',
     );
+
+    warning(
+      !id,
+      'Form.Item',
+      '`id` is deprecated for its label `htmlFor`. Please use `htmlFor` directly.',
+    );
   }
 
   getHelpMessage() {
@@ -328,7 +335,7 @@ export default class FormItem extends React.Component<FormItemProps, any> {
           labelCol: contextLabelCol,
           colon: contextColon,
         }: FormContextProps) => {
-          const { label, labelCol, labelAlign, colon, id } = this.props;
+          const { label, labelCol, labelAlign, colon, id, htmlFor } = this.props;
           const required = this.isRequired();
 
           const mergedLabelCol: ColProps =
@@ -361,7 +368,7 @@ export default class FormItem extends React.Component<FormItemProps, any> {
           return label ? (
             <Col {...mergedLabelCol} className={labelColClassName}>
               <label
-                htmlFor={id || this.getId()}
+                htmlFor={htmlFor || id || this.getId()}
                 className={labelClassName}
                 title={typeof label === 'string' ? label : ''}
                 onClick={this.onLabelClick}

components/form/__tests__/label.test.js

@@ -236,4 +236,30 @@ describe('Form', () => {
       ),
     ).toMatchSnapshot();
   });
+
+  describe('should `htmlFor` work', () => {
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    afterEach(() => {
+      errorSpy.mockReset();
+    });
+
+    afterAll(() => {
+      errorSpy.mockRestore();
+    });
+
+    it('should warning when use `id`', () => {
+      mount(<Form.Item id="bamboo" label="bamboo" />);
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Warning: [antd: Form.Item] `id` is deprecated for its label `htmlFor`. Please use `htmlFor` directly.',
+      );
+    });
+
+    it('use `htmlFor`', () => {
+      const wrapper = mount(<Form.Item htmlFor="bamboo" label="bamboo" />);
+
+      expect(wrapper.find('label').props().htmlFor).toBe('bamboo');
+    });
+  });
 });

components/form/index.en-US.md

@@ -193,17 +193,18 @@ More option at [rc-form option](https://github.com/react-component/form#option-o
 
 Note: if Form.Item has multiple children that had been decorated by `getFieldDecorator`, `help` and `required` and `validateStatus` can't be generated automatically.
 
-| Property | Description | Type | Default Value |
-| -------- | ----------- | ---- | ------------- |
-| colon | Used with `label`, whether to display `:` after label text. | boolean | true |
-| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time. | string\|ReactNode |  |
-| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | boolean | false |
-| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string\|ReactNode |  |
-| label | Label text | string\|ReactNode |  |
-| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `<Col>`. You can set on Form one time after 3.14.0. Will take FormItem's prop when both set with Form. | [object](https://ant.design/components/grid/#Col) |  |
-| required | Whether provided or not, it will be generated by the validation rule. | boolean | false |
-| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string |  |
-| wrapperCol | The layout for input controls, same as `labelCol`. You can set on Form one time after 3.14.0. Will take FormItem's prop when both set with Form. | [object](https://ant.design/components/grid/#Col) |  |
+| Property | Description | Type | Default Value | Version |
+| -------- | ----------- | ---- | ------------- | ------- |
+| colon | Used with `label`, whether to display `:` after label text. | boolean | true | |
+| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time. | string\|ReactNode | | |
+| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | boolean | false | |
+| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string\|ReactNode | | |
+| htmlFor | Set sub label `htmlFor`. | string | | 3.17.0 |
+| label | Label text | string\|ReactNode | | |
+| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `<Col>`. You can set on Form one time after 3.14.0. Will take FormItem's prop when both set with Form. | [object](https://ant.design/components/grid/#Col) | | |
+| required | Whether provided or not, it will be generated by the validation rule. | boolean | false | |
+| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string | | |
+| wrapperCol | The layout for input controls, same as `labelCol`. You can set on Form one time after 3.14.0. Will take FormItem's prop when both set with Form. | [object](https://ant.design/components/grid/#Col) | | |
 
 ### Validation Rules
 

components/form/index.zh-CN.md

@@ -195,17 +195,18 @@ validateFields(['field1', 'field2'], options, (errors, values) => {
 
 注意：一个 Form.Item 建议只放一个被 getFieldDecorator 装饰过的 child，当有多个被装饰过的 child 时，`help` `required` `validateStatus` 无法自动生成。
 
-| 参数 | 说明 | 类型 | 默认值 |
-| --- | --- | --- | --- |
-| colon | 配合 label 属性使用，表示是否显示 label 后面的冒号 | boolean | true |
-| extra | 额外的提示信息，和 help 类似，当需要错误信息和提示文案同时出现时，可以使用这个。 | string\|ReactNode |  |
-| hasFeedback | 配合 validateStatus 属性使用，展示校验状态图标，建议只配合 Input 组件使用 | boolean | false |
-| help | 提示信息，如不设置，则会根据校验规则自动生成 | string\|ReactNode |  |
-| label | label 标签的文本 | string\|ReactNode |  |
-| labelCol | label 标签布局，同 `<Col>` 组件，设置 `span` `offset` 值，如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}`。在 3.14.0 之后，你可以通过 Form 的 labelCol 进行统一设置。当和 Form 同时设置时，以 FormItem 为准。 | [object](https://ant.design/components/grid/#Col) |  |
-| required | 是否必填，如不设置，则会根据校验规则自动生成 | boolean | false |
-| validateStatus | 校验状态，如不设置，则会根据校验规则自动生成，可选：'success' 'warning' 'error' 'validating' | string |  |
-| wrapperCol | 需要为输入控件设置布局样式时，使用该属性，用法同 labelCol。在 3.14.0 之后，你可以通过 Form 的 labelCol 进行统一设置。当和 Form 同时设置时，以 FormItem 为准。 | [object](https://ant.design/components/grid/#Col) |  |
+| 参数 | 说明 | 类型 | 默认值 | 版本 |
+| --- | --- | --- | --- | --- |
+| colon | 配合 label 属性使用，表示是否显示 label 后面的冒号 | boolean | true | |
+| extra | 额外的提示信息，和 help 类似，当需要错误信息和提示文案同时出现时，可以使用这个。 | string\|ReactNode | | |
+| hasFeedback | 配合 validateStatus 属性使用，展示校验状态图标，建议只配合 Input 组件使用 | boolean | false | |
+| help | 提示信息，如不设置，则会根据校验规则自动生成 | string\|ReactNode | | |
+| htmlFor | 设置子元素 label `htmlFor` 属性 | string | | 3.17.0 |
+| label | label 标签的文本 | string\|ReactNode | | |
+| labelCol | label 标签布局，同 `<Col>` 组件，设置 `span` `offset` 值，如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}`。在 3.14.0 之后，你可以通过 Form 的 labelCol 进行统一设置。当和 Form 同时设置时，以 FormItem 为准。 | [object](https://ant.design/components/grid/#Col) | | |
+| required | 是否必填，如不设置，则会根据校验规则自动生成 | boolean | false | |
+| validateStatus | 校验状态，如不设置，则会根据校验规则自动生成，可选：'success' 'warning' 'error' 'validating' | string | | |
+| wrapperCol | 需要为输入控件设置布局样式时，使用该属性，用法同 labelCol。在 3.14.0 之后，你可以通过 Form 的 labelCol 进行统一设置。当和 Form 同时设置时，以 FormItem 为准。 | [object](https://ant.design/components/grid/#Col) | | |
 
 ### 校验规则