chore: Warning with defaultValue (#22571)

* add faq

* chore: Warning if Field with defaultValue

components/form/FormItem.tsx

@@ -297,6 +297,12 @@ function FormItem(props: FormItemProps): React.ReactElement {
             'Must set `name` or use render props when `dependencies` is set.',
           );
         } else if (React.isValidElement(children)) {
+          warning(
+            (children.props as any).defaultValue === undefined,
+            'Form.Item',
+            '`defaultValue` will not work on controlled Field. You should use `initialValues` of Form instead.',
+          );
+
           const childProps = { ...children.props, ...mergedControl };
 
           // We should keep user origin event handler

components/form/__tests__/index.test.js

@@ -25,10 +25,7 @@ describe('Form', () => {
   const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
 
   async function change(wrapper, index, value) {
-    wrapper
-      .find(Input)
-      .at(index)
-      .simulate('change', { target: { value } });
+    wrapper.find(Input).at(index).simulate('change', { target: { value } });
     await delay(50);
     wrapper.update();
   }
@@ -74,10 +71,7 @@ describe('Form', () => {
         );
 
         async function operate(className) {
-          wrapper
-            .find(className)
-            .last()
-            .simulate('click');
+          wrapper.find(className).last().simulate('click');
           await delay();
           wrapper.update();
         }
@@ -115,10 +109,7 @@ describe('Form', () => {
 
     it('correct onFinish values', async () => {
       async function click(wrapper, className) {
-        wrapper
-          .find(className)
-          .last()
-          .simulate('click');
+        wrapper.find(className).last().simulate('click');
         await delay();
         wrapper.update();
       }
@@ -405,22 +396,12 @@ describe('Form', () => {
     /* eslint-disable no-await-in-loop */
     for (let i = 0; i < 3; i += 1) {
       await change(wrapper, 0, '');
-      expect(
-        wrapper
-          .find('.ant-form-item-explain')
-          .first()
-          .text(),
-      ).toEqual("'name' is required");
+      expect(wrapper.find('.ant-form-item-explain').first().text()).toEqual("'name' is required");
 
       await change(wrapper, 0, 'p');
       await delay(100);
       wrapper.update();
-      expect(
-        wrapper
-          .find('.ant-form-item-explain')
-          .first()
-          .text(),
-      ).toEqual('not a p');
+      expect(wrapper.find('.ant-form-item-explain').first().text()).toEqual('not a p');
     }
     /* eslint-enable */
   });
@@ -441,12 +422,7 @@ describe('Form', () => {
 
     const wrapper = mount(<App />);
     wrapper.find('button').simulate('click');
-    expect(
-      wrapper
-        .find('.ant-form-item')
-        .first()
-        .hasClass('ant-form-item-with-help'),
-    ).toBeTruthy();
+    expect(wrapper.find('.ant-form-item').first().hasClass('ant-form-item-with-help')).toBeTruthy();
     expect(wrapper.find('.ant-form-item-explain').text()).toEqual('bamboo');
   });
 
@@ -652,4 +628,18 @@ describe('Form', () => {
     expect(renderTimes).toEqual(1);
     expect(wrapper.find('input').props().value).toEqual('a');
   });
+
+  it('warning with `defaultValue`', () => {
+    mount(
+      <Form>
+        <Form.Item name="light">
+          <input defaultValue="should warning" />
+        </Form.Item>
+      </Form>,
+    );
+
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Warning: [antd: Form.Item] `defaultValue` will not work on controlled Field. You should use `initialValues` of Form instead.',
+    );
+  });
 });

components/form/index.en-US.md

@@ -308,6 +308,10 @@ validator(rule, value, callback) => {
 
 Before Modal open, children elements do not exist in the view. You can set `forceRender` on Modal to pre-render its children. Click [here](https://codesandbox.io/s/antd-reproduction-template-ibu5c) to view an example.
 
+### 为什么 Form.Item 下的子组件 defaultValue 不生效？
+
+当你为 Form.Item 设置 `name` 属性后，子组件会转为受控模式。因而 `defaultValue` 不会生效。你需要在 Form 上通过 `initialValues` 设置默认值。
+
 <style>
   .site-form-item-icon {
     color: rgba(0, 0, 0, 0.25);

components/form/index.zh-CN.md

@@ -309,6 +309,10 @@ validator(rule, value, callback) => {
 
 这是因为你在调用 form 方法时，Modal 还未初始化导致 form 没有关联任何 Form 组件。你可以通过给 Modal 设置 `forceRender` 将其预渲染。示例点击[此处](https://codesandbox.io/s/antd-reproduction-template-ibu5c)。
 
+### 为什么 Form.Item 下的子组件 defaultValue 不生效？
+
+当你为 Form.Item 设置 `name` 属性后，子组件会转为受控模式。因而 `defaultValue` 不会生效。你需要在 Form 上通过 `initialValues` 设置默认值。
+
 <style>
   .site-form-item-icon {
     color: rgba(0, 0, 0, 0.25);