feat(form): Add scrollToFirstError api (#3003)

.changeset/nasty-geckos-laugh.md

@@ -0,0 +1,5 @@
+---
+"@hi-ui/hiui": patch
+---
+
+feat(form): Add scrollToFirstError api

.changeset/six-carrots-protect.md

@@ -0,0 +1,5 @@
+---
+"@hi-ui/form": minor
+---
+
+feat: Add scrollToFirstError api

packages/ui/form/package.json

@@ -52,7 +52,8 @@
     "@hi-ui/object-utils": "^4.0.4",
     "@hi-ui/type-assertion": "^4.0.4",
     "@hi-ui/use-latest": "^4.0.4",
-    "async-validator": "^4.0.7"
+    "async-validator": "^4.0.7",
+    "scroll-into-view-if-needed": "^3.1.0"
   },
   "peerDependencies": {
     "@hi-ui/core": ">=4.0.8",

packages/ui/form/src/FormItem.tsx

@@ -1,4 +1,4 @@
-import React, { useMemo } from 'react'
+import React, { useMemo, useRef } from 'react'
 import { __DEV__ } from '@hi-ui/env'
 import { useFiledRules, UseFormFieldProps } from './use-form-field'
 import { FormLabel, FormLabelProps } from './FormLabel'
@@ -21,7 +21,7 @@ export const FormItem: React.FC<FormItemProps> = ({
   render,
   ...rest
 }) => {
-  const { prefixCls, showRequiredOnValidateRequired } = useFormContext()
+  const { prefixCls, showRequiredOnValidateRequired, formItemsRef } = useFormContext()
 
   const fieldRules = useFiledRules({ field, rules, valueType })
   const { required } = rest
@@ -36,6 +36,9 @@ export const FormItem: React.FC<FormItemProps> = ({
   return (
     <FormLabel
       {...rest}
+      ref={(ref) => {
+        field && formItemsRef.current.set(field.toString(), ref)
+      }}
       required={showRequired}
       // @ts-ignore
       formMessage={<FormMessage field={field} className={`${prefixCls}-item__message`} />}

packages/ui/form/src/context.ts

@@ -1,6 +1,7 @@
-import React, { createContext, useContext } from 'react'
+import React, { createContext, MutableRefObject, useContext } from 'react'
 
 import { UseFormReturn } from './use-form'
+import { FormFieldPath } from './types'
 
 export interface FormContextProps extends UseFormReturn {
   labelWidth: React.ReactText
@@ -10,6 +11,7 @@ export interface FormContextProps extends UseFormReturn {
   showRequiredOnValidateRequired: boolean
   showValidateMessage: boolean
   prefixCls: string
+  formItemsRef: MutableRefObject<Map<FormFieldPath, HTMLDivElement | null>>
 }
 
 const formContext = createContext<Omit<FormContextProps, 'rootProps'> | null>(null)

packages/ui/form/src/use-form.ts

@@ -1,5 +1,8 @@
 import { stringify, parse, isValidField, mergeValues } from './utils'
 import React, { useCallback, useMemo, useReducer, useRef } from 'react'
+import scrollIntoView, {
+  StandardBehaviorOptions as ScrollOptions,
+} from 'scroll-into-view-if-needed'
 import {
   FormAction,
   FormState,
@@ -35,6 +38,7 @@ export const useForm = <Values = Record<string, any>>({
   rules = EMPTY_RULES,
   validateAfterTouched = false,
   validateTrigger: validateTriggerProp = DEFAULT_VALIDATE_TRIGGER,
+  scrollToFirstError,
   ...rest
 }: UseFormProps<Values>) => {
   /**
@@ -44,6 +48,9 @@ export const useForm = <Values = Record<string, any>>({
   // eslint-disable-next-line react-hooks/exhaustive-deps
   const validateTriggersMemo = useMemo(() => validateTrigger, validateTrigger)
 
+  const formItemsMp = useMemo(() => new Map(), [])
+  const formItemsRef = useRef(formItemsMp)
+
   /**
    * 收集 Field 的校验器注册表
    */
@@ -69,6 +76,21 @@ export const useForm = <Values = Record<string, any>>({
   //   formStateRef,
   // ])
 
+  const getFormItemNode = useCallback((fieldName: FormFieldPath) => {
+    return formItemsRef.current.get(fieldName.toString())
+  }, [])
+
+  const scrollToNode = useCallback(
+    (fieldName: FormFieldPath, options: ScrollOptions = {}) => {
+      scrollIntoView(getFormItemNode(fieldName), {
+        scrollMode: 'if-needed',
+        block: 'nearest',
+        ...options,
+      })
+    },
+    [getFormItemNode]
+  )
+
   const getFieldValue = useCallback(
     (fieldName: FormFieldPath) => getNested(formStateRef.current.values, fieldName),
     [formStateRef]
@@ -151,6 +173,8 @@ export const useForm = <Values = Record<string, any>>({
     const fieldNames = getRegisteredKeys()
     formDispatch({ type: 'SET_VALIDATING', payload: true })
 
+    let firstError = false
+
     return Promise.all(
       fieldNames.map((fieldName) => {
         const value = getFieldValue(fieldName)
@@ -162,6 +186,14 @@ export const useForm = <Values = Record<string, any>>({
 
         // catch 错误，保证检验所有表单项
         return fieldValidation.validate(value).catch((error) => {
+          if (scrollToFirstError && !firstError) {
+            firstError = true
+            scrollToNode(
+              fieldName,
+              typeof scrollToFirstError === 'object' ? scrollToFirstError : {}
+            )
+          }
+
           // 第一个出错，即退出校验
           if (lazyValidate) {
             throw error
@@ -229,7 +261,14 @@ export const useForm = <Values = Record<string, any>>({
 
         return combinedError
       })
-  }, [getRegisteredKeys, getFieldValue, getValidation, lazyValidate])
+  }, [
+    getFieldValue,
+    getRegisteredKeys,
+    getValidation,
+    lazyValidate,
+    scrollToFirstError,
+    scrollToNode,
+  ])
 
   /**
    * 控件值更新策略
@@ -568,6 +607,7 @@ export const useForm = <Values = Record<string, any>>({
     getFieldsValue,
     setFieldsValue,
     getFieldsError,
+    formItemsRef,
   }
 }
 
@@ -615,6 +655,10 @@ export interface UseFormProps<T = Record<string, any>> {
    * 重置时回调
    */
   onReset?: (values: T) => void | Promise<any>
+  /**
+   * 提交失败自动滚动到第一个错误字段，配置参考：https://github.com/scroll-into-view/scroll-into-view-if-needed?tab=readme-ov-file#options
+   */
+  scrollToFirstError?: boolean | ScrollOptions
 }
 
 export type UseFormReturn = ReturnType<typeof useForm>

packages/ui/form/stories/index.stories.tsx

@@ -7,6 +7,7 @@ export * from './placement.stories'
 export * from './validate.stories'
 export * from './validate-field.stories'
 export * from './validate-message.stories'
+export * from './scroll-to-error.stories'
 export * from './set-values.stories'
 export * from './get-values.stories'
 export * from './render.stories'