fix(Form): optimize field interception logic

RylanBot · RylanBot · commit 0d2d208a4b62 · 2025-12-05T23:08:13.000+08:00
diff --git a/packages/components/form/FormItem.tsx b/packages/components/form/FormItem.tsx
@@ -1,16 +1,16 @@
+import { get, isEqual, isFunction, isObject, isString, set, unset } from 'lodash-es';
 import React, { forwardRef, ReactNode, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import {
   CheckCircleFilledIcon as TdCheckCircleFilledIcon,
   CloseCircleFilledIcon as TdCloseCircleFilledIcon,
   ErrorCircleFilledIcon as TdErrorCircleFilledIcon,
 } from 'tdesign-icons-react';
-import { get, isEqual, isFunction, isObject, isString, set, unset } from 'lodash-es';
 
 import useConfig from '../hooks/useConfig';
 import useDefaultProps from '../hooks/useDefaultProps';
 import useGlobalIcon from '../hooks/useGlobalIcon';
 import { useLocaleReceiver } from '../locale/LocalReceiver';
-import { READONLY_SUPPORTED_COMP, ValidateStatus } from './const';
+import { NATIVE_INPUT_COMP, TD_READONLY_COMP, ValidateStatus } from './const';
 import { formItemDefaultProps } from './defaultProps';
 import { useFormContext, useFormListContext } from './FormContext';
 import { parseMessage, validate as validateModal } from './formModel';
@@ -490,41 +490,53 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
         <div className={`${classPrefix}-form__controls-content`}>
           {React.Children.map(children, (child, index) => {
             if (!child) return null;
+            if (!React.isValidElement(child)) return child;
 
-            let ctrlKey = 'value';
-            if (React.isValidElement(child)) {
-              if (child.type === FormItem) {
-                return React.cloneElement(child, {
-                  // @ts-ignore
-                  ref: (el) => {
-                    if (!el) return;
-                    innerFormItemsRef.current[index] = el;
-                  },
-                });
-              }
-              if (typeof child.type === 'object') {
-                ctrlKey = ctrlKeyMap.get(child.type) || 'value';
-              }
-              const childProps = child.props as any;
-              // @ts-ignore
-              const readOnlyKey = READONLY_SUPPORTED_COMP.includes(child?.type?.displayName) ? 'readonly' : 'readOnly';
+            const childType = child.type;
+            const isCustomComp = typeof childType === 'object' || typeof childType === 'function';
+            // @ts-ignore
+            const childName = isCustomComp ? childType.displayName : childType;
+
+            if (childName === 'FormItem') {
               return React.cloneElement(child, {
-                disabled: disabledFromContext,
-                [readOnlyKey]: readonlyFromContext,
-                ...childProps,
-                [ctrlKey]: formValue,
-                onChange: (value: any, ...args: any[]) => {
-                  const newValue = valueFormat ? valueFormat(value) : value;
-                  updateFormValue(newValue, true, true);
-                  childProps?.onChange?.call?.(null, value, ...args);
-                },
-                onBlur: (value: any, ...args: any[]) => {
-                  handleItemBlur();
-                  childProps?.onBlur?.call?.(null, value, ...args);
+                // @ts-ignore
+                ref: (el) => {
+                  if (!el) return;
+                  innerFormItemsRef.current[index] = el;
                 },
               });
             }
-            return child;
+
+            const childProps = child.props as any;
+            const readOnlyKey = TD_READONLY_COMP.includes(childName) ? 'readonly' : 'readOnly';
+            const commonProps = {
+              disabled: disabledFromContext,
+              [readOnlyKey]: readonlyFromContext,
+              ...child.props,
+            };
+
+            if (!isCustomComp && !NATIVE_INPUT_COMP.includes(childName)) {
+              return React.cloneElement(child, commonProps);
+            }
+
+            let ctrlKey = 'value';
+            if (isCustomComp) {
+              ctrlKey = ctrlKeyMap.get(childType) || 'value';
+            }
+
+            return React.cloneElement(child, {
+              ...commonProps,
+              [ctrlKey]: formValue,
+              onChange: (value: any, ...args: any[]) => {
+                const newValue = valueFormat ? valueFormat(value) : value;
+                updateFormValue(newValue, true, true);
+                childProps?.onChange?.call?.(null, value, ...args);
+              },
+              onBlur: (value: any, ...args: any[]) => {
+                handleItemBlur();
+                childProps?.onBlur?.call?.(null, value, ...args);
+              },
+            });
           })}
           {renderSuffixIcon()}
         </div>
diff --git a/packages/components/form/const.ts b/packages/components/form/const.ts
@@ -5,7 +5,7 @@ export const enum ValidateStatus {
   VALIDATING = 'validating',
 }
 
-export const READONLY_SUPPORTED_COMP = [
+export const TD_READONLY_COMP = [
   'AutoComplete',
   'Cascader',
   'Checkbox',
@@ -21,3 +21,8 @@ export const READONLY_SUPPORTED_COMP = [
   'Textarea',
   'TreeSelect',
 ];
+
+/**
+ * 原生支持 value 属性的组件
+ */
+export const NATIVE_INPUT_COMP = ['input', 'textarea', 'select', 'progress'];
diff --git a/packages/components/form/form.md b/packages/components/form/form.md
@@ -30,7 +30,6 @@
 
 创建 Form 实例，用于管理所有数据状态。
 
-
 ### Form.useWatch
 
 用于直接获取 form 中字段对应的值。
@@ -52,34 +51,64 @@ const Demo = () => {
 
 ## FAQ
 
-### 为什么被 FormItem 包裹的组件 value、defaultValue 没有效果？
+### 为什么被 FormItem 包裹的组件 `value`、`defaultValue` 没有效果？
+
+Form 的设计初衷是自动托管表单字段的 `value` 和 `onChange`，FormItem 会向包裹的第一个组件注入状态，即内部组件自身的 `defaultValue`、`value` 将被拦截，不会生效。如果需要设置初始值，应该使用 FormItem 的 `initialData`。
+
+```js
+<FormItem name="ui" label="组件库" initialData="TDesign">
+  <Input />
+</FormItem>
+```
+
+如果第一层组件不支持 `value` 属性，会导致 Form 无法接管组件的行为：
+
+```js
+// ❌ div 的 value 无意义，Form 部分 API 失效
+<FormItem name="ui" label="组件库" >
+  <div style={{ border: '1px dotted blue', padding: 5 }}>
+    <Input />
+  </div>
+</FormItem>
+```
 
-Form 组件设计的初衷是为了解放开发者配置大量的 `value`、`onChange` 受控属性，所以 Form.FormItem 被设计成需要拦截嵌套组件的受控属性，如需定义初始值请使用 `initialData` 属性。
+如果想要自定义排版样式，可以考虑下面的写法：
 
-由于 Form.FormItem 只会拦截第一层子节点的受控属性，所以如不希望 Form.FormItem 拦截受控属性希望自行管理 state 的话，可以在 Form.FormItem 下包裹一层 `div` 节点脱离 Form.FormItem 的代理，但同时也会失去 Form 组件的校验能力。
+```js
+// ✅ value 自动会传递给 input，Form 相关 API 正常
+const CustomInput = (props) => (
+  <div style={{ border: '1px dotted blue', padding: 5 }}>
+    <Input {...props} />
+  </div>
+);
+
+<FormItem name="ui" label="组件库" initialData="TDesign">
+  <CustomInput />
+</FormItem>
+```
 
 ### 我只想要 Form 组件的布局效果，校验能力我自己业务来实现可以吗？
 
-可以的，Form 的校验能力只跟 `name` 属性关联，不指定 Form.FormItem 的 `name` 属性是可以当成布局组件来使用的，甚至可以实现各种嵌套自定义内容的布局效果。
+可以的，Form 的校验能力只跟 `name` 属性关联，不指定 FormItem 的 `name` 属性是可以当成布局组件来使用的，甚至可以实现各种嵌套自定义内容的布局效果。
 
 ```js
 // 可以单独使用 FormItem 组件
-<Form.FormItem label="姓名">
+<FormItem label="姓名">
   <div>可以任意定制内容</div>
   <Input />
   <div>可以任意定制内容</div>
-</Form.FormItem>
+</FormItem>
 ```
 
-### getFieldsValue 返回的数据如何支持嵌套数据结构？
+### `getFieldsValue` 返回的数据如何支持嵌套数据结构？
 
 将 `name` 设置成数组形式可以支持嵌套数据结构。
 
 ```js
 // ['user', 'name'] => { user: { name: '' } }
-<Form.FormItem label="姓名" name={['user', 'name']}>
+<FormItem label="姓名" name={['user', 'name']}>
   <Input />
-</Form.FormItem>
+</FormItem>
 ```
 
 ## API
diff --git a/packages/components/form/hooks/useWatch.ts b/packages/components/form/hooks/useWatch.ts
@@ -1,16 +1,16 @@
-import { useState, useEffect, useMemo, useRef } from 'react';
-import { get, isUndefined } from 'lodash-es';
+import { useEffect, useState } from 'react';
+import { get, isEqual } from 'lodash-es';
+
+import noop from '../../_util/noop';
+import { HOOK_MARK } from './useForm';
+
 import type { NamePath } from '../type';
 import type { InternalFormInstance } from './interface';
-import { HOOK_MARK } from './useForm';
-import noop from '../../_util/noop';
 
 export default function useWatch(name: NamePath, form: InternalFormInstance) {
   const [value, setValue] = useState<any>();
-  const valueStr = useMemo(() => JSON.stringify(value), [value]);
-  const valueStrRef = useRef(valueStr);
 
-  // eslint-disable-next-line
+  // eslint-disable-next-line no-underscore-dangle
   const isValidForm = form && form._init;
 
   useEffect(() => {
@@ -21,22 +21,18 @@ export default function useWatch(name: NamePath, form: InternalFormInstance) {
     const cancelRegister = registerWatch(() => {
       const allFieldsValue = form.getFieldsValue?.(true);
       const newValue = get(allFieldsValue, name);
-      const nextValueStr = JSON.stringify(newValue);
-
-      // Compare stringify in case it's nest object
-      if (valueStrRef.current !== nextValueStr) {
-        valueStrRef.current = nextValueStr;
-        setValue(nextValueStr);
+      if (!isEqual(value, newValue)) {
+        setValue(newValue);
       }
     });
 
     const allFieldsValue = form.getFieldsValue?.(true);
     const initialValue = get(allFieldsValue, name);
-    setValue(JSON.stringify(initialValue));
+    setValue(initialValue);
 
     return cancelRegister;
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  return isUndefined(value) ? value : JSON.parse(value);
+  return value;
 }
diff --git a/packages/tdesign-react/site/plugins/plugin-tdoc/transforms.js b/packages/tdesign-react/site/plugins/plugin-tdoc/transforms.js
@@ -44,7 +44,8 @@ export default {
     }
 
     // 替换成对应 demo 文件
-    source = source.replace(/\{\{\s+(.+)\s+\}\}/g, (demoStr, demoFileName) => {
+    // 只匹配独立行的 {{ }} 模式，避免影响普通代码块中的内容
+    source = source.replace(/^[ \t]*\{\{\s+(.+?)\s+\}\}[ \t]*$/gm, (demoStr, demoFileName) => {
       const tsxDemoPath = path.resolve(resourceDir, `./_example/${demoFileName}.tsx`);
 
       if (!fs.existsSync(tsxDemoPath)) {

Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,8 @@ export default {`
`44`	`44`	`}`
`45`	`45`
`46`	`46`	`// 替换成对应 demo 文件`
`47`		`- source = source.replace(/\{\{\s+(.+)\s+\}\}/g, (demoStr, demoFileName) => {`
	`47`	`+ // 只匹配独立行的 {{ }} 模式，避免影响普通代码块中的内容`
	`48`	`+ source = source.replace(/^[ \t]\{\{\s+(.+?)\s+\}\}[ \t]$/gm, (demoStr, demoFileName) => {`
`48`	`49`	const tsxDemoPath = path.resolve(resourceDir, `./_example/${demoFileName}.tsx`);
`49`	`50`
`50`	`51`	`if (!fs.existsSync(tsxDemoPath)) {`