前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载本文围绕 ant-design-vue 官方文档中 Anchor 锚点组件的使用说明展开系统讲解它的核心用途、全部 Props/事件/AnchorItem 配置、数据化items与嵌套子链接用法、以及如何基于仓库源码理解其高亮与滚动跳转的底层实现。读完本文你将能够在 Vue 3 项目中快速落地一个支持固定定位、自定义高亮、横向导航和滚动偏移控制的企业级锚点导航。组件定位与适用场景Anchor锚点用于跳转到页面指定位置它会在页面上渲染一组可点击的锚点链接点击后页面平滑滚动到对应的目标区块并随滚动自动高亮当前所处的章节。ant-design-vue 文档给出的“何时使用”标准是需要展现当前页面上可供跳转的锚点链接以及快速在锚点之间跳转。典型应用场景包括长文档/帮助中心页面的章节目录如本仓库中components/anchor/index.zh-CN.md这类 API 文档的侧边导航表单、详情页等长页面的分段导航教程类站点的内容大纲与进度指示。组件完整源码位于 components/anchor/Anchor.tsx入口聚合在 components/anchor/index.tsx挂载为Anchor与Anchor.Link两个组件测试用例可参考 components/anchor/tests/Anchor.test.js。基础用法数据化 items 配置从 4.0 版本开始Anchor 推荐使用items数据化配置选项内容支持通过children进行嵌套。以仓库中 components/anchor/demo/basic.vue 的最简示例为蓝本template a-anchor :items[ { key: part-1, href: #part-1, title: () h(span, { style: color: red }, Part 1), }, { key: part-2, href: #part-2, title: Part 2, }, { key: part-3, href: #part-3, title: Part 3, }, ] / /template script langts setup import { h } from vue; /script要点说明每个 item 的href必须以#开头并指向页面中真实存在的元素id如#part-1对应div idpart-1title既可以是纯字符串也可以是函数函数接收当前 item 并返回 VueNode可用于渲染富文本标题key是唯一标志用于 Vue 的列表 diff 与嵌套结构稳定渲染。items的结构化渲染在源码 components/anchor/Anchor.tsx 的createNestedLink中实现它遍历items数组把children递归地继续生成为嵌套的AnchorLink并在direction vertical垂直时才渲染子级水平方向不支持嵌套详见下文。传统写法Anchor Link 组合已弃用在items引入之前官方写法是组合Anchor与Link子组件例如template a-anchor a-link href#part-1 titlePart 1 / a-link href#part-2 titlePart 2 a-link href#part-2-1 titlePart 2-1 / /a-link /a-anchor /template源码 components/anchor/Anchor.tsx 在非生产环境会输出开发警告Anchor childrenis deprecated. Please useitemsinstead.即Anchor的默认插槽children写法已废弃请改用items。Link的独立实现见 components/anchor/AnchorLink.tsx其href默认值为#通过registerLink/unregisterLink与父级 Anchor 通信context 定义于 components/anchor/context.ts。Anchor Props 完整参数表成员说明类型默认值版本affix固定模式booleantruebounds锚点区域边界number5(px)getContainer指定滚动的容器() HTMLElement() windowgetCurrentAnchor自定义高亮的锚点(activeLink: string) string-activeLink(3.3)offsetBottom距离窗口底部达到指定偏移量后触发numberoffsetTop距离窗口顶部达到指定偏移量后触发numbershowInkInFixed:affixfalse时是否显示小方块booleanfalsetargetOffset锚点滚动偏移量默认与 offsetTop 相同numberoffsetTop1.5.0wrapperClass容器的类名string-wrapperStyle容器样式object-items数据化配置选项内容支持通过 children 嵌套{ key, href, title, target, children }[]-4.0direction设置导航方向vertical|horizontalvertical4.0customTitle使用插槽自定义选项 titlev-slotAnchorItem-4.0参数定义可以在源码 components/anchor/Anchor.tsx 的anchorProps()中找到对应实现下面结合实现逐项深入说明。affix 与 offsetTop / offsetBottom固定模式affix默认true即默认启用固定定位渲染时 Anchor 会被包裹在Affix组件内源码中!affix ? anchorContent : Affix offsetTop{offsetTop} target{getContainer.value}吸附在页面顶部不随滚动移出视口offsetTop表示锚点距离窗口顶部达到指定偏移量后触发固定offsetBottom表示距离窗口底部达到指定偏移量后触发固定二者与Affix的语义一致当affix{false}时Anchor 不浮动状态也不随页面滚动变化对应仓库示例 components/anchor/demo/static.vue 的“静态位置”用法。值得注意的细节源码中当设置了offsetTop时容器会被加上maxHeight: calc(100vh - ${offsetTop}px)的样式约束避免固定后内容超出视口高度。bounds 与 getCurrentAnchor高亮判定与自定义高亮bounds默认 5px指锚点区域边界目标区块顶部进入视口滚动容器内offsetTop bounds范围内即视为“当前区块”。源码getCurrentAnchor中判定条件为top offsetTop bounds并在所有满足条件的 section 中取top最大者作为当前激活链接getCurrentAnchor允许自定义高亮的锚点接收内部计算出的activeLink作为参数并返回最终要高亮的链接3.3 版本起回调参数可用。仓库示例 components/anchor/demo/customizeHighlight.vue 演示了强制高亮固定链接template a-anchor :affixfalse :get-current-anchorgetCurrentAnchor :items[...] /a-anchor /template script langts setup const getCurrentAnchor () { return #components-anchor-demo-static; }; /script对应实现位于 components/anchor/Anchor.tsx 的setCurrentActiveLink当传入getCurrentAnchor函数时激活链接会改写为该函数的返回值。getContainer指定滚动容器默认滚动容器是window当锚点应用于页面内部某个可滚动区域时通过getContainer返回该容器元素。源码中容器的解析优先级为props.getContainer || config-provider 注入的 getTargetContainer || () window见 components/anchor/Anchor.tsx 的getContainercomputed。同时onUpdated中会对比容器是否变化若变化则重新绑定scroll事件监听并立即计算一次激活链接。showInkInFixed静态模式下的指示小方块showInkInFixed默认false。当affix{false}时Anchor 默认不显示左侧/顶部的指示小方块ink设置为true可以强制显示。注意源码中锚点容器类名有一个细节${pre}-fixed仅在!affix !showInkInFixed时添加即静态且不显示小方块时才标记为 fixed 布局。targetOffset锚点滚动偏移量1.5.0targetOffset用于设置点击锚点后的目标滚动偏移量默认与offsetTop相同。它决定了滚动后目标区块停留在视口中的位置——例如希望章节标题滚动到屏幕正中间可将targetOffset设为视口高度的一半。仓库示例 components/anchor/demo/targetOffset.vue 的用法template a-anchor :target-offsettargetOffset :items[...] /a-anchor /template script langts setup import { onMounted, ref } from vue; const targetOffset refnumber | undefined(undefined); onMounted(() { targetOffset.value window.innerHeight / 2; }); /script在源码handleScrollTo中滚动目标y的计算为y scrollTop eleOffsetTop - (targetOffset ! undefined ? targetOffset : offsetTop || 0)可见targetOffset优先级高于offsetTop。wrapperClass / wrapperStyle容器定制wrapperClass容器的自定义类名stringwrapperStyle容器的自定义样式object会与默认的maxHeight计算值合并用户传入样式优先级更高。direction垂直 / 水平导航4.0direction支持vertical默认与horizontal两种导航方向。横向模式下锚点链接在一行内水平排列指示小方块变为水平滑动条并通过scrollIntoView让激活项保持在可视范围内见 components/anchor/Anchor.tsx 的updateInk。仓库示例 components/anchor/demo/horizontal.vuea-anchor directionhorizontal :items[ { key: horizontally-part-1, href: #horizontally-part-1, title: Part 1 }, { key: horizontally-part-2, href: #horizontally-part-2, title: Part 2 }, // ...更多项 ] /限制横向模式下items不支持children嵌套。源码在开发环境会输出警告Anchor items#childrenis not supported whenAnchordirection is horizontal.同时createNestedLink中只有direction vertical时才递归渲染children。customTitle插槽自定义标题4.0customTitle是一个作用域插槽槽内会注入当前AnchorItem对象用于完全自定义每个链接的标题渲染例如加入图标、徽标等复杂结构template a-anchor :itemsitems template #customTitle{ href, title } span my-icon / {{ title }} /span /template /a-anchor /template对应实现Anchor会把customTitle插槽透传给每一个AnchorLink见 components/anchor/Anchor.tsx 的createNestedLink与 components/anchor/AnchorLink.tsx 中slots.customTitle(customTitleProps)的调用。AnchorItem 数据结构items中的每一项AnchorItem字段如下成员说明类型默认值版本key唯一标志string | number-href锚点链接string-target该属性指定在何处显示链接的资源string-title文字内容VueNode \| (item: AnchorItem) VueNode-children嵌套的 Anchor Link注意水平方向该属性不支持AnchorItem[]-类型定义在源码 components/anchor/AnchorLink.tsx 的AnchorLinkItemProps接口中key、href、target、title、children并额外支持class与style。title为函数时源码会以当前 item 为参数调用title(customTitleProps)得到渲染节点。嵌套示例参考 components/anchor/demo/onChange.vuea-anchor :affixfalse :items[ { key: 1, href: #components-anchor-demo-basic, title: Basic demo, }, { key: 3, href: #api, title: API, children: [ { key: 4, href: #anchor-props, title: Anchor Props }, { key: 5, href: #link-props, title: Link Props }, ], }, ] /事件Events事件名称说明回调参数版本change监听锚点链接改变(currentActiveLink: string) void1.5.0clickclick事件的 handlerFunction(e: MouseEvent, link: Object)change监听锚点链接改变滚动经过不同区块或点击链接时触发回调参数为当前激活的锚点链接字符串。示例components/anchor/demo/onChange.vuetemplate a-anchor :affixfalse :itemsitems changeonChange / /template script langts setup const onChange (link: string) { console.log(Anchor:OnChange, link); }; /script源码中setCurrentActiveLink在激活链接变化时通过emit(change, link)发出该事件因此仅在激活链接真正变化时触发。click自定义点击行为点击锚点链接时触发回调参数为(e: MouseEvent, link: Object)其中link包含{ title, href }。通过e.preventDefault()可以阻止默认跳转/记录历史。示例components/anchor/demo/onClick.vuetemplate a-anchor :affixfalse :itemsitems clickhandleClick / /template script langts setup import type { AnchorProps } from ant-design-vue; const handleClick: AnchorProps[onClick] (e, link) { e.preventDefault(); console.log(link); }; /script事件派发链路AnchorLink内点击a时调用contextHandleClick(e, { title: mergedTitle, href })并继续scrollTo(href)见 components/anchor/AnchorLink.tsx父级 Anchor 的 context 收到后emit(click, e, info)见 components/anchor/Anchor.tsx 的useProvideAnchor。Link Props传统子组件若仍使用传统Anchor.Link写法其 Props 如下成员说明类型默认值版本href锚点链接string#target该属性指定在何处显示链接的资源string1.5.0title文字内容string | slothref默认值#定义于 components/anchor/AnchorLink.tsx 的initDefaultProps(anchorLinkProps(), { href: # })title同时支持属性传值与具名插槽#titletarget直接透传到渲染出的a标签上_blank等值。源码级原理锚点如何工作链接注册与激活高亮Anchor 通过 Vue 3 的provide / injectcomponents/anchor/context.ts向所有AnchorLink提供registerLink/unregisterLink/activeLink/scrollTo/handleClick/direction。每个AnchorLink挂载时注册自己的href卸载或href变化时注销旧值并注册新值watch 逻辑见 components/anchor/AnchorLink.tsx父级维护links数组。激活高亮的核心流程components/anchor/Anchor.tsx组件挂载后监听滚动容器的scroll事件addEventListener(container, scroll, handleScroll)滚动时遍历所有注册链接用正则/#([\S ])$/提取href中的元素 id通过getElementById找到目标元素计算其相对滚动容器的top收集所有top offsetTop bounds的链接取top最大者作为当前激活链接setCurrentActiveLink更新activeLink激活的AnchorLink渲染-link-active样式类指示小方块ink通过updateInk移动到对应位置。点击跳转与平滑滚动点击链接时handleScrollTocomponents/anchor/Anchor.tsx计算目标滚动位置y 当前滚动高度 元素相对偏移 - (targetOffset ?? offsetTop ?? 0)然后调用scrollTo工具进行平滑滚动。该工具实现在 components/_util/scrollTo.ts基于requestAnimationFrame与easeInOutCubic缓动函数默认动画时长450ms滚动期间animating置为true从而在滚动过程中忽略滚动事件、避免高亮抖动。测试验证components/anchor/tests/Anchor.test.js 覆盖了渲染、点击、onChange回调以及完整 URL如http://www.example.com/#api等场景验证了带完整前缀的链接同样能被解析与高亮components/anchor/tests/demo.test.js 与快照则保证各 demo 可正常渲染。样式入口位于 components/anchor/style/index.ts。常见问题与使用建议链接没有高亮/点击无反应检查href指向的元素id是否真实存在且href以#开头滚动容器必须是getContainer指定的那个容器。固定模式下被遮挡合理设置offsetTop并让targetOffset保持一致或按需调整保证高亮判定与最终落点一致。页面有固定 HeadertargetOffset应不小于 Header 高度否则锚点目标会被 Header 遮住。横向导航不要用children源码会在开发环境给出告警且子级不会被渲染。避免混用新旧写法Anchor的默认插槽children已标记废弃新代码一律使用itemscustomTitle。页面锚点目标位于自定义滚动容器内务必通过getContainer显式指定容器否则组件监听的是window滚动无法正确计算位置。以上配置项与事件均可对照 components/anchor/index.en-US.md 及仓库内各 demo 用例components/anchor/demo/进行二次验证与扩展实践。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐Ant Design Anchor 组件完全指南页面内锚点导航的配置、事件与源码原理Ant Design Anchor 组件完全指南页面内锚点导航的配置、事件与源码原理 Anchor 是 Ant Design 提供的页面内锚点Hyperli前端UI组件设计系统Ant Design Anchor 锚点组件完全指南API 配置、滚动高亮原理与实战示例Ant Design Anchor 锚点组件完全指南API 配置、滚动高亮原理与实战示例 Ant Design 的 Anchor锚点组件用于在单页内展示可前端UI组件设计系统为什么选择Qwen3.5-27B-Claude-4.6-Opus蒸馏模型10个核心优势详解为什么选择Qwen3.5 27B Claude 4.6 Opus蒸馏模型10个核心优势详解 在人工智能快速发展的今天Qwen3.5 27B Claude 4前端UI组件设计系统上一篇NocoBase 区块高度配置全指南默认高度、指定高度与全高模式原理详解下一篇MetaFormer架构核心解密convformer_b36.sail_in22k代码实现原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考