UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载Affix固钉是 ng-zorro-antd 提供的页面固定组件用于将侧边菜单、操作按钮等元素钉在可视范围内使其在页面滚动时始终保持可见。本文以 components/affix/doc/index.zh-CN.md 官方文档为骨架结合组件源码、官方 demo 与全局配置实现系统讲解nz-affix的完整 API、实战用法、全局配置方式以及底层固定位置计算原理。读完本文你将能够在长页面场景下正确使用 Affix 固定导航与操作区并理解其滚动监听 占位元素 固定定位的核心工作机制。何时使用 Affix当内容区域比较长、需要滚动页面时这部分内容对应的操作或导航需要在滚动范围内始终展现。Affix 最常见的应用场景是侧边菜单和按钮组合例如文章详情页侧边的目录导航、长表单页底部的保存 / 取消操作按钮、列表页顶部的筛选工具栏等。需要注意的是当页面可视范围过小时慎用此功能以免固定元素遮挡页面内容。这是官方文档明确给出的使用边界——Affix 不应覆盖页面其他内容尤其是视口较小时更应谨慎。快速上手最简单的用法在独立组件standalone或模块化引入方式下首先导入NzAffixModuleimport { NzAffixModule } from ng-zorro-antd/affix; import { NzButtonModule } from ng-zorro-antd/button;将需要固定的元素包进nz-affix即可。参考官方基础示例 components/affix/demo/basic.tsnz-affix [nzOffsetTop]offsetTop button nz-button nzTypeprimary (click)setOffsetTop() spanAffix top/span /button /nz-affix br / nz-affix [nzOffsetBottom]nzOffsetBottom (click)setOffsetBottom() button nz-button nzTypeprimary spanAffix bottom/span /button /nz-affixexport class NzDemoAffixBasicComponent { offsetTop 10; nzOffsetBottom 10; setOffsetTop(): void { this.offsetTop 10; } setOffsetBottom(): void { this.nzOffsetBottom 10; } }第一个 Affix 固定于顶部、距顶部10px处触发第二个固定于底部、距底部10px处触发。点击按钮改变偏移量可以直观看到固定触发点随偏移值变化。API 详解nz-affix 的四个成员官方文档给出nz-affix的全部 API整理如下成员说明类型默认值全局配置[nzOffsetBottom]距离窗口底部达到指定偏移量后触发number-✅[nzOffsetTop]距离窗口顶部达到指定偏移量后触发number0✅[nzTarget]设置nz-affix需要监听其滚动事件的元素值为一个返回对应 DOM 元素的函数string \| HTMLElementwindow(nzChange)固定状态改变时触发的回调函数EventEmitterboolean-nzOffsetTop顶部固定偏移元素滚动到距离窗口或nzTarget指定容器顶部nzOffsetTop像素时触发固定默认值为0即元素一到达视口顶部边缘即被固定。在源码 components/affix/affix.component.ts 中该输入通过numberAttributeWithZeroFallback转换器处理并带有WithConfig()装饰器说明它支持全局配置覆盖Input({ transform: numberAttributeWithZeroFallback }) WithConfig() nzOffsetTop?: null | number;nzOffsetBottom底部固定偏移当元素滚动到距离窗口底部nzOffsetBottom像素时触发固定此时元素以position: fixed; bottom: ...的方式贴住视口底部。该参数没有默认值-即默认不启用底部固定模式。注意一个关键的优先级逻辑见 affix.component.ts若nzOffsetTop与nzOffsetBottom都未显式设置数值则默认采用顶部固定模式且offsetTop 0只要其中一个被设置为数值就按显式值进入对应的固定模式。nzTarget自定义滚动容器nzTarget用于设置nz-affix需要监听滚动事件的元素默认是window。传入值可以是返回 DOM 元素的函数文档表述直接传HTMLElement或选择器字符串string源码类型为string | Element | Window见 affix.component.ts。源码中target的解析逻辑affix.component.tsprivate get target(): Element | Window { const el this.nzTarget; return (typeof el string ? this.document.querySelector(el) : el) || window; }即字符串会被当作 CSS 选择器查询查询失败或未设置时回退到window。当固定发生在非窗口容器中时底部偏移会额外叠加窗口高度与容器底部之间的间距affix.component.tsconst targetBottomOffset targetNode window ? 0 : window.innerHeight - targetRect.bottom!;nzChange固定状态改变回调(nzChange)在固定状态发生切换时触发从不固定变为固定、或从固定变为不固定回调参数为布尔值true表示当前已固定false表示已解除固定。源码中该输出通过 Angular 新式output()函数声明affix.component.ts并仅在状态真正发生翻转时才 emitaffix.component.tsif ((affixStyle !originalAffixStyle) || (!affixStyle originalAffixStyle)) { this.nzChange.emit(fixed); }监听固定状态变化参考官方示例 components/affix/demo/on-change.ts设置nzOffsetTop为120即元素滚动到距顶部 120px 时固定并通过nzChange回调得知当前是否处于固定状态nz-affix [nzOffsetTop]120 (nzChange)onChange($event) button nz-button span120px to affix top/span /button /nz-affixexport class NzDemoAffixOnChangeComponent { onChange(status: boolean): void { console.log(status); } }该能力非常实用例如固定后可以给元素追加阴影样式、改变按钮文案或联动调整页面布局的占位。在自定义滚动容器内固定nzTarget 实战官方示例 components/affix/demo/target.ts 演示了如何将 Affix 限定在某个可滚动容器内而不是整个窗口div classscrollable-container #target div classbackground nz-affix [nzTarget]target idaffix-container-target button nz-button nzTypeprimary spanFixed at the top of container/span /button /nz-affix /div /divstyles: .scrollable-container { height: 100px; overflow-y: scroll; } .background { padding-top: 60px; height: 300px; background-image: url(//zos.alipayobjects.com/rmsportal/RmjwQiJorKyobvI.jpg); } 要点容器需要设置固定高度与overflow-y: scroll或auto使其成为真正可滚动的区域通过模板引用变量#target将容器元素传给nzTarget此时 Affix 只监听该容器的滚动事件容器内部的滚动才会触发固定页面本身的滚动不会影响它。全局配置通过 NzConfig 统一设置偏移表格中nzOffsetTop与nzOffsetBottom标注了全局配置 ✅意味着可以通过 ng-zorro-antd 的全局配置服务统一设置无需在每个组件实例上重复传入。全局配置类型定义于 components/core/config/config.tsexport interface AffixConfig { nzOffsetBottom?: number; nzOffsetTop?: number; }配置方式例如在app.config.ts中import { provideNzConfig } from ng-zorro-antd/core/config; const nzConfig { affix: { nzOffsetTop: 80, // 全局默认顶部偏移 nzOffsetBottom: 40 // 全局默认底部偏移 } }; export const appConfig: ApplicationConfig { providers: [provideNzConfig(nzConfig)] };实例上显式传入的nzOffsetTop/nzOffsetBottom会覆盖全局配置源码中WithConfig()装饰器即实现实例值优先、否则回退全局值的合并逻辑。源码级实现原理要真正驾驭 Affix理解其底层机制很有帮助。核心逻辑集中在 components/affix/affix.component.ts1. 事件监听与节流组件在构造时通过effect注册监听affix.component.ts并借助ngZone.runOutsideAngular将事件处理移出 Angular Zone 以减少不必要的变更检测开销。监听的事件定义于 components/affix/respond-events.tsexport enum AffixRespondEvents { resize resize, scroll scroll, touchstart touchstart, touchmove touchmove, touchend touchend, pageshow pageshow, load LOAD }所有事件流与NzResizeObserver观察到的尺寸变化合并后统一经过throttleTime(20ms)节流常量NZ_AFFIX_DEFAULT_SCROLL_TIME 20见 affix.component.ts最终驱动updatePosition重算位置。2. 占位元素与双样式机制这是 Affix 最精妙的设计组件模板affix.component.ts在内部包了一层div #fixedEl来装载投影内容ng-content而组件宿主本身充当占位元素div #fixedEl ng-content / /div占位样式placeholderStyle当内容被固定脱离文档流时宿主元素会被赋予与固定内容相同的width与height从而撑住原布局位置避免下方内容上跳固定样式affixStyle内部fixedEl被设置为position: fixed并定位到视口或容器相应位置同时添加ant-affix类常量NZ_AFFIX_CLS_PREFIX见 affix.component.ts。固定时元素的实际定位计算顶部模式为affix.component.tsif (scrollTop elemOffset.top - (offsetTop as number) offsetMode.top) { const width elemOffset.width; const top targetRect.top (offsetTop as number); this.setAffixStyle(e, { position: fixed, top, left: targetRect.left elemOffset.left, width }); ... }其中元素相对容器的偏移由工具函数getOffset计算affix.component.tsgetTargetRect则区分窗口返回全零矩形与普通元素返回getBoundingClientRect()实现见 components/affix/utils.ts。3. 与文档一致的行为细节固定/解除固定只改变内部fixedEl的样式与ant-affix类不销毁、不重建投影内容方向RTL/LTR变化时组件会重新计算位置构造函数中effect读取dir()信号滚动事件经过 20ms 节流且带trailing选项保证连续滚动时高频位置更新被合并性能可控。注意事项与避坑指南nz-affix内的元素不要使用绝对定位position: absolute因为固定定位fixed与绝对定位叠加会破坏相对定位基准。如确实需要绝对定位效果官方文档给出的做法是直接对nz-affix本身设置绝对定位nz-affix styleposition: absolute; top: 10px, left: 10px ... /nz-affix另外两点实践建议固定元素会脱离文档流Affix 已通过占位元素保持布局稳定但请避免在视口过小的场景下使用防止固定内容遮挡正文页面中存在横向滚动条时注意固定元素以left定位相对滚动容器左侧若容器宽度小于元素宽度可能造成截断必要时结合全局配置调整偏移。小结Affix 是长页面场景下提升可用性的基础组件其核心 API 只有四个顶部偏移nzOffsetTop默认 0、底部偏移nzOffsetBottom、自定义滚动容器nzTarget默认window以及固定状态回调nzChange。通过全局配置NzConfig的affix节点可以统一管理前两个偏移参数。从源码看它依靠滚动/触摸/尺寸变化事件 20ms 节流驱动位置重算并用宿主占位 内部 fixed 样式的双层结构在固定时保持布局稳定——理解这一机制有助于在复杂布局中正确地使用并排查 Affix 相关的定位问题。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Affix 固钉组件完全指南让页面元素吸附视口ng zorro antd Affix 固钉组件完全指南让页面元素吸附视口 Affix固钉是 ng zorro antd 提供的一个基础布局组件当用户浏UI组件前端ng-zorro-antd Collapse 折叠面板组件完全指南从 API 配置到源码实现剖析ng zorro antd Collapse 折叠面板组件完全指南从 API 配置到源码实现剖析 导读 本文是 ng zorro antd 中 CollapsUI组件前端ng-zorro-antd Affix 组件 nzChange 回调固定状态监听与源码原理深入解析ng zorro antd Affix 组件 nzChange 回调固定状态监听与源码原理深入解析 nz affix 固钉是 ng zorro antdUI组件前端上一篇终极指南3步让老旧Mac免费升级到最新macOS系统下一篇Anki间隔重复记忆系统完整指南免费开源的高效学习工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
