Element Plus Anchor 锚点组件完整指南快速定位、滚动监听与源码原理解析【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusAnchor锚点组件是 Element Plus 中用于页面快速定位的核心导航组件它通过一组可点击的锚点链接帮助用户在长页面中快速跳转到指定信息位置并自动高亮当前所在的章节。本指南将围绕 Element Plus 官方文档对 Anchor 组件的完整介绍结合仓库源码packages/components/anchor深入讲解其基础用法、横向模式、滚动容器、事件监听、下划线样式、Affix 固定模式以及完整的 Attributes / Events / Exposes / Slots API帮助你从会用到懂原理。基础用法Anchor 最基本的使用方式在el-anchor内部放置多个el-anchor-link每个链接通过href指向页面内对应元素通常是带id的区块通过title或默认插槽设置链接文本。template el-anchor :offset70 el-anchor-link :href#basic-usageBasic Usage/el-anchor-link el-anchor-link :href#horizontal-modeHorizontal Mode/el-anchor-link el-anchor-link :href#scroll-containerScroll Container/el-anchor-link el-anchor-link :href#anchor-api Anchor API template #sub-link el-anchor-link :href#anchor-attributesAnchor Attributes/el-anchor-link el-anchor-link :href#anchor-eventsAnchor Events/el-anchor-link /template /el-anchor-link /el-anchor /template这是官方文档anchor/basic示例docs/examples/anchor/basic.vue的简化形态。可以看到el-anchor-link支持嵌套的sub-link插槽来渲染二级子链接实现层级目录结构。页面滚动时当前处于视口内的章节所对应的链接会自动高亮。从源码看每个el-anchor-link挂载后会通过addLink将自身的href与 DOM 元素注册到父级el-anchor见 packages/components/anchor/src/anchor-link.vue 的onMounted父级通过getCurrentHref计算各目标元素与滚动容器的距离来判断当前激活项整个过程借助provide / injectpackages/components/anchor/src/constants.ts 中的anchorKey实现父子通信。横向模式Anchor 默认是垂直排列directionvertical通过设置directionhorizontal可以让锚点链接水平对齐排列适合页面顶部的章节导航条。template el-anchor :offset70 directionhorizontal el-anchor-link :href#basic-usageBasic Usage/el-anchor-link el-anchor-link :href#horizontal-modeHorizontal Mode/el-anchor-link el-anchor-link :href#scroll-containerScroll Container/el-anchor-link /el-anchor /template对应官方文档anchor/horizontal示例docs/examples/anchor/horizontal.vue。需要特别注意的是横向模式不支持sub-link子链接插槽。这一点在 anchor-link 的渲染逻辑中有明确体现只有direction vertical时才会渲染sub-link插槽内容见 packages/components/anchor/src/anchor-link.vue 模板中的v-if$slots[sub-link] direction vertical。自定义滚动容器当页面内容较多、需要放在独立的可滚动区域如高度受限的div内时可以通过container属性指定滚动容器并配合offset设置锚点滚动偏移量。template el-row el-col :span18 !-- 自定义滚动容器 -- div refcontainerRef styleheight: 300px; overflow-y: auto div idpart1 styleheight: 300pxpart1/div div idpart2 styleheight: 300pxpart2/div div idpart3 styleheight: 300pxpart3/div /div /el-col el-col :span6 el-anchor :containercontainerRef directionvertical typedefault :offset30 clickhandleClick el-anchor-link href#part1 titlepart1 / el-anchor-link href#part2 titlepart2 / el-anchor-link href#part3 titlepart3 / /el-anchor /el-col /el-row /template script setup langts import { ref } from vue const containerRef refHTMLElement | null(null) const handleClick (e: MouseEvent) { e.preventDefault() } /script这是官方文档anchor/scroll示例docs/examples/anchor/scroll.vue的核心逻辑。这里有几个要点container可以直接传ref元素引用也可以传 CSS 选择器字符串还可以省略此时默认滚动容器为window。源码中的getContainerpackages/components/anchor/src/anchor.vue通过getElement解析容器若未匹配到元素或为Window则回退到window全局滚动。offset用于设置锚点滚动偏移量避免跳转后目标区块被页面的固定头部遮挡。点击链接后组件计算目标元素到滚动容器的距离并减去offset得到最终的滚动位置。监听link-click即click事件并调用e.preventDefault()阻止浏览器默认行为后跳转将不会修改浏览器历史记录URL hash 不会变化这适合纯业务逻辑的滚动场景。源码层面的滚动流程从 packages/components/anchor/src/anchor.vue 的实现可以看到完整的调用链点击链接触发handleClick对外派发click事件参数为MouseEvent和href随后调用scrollTo(href)scrollTo先调用setCurrentAnchor更新当前高亮项再调用scrollToAnchor执行滚动scrollToAnchor通过getElement(href)定位目标元素用getOffsetTopDistance计算目标距滚动容器的距离将distance - offset与容器最大可滚距离scrollHeight - clientHeight取最小值然后交给animateScrollTo以duration默认 300ms完成平滑滚动滚动结束后通过setTimeout约 20ms将isScrolling复位确保后续滚动监听能继续正常计算当前激活项。监听锚点切换事件通过change事件可以监听当前激活锚点的变化适合配合埋点统计、面包屑联动或目录高亮等场景。template el-anchor :offset70 changehandleChange el-anchor-link href#basic-usageBasic Usage/el-anchor-link el-anchor-link href#scroll-containerScroll Container/el-anchor-link /el-anchor /template script setup langts const handleChange (href: string) { console.log(anchor change: ${href}) } /script官方文档anchor/change示例docs/examples/anchor/change.vue展示了handleChange的用法。在源码中change事件通过CHANGE_EVENT常量派发且只有当激活项真正发生变化时才会触发setCurrentAnchor中activeHref ! href判断避免无效回调。激活项的判定逻辑getCurrentHref值得展开说明遍历所有已注册链接计算每个目标元素的触发位置distance - offset - bound其中bound默认 15表示元素开始触发锚点的偏移量即目标区块进入视口一定距离后才激活对应链接当滚动条位于最顶部scrollTop 0时默认不选中任何链接若设置select-scroll-top2.9.2 新增为true则滚动到顶部时选中第一个链接其余情况按触发位置排序后选中当前滚动位置落在其区间内的那一项。下划线类型默认 Anchor 通过左侧的 Marker 指示器标识当前章节设置typeunderline可切换为下划线样式当前激活链接下方会显示一条横线。template el-anchor typeunderline :offset70 el-anchor-link href#basic-usageBasic Usage/el-anchor-link el-anchor-link href#horizontal-modeHorizontal Mode/el-anchor-link el-anchor-link href#scroll-containerScroll Container/el-anchor-link /el-anchor /template对应官方文档anchor/underline示例docs/examples/anchor/underline.vue。样式层由useNamespace(anchor)生成的 BEM 类名控制根节点会追加is-underline修饰类见 packages/components/anchor/src/anchor.vue 中的cls计算逻辑主题样式定义在 packages/theme-chalk/src 的 anchor 相关 scss 文件中。Affix 固定模式配合 Affix 组件可以将锚点固定在页面中实现阅读长文档时目录始终跟随的体验——这正是本组件在 Element Plus 官方文档站中的典型用法。template el-affix :offset60 el-anchor :offset70 stylewidth: 300px el-anchor-link href#basic-usageBasic Usage/el-anchor-link el-anchor-link href#anchor-api Anchor API template #sub-link el-anchor-link href#anchor-attributesAnchor Attributes/el-anchor-link /template /el-anchor-link /el-anchor /el-affix /template官方文档anchor/affix示例docs/examples/anchor/affix.vue展示了组合方式外层el-affix的offset控制固定后距视口顶部的距离内层el-anchor的offset控制滚动跳转时目标区块的偏移补偿。两层 offset 各司其职一个管目录固定位置一个管正文跳转位置。Anchor 的纵向空间有限时可显式设置宽度如width: 300px避免布局挤压。Anchor API 完整参考Anchor Attributes属性说明类型默认值container滚动容器string|HTMLElement|Window—offset锚点滚动偏移量number0bound元素开始触发锚点的偏移量number15duration滚动容器滚动时长毫秒number300marker是否显示 marker 指示器booleantruetypeAnchor 类型default \| underlinedefaultdirectionAnchor 方向vertical \| horizontalverticalselect-scroll-top2.9.2滚动到顶部时是否选中链接booleanfalse这些默认值在源码的withDefaults(definePropsAnchorProps(), ...)中逐一落地packages/components/anchor/src/anchor.vue完整 Props 类型定义见 packages/components/anchor/src/anchor.ts 的AnchorProps接口其中包含逐条 JSDoc 注释可供 IDE 悬浮提示使用。参数说明补充container未传或传入无效选择器时默认使用window全局滚动见getContainer实现bound数值越大目标区块越早距离视口顶部更远时触发激活duration仅影响点击链接后的平滑滚动动画时长不影响页面手动滚动的监听响应marker设为false可隐藏随激活项移动的指示器仅保留文字高亮select-scroll-top默认false时滚动回到页面顶部会清空选中态设为true后顶部始终选中第一个链接。Anchor Events事件名说明类型change当前激活锚点变化时触发(href: string) voidclick点击链接时触发(e: MouseEvent, href?: string) void在 anchor.ts 的anchorEmits中change回调校验href必须为字符串click回调校验第一个参数必须是MouseEvent。注意点击事件无论是否preventDefault都会先触发之后组件内部再执行滚动因此你可以在click中拦截默认行为阻止 hash 历史变更或补充自定义逻辑。Anchor Exposes名称说明类型scrollTo手动滚动到指定位置(href: string) void通过ref拿到组件实例后可调用scrollTo编程式跳转。源码中scrollTo会先setCurrentAnchor同步高亮再执行平滑滚动defineExpose导出于 anchor.vue。这可以用于点击面包屑跳转、URL 带 hash 进入页面时自动定位等场景——事实上组件在onMounted时就会读取window.location.hash若命中已注册链接则自动滚动过去。Anchor Slots插槽名说明defaultAnchorLink 组件列表AnchorLink Attributes属性说明类型默认值title锚点链接的文本内容string—href锚点链接地址string—title与默认插槽二选一即可若同时使用插槽内容优先模板中:href渲染在a标签上插槽未提供内容时才显示title。属性定义见 anchor-link.ts。AnchorLink Slots插槽名说明default锚点链接内容sub-link子链接插槽sub-link用于渲染二级目录且仅在directionvertical时生效横向模式不支持见上文横向模式一节。结合测试用例理解激活与点击行为仓库中 Anchor 组件的自动化测试位于 packages/components/anchor/tests/anchor.test.tsx快照见 anchor.test.tsx.snap。测试覆盖了基础渲染、scrollTo暴露方法的调用、change事件的触发等核心行为与上述源码逻辑一一对应。如果你需要扩展 Anchor 的定制场景如自定义高亮样式、配合其他滚动库建议先阅读这些测试以理解组件行为的边界条件。总结Element Plus 的 Anchor 组件围绕链接注册—滚动计算—激活高亮—平滑跳转这条主线设计el-anchor-link负责注册目标与渲染层级el-anchor负责滚动监听、激活判定与滚动动画二者通过provide/inject解耦通信。本文从官方文档的六个使用场景出发结合 anchor.vue、anchor-link.vue 等源码完整覆盖了 Attributes / Events / Exposes / Slots 全部 API。掌握这些内容后你可以在长文档、帮助中心、数据看板等场景中快速搭建带目录导航、滚动联动与固定定位的页面结构。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考