fix(FormList): setFields failure in nested components

RylanBot · RylanBot · commit da3a716ce9ff · 2025-10-31T17:58:27.000+08:00
diff --git a/packages/components/form/FormItem.tsx b/packages/components/form/FormItem.tsx
@@ -1,11 +1,10 @@
+import { flattenDeep, get, isEqual, isFunction, isObject, isString, merge, 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 { flattenDeep, get, isEqual, isFunction, isObject, isString, merge, set, unset } from 'lodash-es';
-import { StyledProps } from '../common';
 import useConfig from '../hooks/useConfig';
 import useDefaultProps from '../hooks/useDefaultProps';
 import useGlobalIcon from '../hooks/useGlobalIcon';
@@ -17,34 +16,40 @@ import { parseMessage, validate as validateModal } from './formModel';
 import { HOOK_MARK } from './hooks/useForm';
 import useFormItemInitialData, { ctrlKeyMap } from './hooks/useFormItemInitialData';
 import useFormItemStyle from './hooks/useFormItemStyle';
+import { calcFieldValue } from './utils';
+
+import type { StyledProps } from '../common';
 import type {
+  FieldData,
   FormInstanceFunctions,
   FormItemValidateMessage,
   FormRule,
   NamePath,
   TdFormItemProps,
+  TdFormProps,
+  ValidateTriggerType,
   ValueType,
 } from './type';
-import { calcFieldValue } from './utils';
 
 export interface FormItemProps extends TdFormItemProps, StyledProps {
   children?: React.ReactNode | React.ReactNode[] | ((form: FormInstanceFunctions) => React.ReactElement);
 }
 
 export interface FormItemInstance {
   name?: NamePath;
-  isUpdated?: boolean;
   value?: any;
-  getValue?: Function;
-  setValue?: Function;
-  setField?: Function;
-  validate?: Function;
-  resetField?: Function;
-  setValidateMessage?: Function;
-  getValidateMessage?: Function;
-  resetValidate?: Function;
-  validateOnly?: Function;
+  isUpdated?: boolean;
   isFormList?: boolean;
+  formListMapRef?: React.MutableRefObject<Map<any, any>>;
+  getValue?: () => any;
+  setValue?: (newVal: any, originalData?: any) => void;
+  setField?: (field: Omit<FieldData, 'name'>, originalData?: any) => void;
+  validate?: (trigger?: ValidateTriggerType, showErrorMessage?: boolean) => Promise<Record<string, any>>;
+  validateOnly?: (trigger?: ValidateTriggerType) => Promise<Record<string, any>>;
+  resetField?: (type?: TdFormProps['resetType']) => void;
+  setValidateMessage?: (message: FormItemValidateMessage[]) => void;
+  getValidateMessage?: FormInstanceFunctions['getValidateMessage'];
+  resetValidate?: () => void;
 }
 
 const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref) => {
@@ -108,7 +113,6 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
   const [formValue, setFormValue] = useState(() => {
     const fieldName = flattenDeep([formListName, name]);
     const storeValue = get(form?.store, fieldName);
-    // if (!storeValue && formListName) return; // TODO 针对新增空的动态表单情况，避免回填默认值
     return (
       storeValue ??
       getDefaultInitialData({
@@ -225,7 +229,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     return null;
   };
 
-  async function analysisValidateResult(trigger) {
+  async function analysisValidateResult(trigger: ValidateTriggerType) {
     const result = {
       successList: [],
       errorList: [],
@@ -262,7 +266,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     return result;
   }
 
-  async function validate(trigger = 'all', showErrorMessage?: boolean) {
+  async function validate(trigger: ValidateTriggerType = 'all', showErrorMessage?: boolean) {
     if (innerFormItemsRef.current.length) {
       return innerFormItemsRef.current.map((innerFormItem) => innerFormItem?.validate(trigger, showErrorMessage));
     }
@@ -316,7 +320,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     };
   }
 
-  async function validateOnly(trigger = 'all') {
+  async function validateOnly(trigger: ValidateTriggerType = 'all') {
     const { errorList: innerErrorList, resultList } = await analysisValidateResult(trigger);
 
     return {
@@ -331,7 +335,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     filterRules.length && validate('blur');
   }
 
-  function getResetValue(resetType: string): ValueType {
+  function getResetValue(resetType: TdFormProps['resetType']): ValueType {
     if (resetType === 'initial') {
       return getDefaultInitialData({
         children,
@@ -351,7 +355,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     return emptyValue;
   }
 
-  function resetField(type: string) {
+  function resetField(type: TdFormProps['resetType']) {
     if (typeof name === 'undefined') return;
 
     const resetType = type || resetTypeFromContext;
@@ -373,7 +377,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     setVerifyStatus(ValidateStatus.VALIDATING);
   }
 
-  function setField(field: { value?: string; status?: ValidateStatus; validateMessage?: FormItemValidateMessage }) {
+  function setField(field: Omit<FieldData, 'name'>) {
     const { value, status, validateMessage } = field;
     if (typeof status !== 'undefined') {
       setErrorList(validateMessage ? [validateMessage] : []);
diff --git a/packages/components/form/FormList.tsx b/packages/components/form/FormList.tsx
@@ -182,6 +182,7 @@ const FormList: React.FC<TdFormListProps> = (props) => {
     (): FormItemInstance => ({
       name,
       isFormList: true,
+      formListMapRef,
       getValue() {
         const formListValue = [];
         [...formListMapRef.current.values()].forEach((formItemRef) => {
@@ -214,26 +215,26 @@ const FormList: React.FC<TdFormListProps> = (props) => {
         });
       },
       // TODO 支持局部更新数据
-      setValue: (fieldData: any[], originData) => {
+      setValue: (fieldData, originalData) => {
         setListFields(
           fieldData,
           (formItemRef, data) => {
             formItemRef?.current?.setValue?.(data);
           },
-          originData,
+          originalData,
         );
       },
-      setField: (fieldData: { value?: any[]; status?: string }, originData) => {
+      setField: (fieldData, originalData) => {
         const { value, status } = fieldData;
         setListFields(
           value,
           (formItemRef, data) => {
             formItemRef?.current?.setField?.({ value: data, status });
           },
-          originData,
+          originalData,
         );
       },
-      resetField: (type: string) => {
+      resetField: (type) => {
         const resetType = type || resetTypeFromContext;
 
         if (resetType === 'initial') {
diff --git a/packages/components/form/hooks/useInstance.tsx b/packages/components/form/hooks/useInstance.tsx
@@ -1,15 +1,17 @@
-import { isEmpty, isFunction, isEqual, merge, get, set } from 'lodash-es';
+import { get, isEmpty, isEqual, isFunction, merge, set } from 'lodash-es';
 import log from '@tdesign/common-js/log/index';
+import useConfig from '../../hooks/useConfig';
+import { calcFieldValue, findFormItem, findFormItemDeep, objectToArray, travelMapFromObject } from '../utils';
+
+import type { FormItemInstance } from '../FormItem';
 import type {
-  TdFormProps,
-  FormValidateResult,
+  AllValidateResult,
   FormResetParams,
   FormValidateMessage,
-  AllValidateResult,
+  FormValidateResult,
   NamePath,
+  TdFormProps,
 } from '../type';
-import useConfig from '../../hooks/useConfig';
-import { getMapValue, objectToArray, travelMapFromObject, calcFieldValue } from '../utils';
 
 // 检测是否需要校验 默认全量校验
 function needValidate(name: NamePath, fields: string[]) {
@@ -40,7 +42,7 @@ function formatValidateResult(validateResultList) {
 
 export default function useInstance(
   props: TdFormProps,
-  formRef,
+  formRef: React.RefObject<HTMLFormElement>,
   formMapRef: React.MutableRefObject<Map<any, any>>,
   floatingFormDataRef: React.RefObject<Record<any, any>>,
 ) {
@@ -109,7 +111,7 @@ export default function useInstance(
   function getFieldValue(name: NamePath) {
     if (!name) return null;
 
-    const formItemRef = getMapValue(name, formMapRef);
+    const formItemRef = findFormItem(name, formMapRef);
     return formItemRef?.current?.getValue?.();
   }
 
@@ -130,12 +132,12 @@ export default function useInstance(
       }
     } else {
       if (!Array.isArray(nameList)) {
-        log.error('Form', '`getFieldsValue` 参数需要 Array 类型');
+        log.error('Form', 'The parameter of "getFieldsValue" must be an array');
         return {};
       }
 
       nameList.forEach((name) => {
-        const formItemRef = getMapValue(name, formMapRef);
+        const formItemRef = findFormItem(name, formMapRef);
         if (!formItemRef) return;
 
         const fieldValue = calcFieldValue(name, formItemRef?.current.getValue?.());
@@ -175,13 +177,15 @@ export default function useInstance(
 
   // 对外方法，设置对应 formItem 的数据
   function setFields(fields = []) {
-    if (!Array.isArray(fields)) throw new Error('setFields 参数需要 Array 类型');
+    if (!Array.isArray(fields)) throw new TypeError('The parameter of "setFields" must be an array');
 
     fields.forEach((field) => {
       const { name, ...restFields } = field;
-      const formItemRef = getMapValue(name, formMapRef);
-
-      formItemRef?.current?.setField(restFields, field);
+      let formItemRef = findFormItem(name, formMapRef);
+      if (!formItemRef) {
+        formItemRef = findFormItemDeep(name, formMapRef);
+      }
+      formItemRef?.current?.setField(restFields);
     });
   }
 
@@ -196,7 +200,7 @@ export default function useInstance(
       const { type = 'initial', fields = [] } = params;
 
       fields.forEach((name) => {
-        const formItemRef = getMapValue(name, formMapRef);
+        const formItemRef = findFormItem(name, formMapRef);
         formItemRef?.current?.resetField(type);
       });
     }
@@ -211,10 +215,10 @@ export default function useInstance(
         formItemRef?.current?.resetValidate();
       });
     } else {
-      if (!Array.isArray(fields)) throw new Error('clearValidate 参数需要 Array 类型');
+      if (!Array.isArray(fields)) throw new TypeError('The parameter of "clearValidate" must be an array');
 
       fields.forEach((name) => {
-        const formItemRef = getMapValue(name, formMapRef);
+        const formItemRef = findFormItem(name, formMapRef);
         formItemRef?.current?.resetValidate();
       });
     }
@@ -229,25 +233,30 @@ export default function useInstance(
 
   // 对外方法，获取 formItem 的错误信息
   function getValidateMessage(fields?: Array<keyof FormData>) {
-    const message = {};
+    const formItemRefs =
+      typeof fields === 'undefined'
+        ? [...formMapRef.current.values()]
+        : fields.map((name) => findFormItem(name, formMapRef)).filter(Boolean);
 
-    if (typeof fields === 'undefined') {
-      [...formMapRef.current.values()].forEach((formItemRef) => {
-        const item = formItemRef?.current?.getValidateMessage?.();
-        if (isEmpty(item)) return;
-        message[formItemRef?.current?.name] = item;
-      });
-    } else {
-      if (!Array.isArray(fields)) throw new Error('getValidateMessage 参数需要 Array 类型');
-
-      fields.forEach((name) => {
-        const formItemRef = getMapValue(name, formMapRef);
-        const item = formItemRef?.current?.getValidateMessage?.();
-        if (isEmpty(item)) return;
-        message[formItemRef?.current?.name] = item;
-      });
+    if (typeof fields !== 'undefined' && !Array.isArray(fields)) {
+      throw new TypeError('The parameter of "getValidateMessage" must be an array');
     }
 
+    const extractValidateMessage = (formItemRef: React.RefObject<FormItemInstance>) => {
+      const item = formItemRef?.current?.getValidateMessage?.();
+      if (isEmpty(item)) return null;
+      const nameKey = Array.isArray(formItemRef?.current?.name)
+        ? formItemRef?.current?.name.join('.')
+        : String(formItemRef?.current?.name);
+      return { nameKey, item };
+    };
+
+    const message = {};
+    formItemRefs.forEach((formItemRef) => {
+      const result = extractValidateMessage(formItemRef);
+      if (result) message[result.nameKey] = result.item;
+    });
+
     if (isEmpty(message)) return;
 
     return message;
diff --git a/packages/components/form/type.ts b/packages/components/form/type.ts
@@ -447,7 +447,7 @@ export interface FormResetParams<FormData> {
 
 export interface FieldData {
   name: NamePath;
-  value?: unknown;
+  value?: any;
   status?: string;
   validateMessage?: { type?: string; message?: string };
 }
diff --git a/packages/components/form/utils/index.ts b/packages/components/form/utils/index.ts
@@ -1,10 +1,16 @@
-import { has, get, isObject, isArray, isEmpty } from 'lodash-es';
+import { get, has, isArray, isEmpty, isObject } from 'lodash-es';
+import type { FormItemInstance } from '../FormItem';
 import type { NamePath } from '../type';
 
-// 获取 formMap 管理的数据
-export function getMapValue(name: NamePath, formMapRef: React.MutableRefObject<Map<any, any>>) {
+/**
+ * 在 `formMap` 中查找指定的 `FormItem`
+ * (仅查找当前层级)
+ */
+export function findFormItem(
+  name: NamePath,
+  formMapRef: React.MutableRefObject<Map<any, any>>,
+): React.RefObject<FormItemInstance> | undefined {
   if (!formMapRef.current) return;
-
   // 提取所有 map key
   const mapKeys = [...formMapRef.current.keys()];
   // 转译为字符串后比对 key 兼容数组格式
@@ -13,6 +19,29 @@ export function getMapValue(name: NamePath, formMapRef: React.MutableRefObject<M
   return formMapRef.current.get(key);
 }
 
+/**
+ * 在 `formMap` 中查找指定的 `FormItem`
+ * (包括在嵌套的 FormList 中递归查找）
+ */
+export function findFormItemDeep(
+  name: NamePath,
+  formMapRef: React.MutableRefObject<Map<any, any>>,
+): React.RefObject<FormItemInstance> | undefined {
+  if (!formMapRef?.current) return;
+  const targetPath = Array.isArray(name) ? name : [name];
+  for (const [key, ref] of formMapRef.current.entries()) {
+    const formItem = ref?.current;
+    if (!formItem?.isFormList || !formItem.formListMapRef) continue;
+    const { formListMapRef } = formItem;
+    for (const [itemKey, itemRef] of formListMapRef.current.entries()) {
+      const fullPath = [key, itemKey].flat();
+      if (String(fullPath) === String(targetPath)) return itemRef;
+    }
+    const found = findFormItemDeep(name, formListMapRef);
+    if (found) return found;
+  }
+}
+
 // { user: { name: '' } } => [['user', 'name']]
 // 不处理数组类型
 // { user: [{ name: '' }]} => [['user']]

Original file line number	Diff line number	Diff line change
`@@ -447,7 +447,7 @@ export interface FormResetParams<FormData> {`
`447`	`447`
`448`	`448`	`export interface FieldData {`
`449`	`449`	`name: NamePath;`
`450`		`- value?: unknown;`
	`450`	`+ value?: any;`
`451`	`451`	`status?: string;`
`452`	`452`	`validateMessage?: { type?: string; message?: string };`
`453`	`453`	`}`