如何自定义Ant Design表单scrollToFirstError滚动定位行为？

架构老林

2026-8-10

解决Ant Design 4.x表单scrollToFirstError被头部遮挡的问题

当表单滚动到首个错误字段时被页面头部遮挡，你可以通过自定义scrollToFirstError函数调整滚动的top坐标，核心逻辑是修改错误元素的滚动目标位置，避开头部区域：

实现步骤

获取页面固定头部的实际高度（可通过DOM元素的offsetHeight获取，或直接写死已知高度）
在自定义回调函数中，取出首个错误元素的位置信息，调整top值后手动触发滚动

代码示例

方式一：直接修改scrollTo的top值

// 自定义滚动函数
const customScrollToFirstError = (actions) => {
  if (actions.length === 0) return;
  // 取出首个错误元素的位置信息
  const { top, left } = actions[0];
  // 获取头部高度，替换成你项目中头部的选择器
  const headerHeight = document.querySelector('.page-header').offsetHeight;
  // 调整top值，减去头部高度，再加20px偏移量提升体验
  const adjustedTop = top - headerHeight - 20;
  // 执行平滑滚动
  window.scrollTo({
    top: adjustedTop,
    left,
    behavior: 'smooth'
  });
};

// 在Form组件中配置
<Form
  scrollToFirstError={customScrollToFirstError}
  // 其他表单属性
>
  {/* 表单字段 */}
</Form>

方式二：结合scrollIntoView和scrollBy

如果希望错误元素对齐视口但避开头部，可先让元素滚动到视口，再调整滚动位置：

const customScrollToFirstError = (actions) => {
  if (actions.length === 0) return;
  const firstErrorEl = actions[0].el;
  // 先让错误元素滚动到视口顶部
  firstErrorEl.scrollIntoView({
    behavior: 'smooth',
    block: 'start'
  });
  // 再向上滚动，避开头部
  const headerHeight = document.querySelector('.page-header').offsetHeight;
  window.scrollBy({
    top: -headerHeight - 20,
    behavior: 'smooth'
  });
};