@hi-ui/form 4.2.2 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @hi-ui/form
 
+## 4.3.0
+
+### Minor Changes
+
+- [#3006](https://github.com/XiaoMi/hiui/pull/3006) [`4540c217a`](https://github.com/XiaoMi/hiui/commit/4540c217ade6749c38ee58cefcfe94322889b929) Thanks [@zyprepare](https://github.com/zyprepare)! - feat: Add scrollToFirstError api
+
 ## 4.2.2
 
 ### Patch Changes

package/lib/cjs/FormItem.js

@@ -43,7 +43,8 @@ var FormItem = function FormItem(_a) {
     rest = tslib.__rest(_a, ["className", "children", "field", "valueType", "rules", "valuePropName", "valueChangeFuncPropName", "valueDispatchTransform", "valueConnectTransform", "validateTrigger", "render"]);
   var _useFormContext = context.useFormContext(),
     prefixCls = _useFormContext.prefixCls,
-    showRequiredOnValidateRequired = _useFormContext.showRequiredOnValidateRequired;
+    showRequiredOnValidateRequired = _useFormContext.showRequiredOnValidateRequired,
+    formItemsRef = _useFormContext.formItemsRef;
   var fieldRules = useFormField.useFiledRules({
     field: field,
     rules: rules,
@@ -59,6 +60,9 @@ var FormItem = function FormItem(_a) {
     return required;
   }, [required, showRequiredOnValidateRequired, fieldRules]);
   return /*#__PURE__*/React__default["default"].createElement(FormLabel.FormLabel, Object.assign({}, rest, {
+    ref: function ref(_ref) {
+      field && formItemsRef.current.set(field.toString(), _ref);
+    },
     required: showRequired,
     // @ts-ignore
     formMessage: /*#__PURE__*/React__default["default"].createElement(FormMessage.FormMessage, {

package/lib/cjs/use-form.js

@@ -17,6 +17,7 @@ var _regeneratorRuntime = require('@babel/runtime/regenerator');
 var tslib = require('tslib');
 var index = require('./utils/index.js');
 var React = require('react');
+var scrollIntoView = require('scroll-into-view-if-needed');
 var useLatest = require('@hi-ui/use-latest');
 var typeAssertion = require('@hi-ui/type-assertion');
 var funcUtils = require('@hi-ui/func-utils');
@@ -29,6 +30,7 @@ function _interopDefaultCompat(e) {
 }
 var _regeneratorRuntime__default = /*#__PURE__*/_interopDefaultCompat(_regeneratorRuntime);
 var React__default = /*#__PURE__*/_interopDefaultCompat(React);
+var scrollIntoView__default = /*#__PURE__*/_interopDefaultCompat(scrollIntoView);
 var EMPTY_RULES = {};
 var EMPTY_ERRORS = {};
 var EMPTY_TOUCHED = {};
@@ -51,7 +53,8 @@ var useForm = function useForm(_a) {
     validateAfterTouched = _a$validateAfterTouch === void 0 ? false : _a$validateAfterTouch,
     _a$validateTrigger = _a.validateTrigger,
     validateTriggerProp = _a$validateTrigger === void 0 ? DEFAULT_VALIDATE_TRIGGER : _a$validateTrigger,
-    rest = tslib.__rest(_a, ["initialValues", "initialErrors", "initialTouched", "lazyValidate", "onValuesChange", "onReset", "onSubmit", "rules", "validateAfterTouched", "validateTrigger"]);
+    scrollToFirstError = _a.scrollToFirstError,
+    rest = tslib.__rest(_a, ["initialValues", "initialErrors", "initialTouched", "lazyValidate", "onValuesChange", "onReset", "onSubmit", "rules", "validateAfterTouched", "validateTrigger", "scrollToFirstError"]);
   /**
    * 处理校验触发器，保证 memo 依赖的是数组每个项，避免无效重渲染
    */
@@ -60,6 +63,10 @@ var useForm = function useForm(_a) {
   var validateTriggersMemo = React.useMemo(function () {
     return validateTrigger;
   }, validateTrigger);
+  var formItemsMp = React.useMemo(function () {
+    return new Map();
+  }, []);
+  var formItemsRef = React.useRef(formItemsMp);
   /**
    * 收集 Field 的校验器注册表
    */
@@ -85,6 +92,18 @@ var useForm = function useForm(_a) {
   // const getFieldNames = useCallback(() => Object.keys(formStateRef.current.values as any), [
   //   formStateRef,
   // ])
+  var getFormItemNode = React.useCallback(function (fieldName) {
+    return formItemsRef.current.get(fieldName.toString());
+  }, []);
+  var scrollToNode = React.useCallback(function (fieldName, options) {
+    if (options === void 0) {
+      options = {};
+    }
+    scrollIntoView__default["default"](getFormItemNode(fieldName), Object.assign({
+      scrollMode: 'if-needed',
+      block: 'nearest'
+    }, options));
+  }, [getFormItemNode]);
   var getFieldValue = React.useCallback(function (fieldName) {
     return objectUtils.getNested(formStateRef.current.values, fieldName);
   }, [formStateRef]);
@@ -183,6 +202,7 @@ var useForm = function useForm(_a) {
       type: 'SET_VALIDATING',
       payload: true
     });
+    var firstError = false;
     return Promise.all(fieldNames.map(function (fieldName) {
       var value = getFieldValue(fieldName);
       var fieldValidation = getValidation(fieldName);
@@ -191,6 +211,10 @@ var useForm = function useForm(_a) {
       }
       // catch 错误，保证检验所有表单项
       return fieldValidation.validate(value)["catch"](function (error) {
+        if (scrollToFirstError && !firstError) {
+          firstError = true;
+          scrollToNode(fieldName, _typeof(scrollToFirstError) === 'object' ? scrollToFirstError : {});
+        }
         // 第一个出错，即退出校验
         if (lazyValidate) {
           throw error;
@@ -257,7 +281,7 @@ var useForm = function useForm(_a) {
       });
       return combinedError;
     });
-  }, [getRegisteredKeys, getFieldValue, getValidation, lazyValidate]);
+  }, [getFieldValue, getRegisteredKeys, getValidation, lazyValidate, scrollToFirstError, scrollToNode]);
   /**
    * 控件值更新策略
    */
@@ -542,7 +566,8 @@ var useForm = function useForm(_a) {
     validateValue: validateField,
     getFieldsValue: getFieldsValue,
     setFieldsValue: setFieldsValue,
-    getFieldsError: getFieldsError
+    getFieldsError: getFieldsError,
+    formItemsRef: formItemsRef
   });
 };
 function formReducer(state, action) {

package/lib/esm/FormItem.js

@@ -31,7 +31,8 @@ var FormItem = function FormItem(_a) {
     rest = __rest(_a, ["className", "children", "field", "valueType", "rules", "valuePropName", "valueChangeFuncPropName", "valueDispatchTransform", "valueConnectTransform", "validateTrigger", "render"]);
   var _useFormContext = useFormContext(),
     prefixCls = _useFormContext.prefixCls,
-    showRequiredOnValidateRequired = _useFormContext.showRequiredOnValidateRequired;
+    showRequiredOnValidateRequired = _useFormContext.showRequiredOnValidateRequired,
+    formItemsRef = _useFormContext.formItemsRef;
   var fieldRules = useFiledRules({
     field: field,
     rules: rules,
@@ -47,6 +48,9 @@ var FormItem = function FormItem(_a) {
     return required;
   }, [required, showRequiredOnValidateRequired, fieldRules]);
   return /*#__PURE__*/React.createElement(FormLabel, Object.assign({}, rest, {
+    ref: function ref(_ref) {
+      field && formItemsRef.current.set(field.toString(), _ref);
+    },
     required: showRequired,
     // @ts-ignore
     formMessage: /*#__PURE__*/React.createElement(FormMessage, {

package/lib/esm/use-form.js

@@ -1,3 +1,4 @@
+import _typeof from "@babel/runtime/helpers/esm/typeof";
 /** @LICENSE
  * @hi-ui/form
  * https://github.com/XiaoMi/hiui/tree/master/packages/ui/form#readme
@@ -10,7 +11,8 @@
 import _regeneratorRuntime from '@babel/runtime/regenerator';
 import { __rest, __awaiter } from 'tslib';
 import { stringify, parse, mergeValues, isValidField } from './utils/index.js';
-import React, { useMemo, useReducer, useCallback, useRef } from 'react';
+import React, { useMemo, useRef, useReducer, useCallback } from 'react';
+import scrollIntoView from 'scroll-into-view-if-needed';
 import { useLatestRef, useLatestCallback } from '@hi-ui/use-latest';
 import { isArray, isFunction, isObjectLike } from '@hi-ui/type-assertion';
 import { callAllFuncs } from '@hi-ui/func-utils';
@@ -38,7 +40,8 @@ var useForm = function useForm(_a) {
     validateAfterTouched = _a$validateAfterTouch === void 0 ? false : _a$validateAfterTouch,
     _a$validateTrigger = _a.validateTrigger,
     validateTriggerProp = _a$validateTrigger === void 0 ? DEFAULT_VALIDATE_TRIGGER : _a$validateTrigger,
-    rest = __rest(_a, ["initialValues", "initialErrors", "initialTouched", "lazyValidate", "onValuesChange", "onReset", "onSubmit", "rules", "validateAfterTouched", "validateTrigger"]);
+    scrollToFirstError = _a.scrollToFirstError,
+    rest = __rest(_a, ["initialValues", "initialErrors", "initialTouched", "lazyValidate", "onValuesChange", "onReset", "onSubmit", "rules", "validateAfterTouched", "validateTrigger", "scrollToFirstError"]);
   /**
    * 处理校验触发器，保证 memo 依赖的是数组每个项，避免无效重渲染
    */
@@ -47,6 +50,10 @@ var useForm = function useForm(_a) {
   var validateTriggersMemo = useMemo(function () {
     return validateTrigger;
   }, validateTrigger);
+  var formItemsMp = useMemo(function () {
+    return new Map();
+  }, []);
+  var formItemsRef = useRef(formItemsMp);
   /**
    * 收集 Field 的校验器注册表
    */
@@ -72,6 +79,18 @@ var useForm = function useForm(_a) {
   // const getFieldNames = useCallback(() => Object.keys(formStateRef.current.values as any), [
   //   formStateRef,
   // ])
+  var getFormItemNode = useCallback(function (fieldName) {
+    return formItemsRef.current.get(fieldName.toString());
+  }, []);
+  var scrollToNode = useCallback(function (fieldName, options) {
+    if (options === void 0) {
+      options = {};
+    }
+    scrollIntoView(getFormItemNode(fieldName), Object.assign({
+      scrollMode: 'if-needed',
+      block: 'nearest'
+    }, options));
+  }, [getFormItemNode]);
   var getFieldValue = useCallback(function (fieldName) {
     return getNested(formStateRef.current.values, fieldName);
   }, [formStateRef]);
@@ -170,6 +189,7 @@ var useForm = function useForm(_a) {
       type: 'SET_VALIDATING',
       payload: true
     });
+    var firstError = false;
     return Promise.all(fieldNames.map(function (fieldName) {
       var value = getFieldValue(fieldName);
       var fieldValidation = getValidation(fieldName);
@@ -178,6 +198,10 @@ var useForm = function useForm(_a) {
       }
       // catch 错误，保证检验所有表单项
       return fieldValidation.validate(value)["catch"](function (error) {
+        if (scrollToFirstError && !firstError) {
+          firstError = true;
+          scrollToNode(fieldName, _typeof(scrollToFirstError) === 'object' ? scrollToFirstError : {});
+        }
         // 第一个出错，即退出校验
         if (lazyValidate) {
           throw error;
@@ -244,7 +268,7 @@ var useForm = function useForm(_a) {
       });
       return combinedError;
     });
-  }, [getRegisteredKeys, getFieldValue, getValidation, lazyValidate]);
+  }, [getFieldValue, getRegisteredKeys, getValidation, lazyValidate, scrollToFirstError, scrollToNode]);
   /**
    * 控件值更新策略
    */
@@ -529,7 +553,8 @@ var useForm = function useForm(_a) {
     validateValue: validateField,
     getFieldsValue: getFieldsValue,
     setFieldsValue: setFieldsValue,
-    getFieldsError: getFieldsError
+    getFieldsError: getFieldsError,
+    formItemsRef: formItemsRef
   });
 };
 function formReducer(state, action) {

package/lib/types/context.d.ts

@@ -1,5 +1,6 @@
-import React from 'react';
+import React, { MutableRefObject } from 'react';
 import { UseFormReturn } from './use-form';
+import { FormFieldPath } from './types';
 export interface FormContextProps extends UseFormReturn {
     labelWidth: React.ReactText;
     labelPlacement: 'left' | 'right' | 'top';
@@ -8,6 +9,7 @@ export interface FormContextProps extends UseFormReturn {
     showRequiredOnValidateRequired: boolean;
     showValidateMessage: boolean;
     prefixCls: string;
+    formItemsRef: MutableRefObject<Map<FormFieldPath, HTMLDivElement | null>>;
 }
 export declare const FormProvider: React.Provider<Omit<FormContextProps, "rootProps"> | null>;
 export declare const useFormContext: () => Omit<FormContextProps, "rootProps">;

package/lib/types/use-form.d.ts

@@ -1,6 +1,7 @@
 import React from 'react';
+import { StandardBehaviorOptions as ScrollOptions } from 'scroll-into-view-if-needed';
 import { FormState, FormFieldCollection, FormErrors, FormRuleModel, FormFieldPath, FormErrorMessage, FormSetState } from './types';
-export declare const useForm: <Values = Record<string, any>>({ initialValues, initialErrors, initialTouched, lazyValidate, onValuesChange, onReset, onSubmit, rules, validateAfterTouched, validateTrigger: validateTriggerProp, ...rest }: UseFormProps<Values>) => {
+export declare const useForm: <Values = Record<string, any>>({ initialValues, initialErrors, initialTouched, lazyValidate, onValuesChange, onReset, onSubmit, rules, validateAfterTouched, validateTrigger: validateTriggerProp, scrollToFirstError, ...rest }: UseFormProps<Values>) => {
     setFormState: (stateOrFunc: FormSetState<Values>) => void;
     setFieldValue: (field: FormFieldPath, value: unknown, shouldValidate?: boolean | undefined) => void;
     setFieldError: (field: FormFieldPath, errorMessage: FormErrorMessage | undefined) => void;
@@ -24,6 +25,7 @@ export declare const useForm: <Values = Record<string, any>>({ initialValues, in
     getFieldsValue: () => any;
     setFieldsValue: (fieldsState: Record<string, any> | Function) => void;
     getFieldsError: () => any;
+    formItemsRef: React.MutableRefObject<Map<any, any>>;
     values: any;
     errors: FormErrors<unknown>;
     touched: import("./types").FormTouched<unknown>;
@@ -74,5 +76,9 @@ 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 declare type UseFormReturn = ReturnType<typeof useForm>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hi-ui/form",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "description": "A sub-package for @hi-ui/hiui.",
   "keywords": [],
   "author": "HiUI <mi-hiui@xiaomi.com>",
@@ -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",