Ant Design Affix 组件完全指南滚动吸顶原理、API 详解与源码级实现剖析【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designAffix 是 Ant Design 提供的一个「将元素钉在视口中」的定位组件当页面滚动使元素越过指定阈值时它会把元素从文档流中吸到视口顶部或底部固定显示滚动回原位后自动释放。本文以 components/affix/index.en-US.md 为骨架结合 components/affix/index.tsx 的源码实现与官方示例系统讲解 Affix 的使用场景、完整 API、四种官方 Demo、FAQ 注意事项并深入其底层测量、事件监听与动画帧节流机制帮助你既会用、又理解它为什么这样工作。一、什么时候该用 AffixWhen To Use在较长的网页中将某些组件钉在视口内滚动跟随非常常见——最典型的场景就是菜单和操作按钮例如表格上方的工具栏、长表单底部的提交按钮、目录导航。使用 Affix 时有一个重要原则需要注意Affix 不应该遮挡页面上的其他内容尤其是在视口尺寸较小时。官方文档index.en-US.md对此有明确提示这意味着在使用时要为固定元素预留足够的视觉空间避免吸顶后盖住内容的体验问题。另外文档中有一条面向开发者的版本提示自版本5.10.0起Affix 已使用函数组件FC重写通过ref获取内部实例方法的方式将失效。这一点直接影响了 API 的形态现在通过ref能拿到的只有AffixRef.updatePosition详见下文源码剖析章节曾经基于 class 组件实例的内部方法调用不再可用。二、快速上手基础用法最简单的用法是直接用一个offsetTop或offsetBottom包住任意内容。官方基础示例 demo/basic.tsx 同时演示了顶部吸顶与底部吸底两种模式并通过按钮动态修改偏移量验证 Affix 会实时响应偏移值变化import React from react; import { Affix, Button } from antd; const App: React.FC () { const [top, setTop] React.useStatenumber(100); const [bottom, setBottom] React.useStatenumber(100); return ( Affix offsetTop{top} Button typeprimary onClick{() setTop(top 10)} Affix top /Button /Affix br / Affix offsetBottom{bottom} Button typeprimary onClick{() setBottom(bottom 10)} Affix bottom /Button /Affix / ); }; export default App;要点offsetTop{100}表示元素距离视口顶部 100px 时触发吸顶offsetBottom{100}表示元素距离视口底部 100px 时触发吸底动态修改offsetTop/offsetBottom后组件会重新测量并更新固定位置源码中通过React.useEffect监听这两个值的变化并触发updatePosition()见 index.tsx。三、API 完整解析Affix 的 API 十分精简。文档给出了完整属性表其中通用属性如className、style可参考 Common propsPropertyDescriptionTypeDefaultoffsetBottomOffset from the bottom of the viewport (in pixels)number-offsetTopOffset from the top of the viewport (in pixels)number0targetSpecifies the scrollable area DOM node() HTMLElement() windowonChangeCallback for when Affix state is changed(affixed?: boolean) void-对照源码 index.tsx 中的AffixProps类型定义可以进一步补充每个属性的实现细节offsetTop?: number从视口顶部计算的距离。源码中有一个值得注意的默认值逻辑index.tsxconst internalOffsetTop offsetBottom undefined offsetTop undefined ? 0 : offsetTop;即当offsetTop和offsetBottom都未传时内部按offsetTop 0处理只要显式传了offsetBottominternalOffsetTop就取undefined此时不会触发顶部吸顶。offsetBottom?: number从视口底部计算的距离默认无不启用底部吸底。target?: () Window | HTMLElement | null指定 Affix 需要监听其滚动事件的滚动容器 DOM 节点返回一个 DOM 元素的函数默认返回window。源码中还支持从ConfigProvider的getTargetContainer读取全局目标容器index.tsxconst targetFunc target ?? getTargetContainer ?? getDefaultTarget;其中getDefaultTarget在非浏览器环境SSR / 测试下返回null避免直接访问window报错。onChange?: (affixed?: boolean) voidAffix 固定状态改变时的回调参数affixed为true表示进入固定状态false表示解除。在AffixState中还包含affixStyle、placeholderStyle等内部状态字段index.tsx。一个必须遵守的约束子元素不能是position: absolute文档明确强调Affix的子元素不能带有position: absolute属性但可以给Affix本身设置position: absolute。正确写法如下Affix style{{ position: absolute, top: y, left: x }}.../Affix这是因为 Affix 的定位机制依赖placeholder占位元素与fixed节点之间的尺寸/位置换算子元素若脱离文档流absolute 定位其占位尺寸将无法被正确测量导致吸顶位置错乱。四、状态回调监听吸顶与释放当需要感知元素当前是否处于固定状态时例如联动其他组件的高亮、隐藏滚动条等使用onChange。官方示例 demo/on-change.tsximport React from react; import { Affix, Button } from antd; const App: React.FC () ( Affix offsetTop{120} onChange{(affixed) console.log(affixed)} Button120px to affix top/Button /Affix ); export default App;即页面滚动使元素距视口顶部达到 120px 时控制台打印true滚动回原位后打印false。从源码看回调只在状态真正发生翻转时触发而不是每次滚动都触发index.tsxnewState.lastAffix !!newState.affixStyle; if (lastAffix ! newState.lastAffix) { onChange?.(newState.lastAffix); }测试用例 Affix.test.tsx 也验证了这一点movePlaceholder(-100)触发滚动后onChange被以true调用同时.ant-affix节点上出现top: 0的样式。五、自定义滚动容器target 的典型用法默认情况下 Affix 监听window的滚动。当页面内部存在独立滚动的容器而不是整页滚动时需要把target指向该容器。官方示例 demo/target.tsximport React from react; import { Affix, Button } from antd; const containerStyle: React.CSSProperties { width: 100%, height: 100, overflow: auto, boxShadow: 0 0 0 1px #1677ff, scrollbarWidth: thin, scrollbarColor: unset, }; const style: React.CSSProperties { width: 100%, height: 1000, }; const App: React.FC () { const [container, setContainer] React.useStateHTMLDivElement | null(null); return ( div style{containerStyle} ref{setContainer} div style{style} Affix target{() container} Button typeprimaryFixed at the top of container/Button /Affix /div /div ); }; export default App;实现要点外层容器设置overflow: auto并height: 100形成独立滚动区域内层内容高度 1000px制造可滚动空间通过ref拿到容器 DOM再以target{() container}传给 Affix按钮就会在容器滚动时吸在容器可视区域的顶部。从源码看target变化时会触发两件事重新绑定事件监听addListeners见 index.tsx以及重新测量位置updatePosition见 index.tsx。测试用例中也覆盖了target函数切换为返回null的场景此时 Affix 不做测量、不渲染任何固定样式见 Affix.test.tsx。六、源码级原理剖析Affix 是如何吸住的理解了用法之后再看 index.tsx 的整体实现会发现 Affix 的本质是一个基于getBoundingClientRect的几何计算 事件驱动的状态机。整个组件在5.10.0之后用函数组件 Hooks 重写核心流程如下。1. 双元素渲染结构占位符 固定节点渲染结构index.tsx是理解一切的关键ResizeObserver onResize{updatePosition} div style{style} className{className} ref{placeholderNodeRef} {...otherProps} {affixStyle div style{placeholderStyle} aria-hiddentrue /} div className{mergedCls} ref{fixedNodeRef} style{affixStyle} ResizeObserver onResize{updatePosition}{children}/ResizeObserver /div /div /ResizeObserver外层占位容器placeholderNodeRef始终留在文档流中负责顶住原来的排版位置内层固定节点fixedNodeRef当处于固定状态时它被设置为position: fixed并携带width/height与占位元素尺寸一致保证吸顶时不会引起页面布局跳动固定状态下还会渲染一个aria-hiddentrue的占位 div占住原有文档流空间内外两层ResizeObserver监听尺寸变化任何一方的尺寸改变都会触发重新测量——这保证了内容尺寸变化如按钮文案变长时固定位置依然正确。当未处于固定状态时内层节点不添加affix样式类index.tsxconst mergedCls classNames({ [rootCls]: affixStyle });2. 测量算法getFixedTop / getFixedBottom位置计算的核心是 utils.ts 中的三个纯函数export function getTargetRect(target: BindElement): DOMRect { return target ! window ? (target as HTMLElement).getBoundingClientRect() : ({ top: 0, bottom: window.innerHeight } as DOMRect); } export function getFixedTop(placeholderRect, targetRect, offsetTop?) { if ( offsetTop ! undefined Math.round(targetRect.top) Math.round(placeholderRect.top) - offsetTop ) { return offsetTop targetRect.top; } return undefined; } export function getFixedBottom(placeholderRect, targetRect, offsetBottom?) { if ( offsetBottom ! undefined Math.round(targetRect.bottom) Math.round(placeholderRect.bottom) offsetBottom ) { const targetBottomOffset window.innerHeight - targetRect.bottom; return offsetBottom targetBottomOffset; } return undefined; }算法含义吸顶判定当占位元素顶部超过目标容器顶部 offsetTop即placeholderRect.top小于targetRect.top offsetTop时返回offsetTop targetRect.top作为top值吸底判定当占位元素底部还没越过目标容器底部 - offsetBottom即placeholderRect.bottom大于targetRect.bottom - offsetBottom时计算offsetBottom (window.innerHeight - targetRect.bottom)作为bottom值吸顶与吸底二者互斥measure()中先计算fixedTop若得到有效值则采用顶部固定否则再计算fixedBottomindex.tsx。测量前还会做一次隐藏元素守卫如果占位元素的top/left/width/height全为 0说明元素当前不可见如display: none直接跳过测量index.tsx。测试用例do not measure when hidden验证了该行为见 Affix.test.tsx。3. 事件监听并非只监听 scroll源码定义了TRIGGER_EVENTS常量index.tsxconst TRIGGER_EVENTS: (keyof WindowEventMap)[] [ resize, scroll, touchstart, touchmove, touchend, pageshow, load, ];Affix 会将这 7 类事件统一绑定到target容器上addListeners见 index.tsx任何一个事件发生都触发位置重算。这覆盖了滚动scroll与窗口缩放resize移动端触摸滚动系列touchstart/touchmove/touchend页面回退时恢复缓存的pageshow、资源加载完成后的load。同时要注意Affix 只监听目标容器的滚动事件并不会监听容器内部子元素 DOM 的尺寸/位置变化这正是文档 FAQ 中元素有时会移出容器问题的根因见下一节。4. 性能利器requestAnimationFrame 节流所有位置更新都经过throttleByAnimationFrame包装实现见 components/_util/throttleByAnimationFrame.ts其原理是在同一个动画帧内无论滚动事件触发多少次只执行一次测量通过raf与requestId判空实现并提供cancel()用于卸载时清理。Affix 中实际有两个节流函数updatePosition直接触发prepareMeasure()用于尺寸变化ResizeObserver与偏移值变化lazyUpdatePosition先做一次位置是否真的变了的预判比较affixStyle.top/bottom与重算结果未变化则跳过测量这一优化专门用于让 Safari 的滚动更顺滑源码注释Check position change before measure to make Safari smooth见 index.tsx。5. 通过 ref 手动刷新AffixRef.updatePosition前面提到5.10.0重写为函数组件后ref 只暴露一个能力index.tsx 与 index.tsxexport interface AffixRef { updatePosition: ReturnTypetypeof throttleByAnimationFrame; } // ... React.useImperativeHandle(ref, () ({ updatePosition }));当你通过ReactDOM或外部逻辑改变了 Affix 的容器/内容布局、但 Affix 自身监听不到时可以手动调用ref.current?.updatePosition()强制重算位置。6. 样式与主题 TokenAffix 的样式实现位于 style/index.ts非常简洁const genSharedAffixStyle: GenerateStyleAffixToken (token): CSSObject { const { componentCls } token; return { [componentCls]: { position: fixed, zIndex: token.zIndexPopup, }, }; }; export const prepareComponentToken: GetDefaultTokenAffix (token) ({ zIndexPopup: token.zIndexBase 10, });即固定状态下的.ant-affix使用position: fixed层叠上下文为zIndexBase 10可通过主题 TokenzIndexPopup定制。Affix 已通过 components/index.ts 统一导出同时导出AffixProps与AffixRef类型。七、FAQ 与使用注意事项官方文档的 FAQ 记录了两个高频问题这里连同根源一起说明。1. 绑定target容器后元素有时会移出容器原因出于性能考虑Affix 只监听容器的滚动事件即上文TRIGGER_EVENTS绑定的目标不会监听容器内元素位置/尺寸的变化。如果容器内容布局在滚动过程中发生变化例如图片懒加载撑高、子树重新渲染Affix 无法感知元素就可能跑出容器。解决仍希望感知这类变化时可以自行添加自定义监听文档给出了 codesandbox 参考实现或者调用ref.current?.updatePosition()手动刷新。相关历史 issue#3938、#5642、#16120。2. 在横向滚动容器中使用时left位置不正确原因Affix 只适用于单向垂直滚动的场景官方文档明确指出它仅支持在垂直滚动容器中使用。解决如果要在横向滚动容器中实现类似效果建议改用原生 CSS 的position: sticky属性自行实现。相关历史 issue#29108。八、总结Affix 是 Ant Design 中 API 最小、但实现相当精巧的组件之一。掌握四个要点即可在生产中熟练使用参数就三个半offsetTop、offsetBottom、target加上onChange分别对应吸顶、吸底、自定义滚动容器、状态感知牢记两条红线子元素不能用position: absolute横向滚动场景请改用position: sticky理解双元素 测量原理占位元素保证布局不跳动getBoundingClientRect几何计算决定fixed样式动画帧节流保证滚动性能5.10.0之后的函数组件形态ref 仅暴露updatePosition旧的实例方法调用方式已失效。结合 index.tsx、utils.ts、Affix.test.tsx 以及四个官方 Demobasic.tsx、on-change.tsx、target.tsx、debug.tsx一起阅读你不仅能熟练使用 Affix还能在遇到滚动定位类问题时从原理层面快速定位瓶颈。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考