feat(form): add getValidateMessage api

re #2885
Tencent · Nov 14, 2024 · 2ad0d1d · 2ad0d1d
1 parent 683e359
commit 2ad0d1d
Show file tree

Hide file tree

Showing 6 changed files with 42 additions and 0 deletions.
diff --git a/src/form/FormItem.tsx b/src/form/FormItem.tsx
@@ -45,6 +45,7 @@ export interface FormItemInstance {
   validate?: Function;
   resetField?: Function;
   setValidateMessage?: Function;
+  getValidateMessage?: Function;
   resetValidate?: Function;
   validateOnly?: Function;
   isFormList?: boolean;
@@ -382,6 +383,10 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     setVerifyStatus(status);
   }
 
+  function getValidateMessage() {
+    return errorList;
+  }
+
   useEffect(() => {
     // 注册自定义更新回调
     if (!shouldUpdate || !form) return;
@@ -459,6 +464,7 @@ const FormItem = forwardRef<FormItemInstance, FormItemProps>((originalProps, ref
     validateOnly,
     resetField,
     setValidateMessage,
+    getValidateMessage,
     resetValidate: resetHandler,
   };
   useImperativeHandle(ref, (): FormItemInstance => instance);

diff --git a/src/form/form.en-US.md b/src/form/form.en-US.md
@@ -44,6 +44,7 @@ reset | `(params?: FormResetParams<FormData>)` | \- | required。[see more ts de
 setFields | `(fields: FieldData[])` | \- | required。Typescript：`(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)
 setFieldsValue | `(field: Data)` | \- | required
 setValidateMessage | `(message: FormValidateMessage<FormData>)` | \- | required。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)。<br/>`type FormValidateMessage<FormData> = { [field in keyof FormData]: FormItemValidateMessage[] }`<br/><br/>`interface FormItemValidateMessage { type: 'warning' \| 'error'; message: string }`<br/>
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| void` | required。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)。<br/>
 submit | `(params?: { showErrorMessage?: boolean })` | \- | required
 validate | `(params?: FormValidateParams)` | `Promise<FormValidateResult<FormData>>` | required。[see more ts definition](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)。<br/>`interface FormValidateParams { fields?: Array<string>; showErrorMessage?: boolean; trigger?: ValidateTriggerType }`<br/><br/>`type ValidateTriggerType = 'blur' \| 'change' \| 'submit' \| 'all'`<br/>
 validateOnly | `(params?: Pick<FormValidateParams, 'fields' \| 'trigger'>)` | `Promise<FormValidateResult<FormData>>` | required

diff --git a/src/form/form.md b/src/form/form.md
@@ -126,6 +126,7 @@ reset | `(params?: FormResetParams<FormData>)` | \- | 必需。重置表单，
 setFields | `(fields: FieldData[])` | \- | 必需。设置多组字段状态。TS 类型：`(fields: FieldData[]) => void` `interface FieldData { name: NamePath; value?: unknown, status?: string, validateMessage?: { type?: string, message?: string } }`。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)
 setFieldsValue | `(field: Data)` | \- | 必需。设置表单字段值
 setValidateMessage | `(message: FormValidateMessage<FormData>)` | \- | 必需。设置自定义校验结果，如远程校验信息直接呈现。注意需要在组件挂载结束后使用该方法。`FormData` 指表单数据泛型。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)。<br/>`type FormValidateMessage<FormData> = { [field in keyof FormData]: FormItemValidateMessage[] }`<br/><br/>`interface FormItemValidateMessage { type: 'warning' \| 'error'; message: string }`<br/>
+getValidateMessage | `(fields?: Array<keyof FormData>)` | `Array<FormRule> \| void` | 必需。获取校验结果，当调用 getValidateMessage() 时返回所有校验结果。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)。<br/>
 submit | `(params?: { showErrorMessage?: boolean })` | \- | 必需。提交表单，表单里面没有提交按钮`<button type=\"submit\" />`时可以使用该方法。`showErrorMessage` 表示是否在提交校验不通过时显示校验不通过的原因，默认显示。该方法会触发 `submit` 事件
 validate | `(params?: FormValidateParams)` | `Promise<FormValidateResult<FormData>>` | 必需。校验函数，包含错误文本提示等功能。泛型 `FormData` 表示表单数据 TS 类型。<br/>【关于参数】`params.fields` 表示校验字段，如果设置了 `fields`，本次校验将仅对这些字段进行校验。`params.trigger` 表示本次触发校验的范围，'params.trigger = blur' 表示只触发校验规则设定为 trigger='blur' 的字段，'params.trigger = change' 表示只触发校验规则设定为 trigger='change' 的字段，默认触发全范围校验。`params.showErrorMessage` 表示校验结束后是否显示错误文本提示，默认显示。<br />【关于返回值】返回值为 true 表示校验通过；如果校验不通过，返回值为校验结果列表。[详细类型定义](https://github.com/Tencent/tdesign-react/blob/develop/src/form/type.ts)。<br/>`interface FormValidateParams { fields?: Array<string>; showErrorMessage?: boolean; trigger?: ValidateTriggerType }`<br/><br/>`type ValidateTriggerType = 'blur' \| 'change' \| 'submit' \| 'all'`<br/>
 validateOnly | `(params?: Pick<FormValidateParams, 'fields' \| 'trigger'>)` | `Promise<FormValidateResult<FormData>>` | 必需。纯净的校验函数，仅返回校验结果，不对组件进行任何操作。泛型 `FormData` 表示表单数据 TS 类型。参数和返回值含义同 `validate` 方法

diff --git a/src/form/hooks/useForm.ts b/src/form/hooks/useForm.ts
@@ -47,6 +47,9 @@ class FormStore {
     setValidateMessage: (...args) => {
       this.taskQueue.push({ args, name: 'setValidateMessage' });
     },
+    getValidateMessage: (...args) => {
+      this.taskQueue.push({ args, name: 'getValidateMessage' });
+    },
     getFieldValue: null,
     getFieldsValue: null,
     _init: true,

diff --git a/src/form/hooks/useInstance.tsx b/src/form/hooks/useInstance.tsx
@@ -218,6 +218,32 @@ export default function useInstance(
     });
   }
 
+  // 对外方法，获取 formItem 的错误信息
+  function getValidateMessage(fields?: Array<keyof FormData>) {
+    const message = {};
+
+    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 (isEmpty(message)) return;
+
+    return message;
+  }
+
   return {
     submit,
     reset,
@@ -227,6 +253,7 @@ export default function useInstance(
     setFields,
     setFieldsValue,
     setValidateMessage,
+    getValidateMessage,
     getFieldValue,
     getFieldsValue,
     currentElement: formRef.current,

diff --git a/src/form/type.ts b/src/form/type.ts
@@ -141,6 +141,10 @@ export interface FormInstanceFunctions<FormData extends Data = Data> {
    * 设置自定义校验结果，如远程校验信息直接呈现。注意需要在组件挂载结束后使用该方法。`FormData` 指表单数据泛型
    */
   setValidateMessage: (message: FormValidateMessage<FormData>) => void;
+  /**
+   * 获取校验结果
+   */
+  getValidateMessage: (fields?: Array<keyof FormData>) => Array<FormRule> | void;
   /**
    * 提交表单，表单里面没有提交按钮`<button type=\"submit\" />`时可以使用该方法。`showErrorMessage` 表示是否在提交校验不通过时显示校验不通过的原因，默认显示。该方法会触发 `submit` 事件
    */