4.0 Form scrollToField: Pass options to form scrollToField (#20774)

* fix: form.scrollToField should accept options from scrollIntoView

* doc: Fixed wrong doc content

* doc: Fix docs pointing to scroll-into-view-if-needed

components/form/__tests__/index.test.js

@@ -188,8 +188,16 @@ describe('Form', () => {
         mount(<Demo />, { attachTo: document.body });
 
         expect(scrollIntoView).not.toHaveBeenCalled();
-        callGetForm().scrollToField('test');
-        expect(scrollIntoView).toHaveBeenCalled();
+        const form = callGetForm();
+        form.scrollToField('test', {
+          block: 'start',
+        });
+
+        const inputNode = document.getElementById('scroll_test');
+        expect(scrollIntoView).toHaveBeenCalledWith(inputNode, {
+          block: 'start',
+          scrollMode: 'if-needed',
+        });
       });
     }
 

components/form/index.en-US.md

@@ -183,7 +183,7 @@ Provide linkage between forms. If a sub form with `name` prop update, it will au
 | isFieldsTouched | Check if fields have been operated. Check if all fields is touched when `allTouched` is `true` | (nameList?: [NamePath](#NamePath)[], allTouched?: boolean) => boolean |
 | isFieldValidating | Check fields if is in validating | (name: [NamePath](#NamePath)) => boolean |
 | resetFields | Reset fields to `initialValues` | (fields?: [NamePath](#NamePath)[]) => void |
-| scrollToField | Scroll to field position | (name: [NamePath](#NamePath)) => void |
+| scrollToField | Scroll to field position | (name: [NamePath](#NamePath), options: [[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/blob/ece40bd9143f48caf4b99503425ecb16b0ad8249/src/types.ts#L10)]) => void |
 | setFields | Set fields status | (fields: FieldData[]) => void |
 | setFieldsValue | Set fields value | (values) => void |
 | submit | Submit the form. It's same as click `submit` button | () => void |

components/form/index.zh-CN.md

@@ -184,7 +184,7 @@ Form 通过增量更新方式，只更新被修改的字段相关组件以达到
 | isFieldsTouched | 检查一组字段是否被用户操作过，`allTouched` 为 `true` 时检查是否所有字段都被操作过 | (nameList?: [NamePath](#NamePath)[], allTouched?: boolean) => boolean |
 | isFieldValidating | 检查一组字段是否正在校验 | (name: [NamePath](#NamePath)) => boolean |
 | resetFields | 重置一组字段到 `initialValues` | (fields?: [NamePath](#NamePath)[]) => void |
-| scrollToField | 滚动到对应字段位置 | (name: [NamePath](#NamePath)) => void |
+| scrollToField | 滚动到对应字段位置 | (name: [NamePath](#NamePath), options: [[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/blob/ece40bd9143f48caf4b99503425ecb16b0ad8249/src/types.ts#L10)]) => void |
 | setFields | 设置一组字段状态 | (fields: FieldData[]) => void |
 | setFieldsValue | 设置表单的值 | (values) => void |
 | submit | 提交表单，与点击 `submit` 按钮效果相同 | () => void |

components/form/interface.ts

@@ -1 +1,2 @@
+export { Options as ScrollOptions } from 'scroll-into-view-if-needed';
 export type FormLabelAlign = 'left' | 'right';

components/form/util.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { useForm as useRcForm, FormInstance as RcFormInstance } from 'rc-field-form';
 import scrollIntoView from 'scroll-into-view-if-needed';
+import { ScrollOptions } from './interface';
 
 type InternalNamePath = (string | number)[];
 
@@ -65,7 +66,7 @@ export function getFieldId(namePath: InternalNamePath, formName?: string): strin
 }
 
 export interface FormInstance extends RcFormInstance {
-  scrollToField: (name: string | number | InternalNamePath) => void;
+  scrollToField: (name: string | number | InternalNamePath, options?: ScrollOptions) => void;
   __INTERNAL__: {
     name?: string;
   };
@@ -75,7 +76,7 @@ export function useForm(form?: FormInstance): [FormInstance] {
   const wrapForm: FormInstance = form || {
     ...useRcForm()[0],
     __INTERNAL__: {},
-    scrollToField: name => {
+    scrollToField: (name: string, options: ScrollOptions = {}) => {
       const namePath = toArray(name);
       const fieldId = getFieldId(namePath, wrapForm.__INTERNAL__.name);
       const node: HTMLElement | null = fieldId ? document.getElementById(fieldId) : null;
@@ -84,6 +85,7 @@ export function useForm(form?: FormInstance): [FormInstance] {
         scrollIntoView(node, {
           scrollMode: 'if-needed',
           block: 'nearest',
+          ...options,
         });
       }
     },