Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Anchor 锚点
列出页面里的几个章节,点了滚动到对应位置,滚动时高亮当前所在的章节。
引入
import { NsAnchor } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
基础用法
items 里每一项的 href 写成 #id,指向页面上 id 相同的元素(也可以是 data-anchor-id 相同的元素)。点击链接平滑滚动到那个元素;滚动时,已经滚过顶部的章节里最靠下的那个会高亮。
不传 container 时监听页面滚动。为了方便看效果,本页的示例都放在固定高度的滚动容器里,用 container 指向这个容器(用法见下面的“自定义滚动容器”)。点右边的链接,或者在左边的框里滚动:
<script setup lang="ts">
import { NsAnchor } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const items: AnchorItem[] = [
{ href: '#anchor-basic-1', title: '基本信息' },
{ href: '#anchor-basic-2', title: '联系方式' },
{ href: '#anchor-basic-3', title: '账号设置' }
]
</script>
<template>
<div class="layout">
<div id="anchor-basic-box" class="box">
<section id="anchor-basic-1" class="section">基本信息</section>
<section id="anchor-basic-2" class="section">联系方式</section>
<section id="anchor-basic-3" class="section">账号设置</section>
</div>
<NsAnchor :items="items" container="#anchor-basic-box" />
</div>
</template>
<style scoped>
.layout {
display: flex;
gap: 24px;
}
.box {
flex: 1;
height: 240px;
overflow: auto;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.section {
height: 280px;
padding: 16px;
border-bottom: 1px dashed var(--ns-border-color);
color: var(--ns-text-color-secondary);
}
</style>
风格
type 可选 rail(默认,左边有一条轨道,当前项旁边有一段高亮的墨条)和 block(当前项显示成带浅色背景的块)。rail 风格下 show-rail 设成 false 可以去掉轨道和墨条,只靠文字颜色标出当前项;block 风格下 show-rail 不起作用。
下面三个锚点监听同一个滚动容器,滚动时一起变化:
<script setup lang="ts">
import { NsAnchor } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const items: AnchorItem[] = [
{ href: '#anchor-type-1', title: '基本信息' },
{ href: '#anchor-type-2', title: '联系方式' },
{ href: '#anchor-type-3', title: '账号设置' }
]
</script>
<template>
<div class="layout">
<div id="anchor-type-box" class="box">
<section id="anchor-type-1" class="section">基本信息</section>
<section id="anchor-type-2" class="section">联系方式</section>
<section id="anchor-type-3" class="section">账号设置</section>
</div>
<div>
<p class="row-label">rail</p>
<NsAnchor :items="items" type="rail" container="#anchor-type-box" />
</div>
<div>
<p class="row-label">rail,show-rail=false</p>
<NsAnchor :items="items" :show-rail="false" container="#anchor-type-box" />
</div>
<div>
<p class="row-label">block</p>
<NsAnchor :items="items" type="block" container="#anchor-type-box" />
</div>
</div>
</template>
<style scoped>
.layout {
display: flex;
flex-wrap: wrap;
gap: 24px;
}
.box {
flex: 1;
min-width: 200px;
height: 240px;
overflow: auto;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.section {
height: 280px;
padding: 16px;
border-bottom: 1px dashed var(--ns-border-color);
color: var(--ns-text-color-secondary);
}
.row-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
顶部偏移
滚动区域顶部有固定的导航栏时,用 target-offset 设置它的高度:点击跳转时目标停在离顶部这么远的位置,判断高亮时也按这个位置算。bound 是判断高亮时再额外放宽的距离,默认 10,章节标题滚到离偏移线不到这个距离时就算进入了这一节。
下面的框顶部有一条 40px 高、贴住不动的标题栏。左边的锚点设了 :target-offset="40",点击后章节标题露在标题栏下面;中间的没设,章节标题被标题栏挡住;右边设了 :bound="120",章节离顶部还有 160px 时就提前高亮。
<script setup lang="ts">
import { NsAnchor } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const items: AnchorItem[] = [
{ href: '#anchor-offset-1', title: '基本信息' },
{ href: '#anchor-offset-2', title: '联系方式' },
{ href: '#anchor-offset-3', title: '账号设置' }
]
</script>
<template>
<div class="layout">
<div id="anchor-offset-box" class="box">
<div class="header">固定的标题栏(40px)</div>
<section id="anchor-offset-1" class="section">基本信息</section>
<section id="anchor-offset-2" class="section">联系方式</section>
<section id="anchor-offset-3" class="section">账号设置</section>
</div>
<div>
<p class="row-label">target-offset=40</p>
<NsAnchor :items="items" :target-offset="40" container="#anchor-offset-box" />
</div>
<div>
<p class="row-label">不设</p>
<NsAnchor :items="items" container="#anchor-offset-box" />
</div>
<div>
<p class="row-label">bound=120</p>
<NsAnchor :items="items" :target-offset="40" :bound="120" container="#anchor-offset-box" />
</div>
</div>
</template>
<style scoped>
.layout {
display: flex;
flex-wrap: wrap;
gap: 24px;
}
.box {
flex: 1;
min-width: 200px;
height: 240px;
overflow: auto;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.header {
position: sticky;
top: 0;
z-index: 1;
height: 40px;
padding: 0 16px;
line-height: 40px;
background-color: var(--ns-color-primary);
color: var(--ns-color-white);
}
.section {
height: 280px;
padding: 16px;
border-bottom: 1px dashed var(--ns-border-color);
color: var(--ns-text-color-secondary);
}
.row-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
固定在侧边
affix 为 true 时锚点留在原来的位置,滚动时贴在滚动容器的顶部(离顶部 target-offset 像素),不会盖住正文。它用的是 position: sticky,只在父元素的范围内贴住,所以父元素要和正文一样高,常见的写法是和正文并排放在一个 flex 容器里。
下面锚点和正文都在滚动容器里,往下滚时锚点贴在离顶部 16px 处:
<script setup lang="ts">
import { NsAnchor } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const items: AnchorItem[] = [
{ href: '#anchor-affix-1', title: '简介' },
{ href: '#anchor-affix-2', title: '用法' },
{ href: '#anchor-affix-3', title: '常见问题' }
]
</script>
<template>
<div
id="anchor-affix-box"
style="height: 300px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<div style="display: flex; gap: 24px; padding: 0 16px">
<main style="flex: 1">
<section id="anchor-affix-1" style="height: 400px; padding-top: 16px">简介</section>
<section id="anchor-affix-2" style="height: 400px; padding-top: 16px">用法</section>
<section id="anchor-affix-3" style="height: 400px; padding-top: 16px">常见问题</section>
</main>
<NsAnchor :items="items" affix :target-offset="16" container="#anchor-affix-box" />
</div>
</div>
</template>
自定义滚动容器
内容在某个可以滚动的元素里时,用 container 指定这个元素,可以传 CSS 选择器、元素或 window。选择器在组件挂载时查找,找不到就用 window。
<script setup lang="ts">
import { NsAnchor } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const items: AnchorItem[] = [
{ href: '#part-1', title: '第一部分' },
{ href: '#part-2', title: '第二部分' },
{ href: '#part-3', title: '第三部分' }
]
</script>
<template>
<div style="display: flex; gap: 24px">
<div
id="anchor-demo-box"
style="flex: 1; height: 300px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<section id="part-1" style="height: 400px">第一部分</section>
<section id="part-2" style="height: 400px">第二部分</section>
<section id="part-3" style="height: 400px">第三部分</section>
</div>
<NsAnchor :items="items" container="#anchor-demo-box" />
</div>
</template>
自定义标题
title 除了字符串还可以是 VNode,比如在文字前面加图标。
<script setup lang="ts">
import { h } from 'vue'
import { NsAnchor, NsIcon } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const items: AnchorItem[] = [
{ href: '#anchor-title-1', title: h('span', [h(NsIcon, { name: 'user' }), ' 个人资料']) },
{ href: '#anchor-title-2', title: h('span', [h(NsIcon, { name: 'setting' }), ' 偏好设置']) },
{ href: '#anchor-title-3', title: h('span', [h(NsIcon, { name: 'bell' }), ' 消息通知']) }
]
</script>
<template>
<div style="display: flex; gap: 24px">
<div
id="anchor-title-box"
style="flex: 1; height: 240px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<section id="anchor-title-1" style="height: 280px; padding: 16px">个人资料</section>
<section id="anchor-title-2" style="height: 280px; padding: 16px">偏好设置</section>
<section id="anchor-title-3" style="height: 280px; padding: 16px">消息通知</section>
</div>
<NsAnchor :items="items" container="#anchor-title-box" />
</div>
</template>
监听高亮变化
当前高亮的项变化时触发 change,参数是新的 href 和原来的 href。点击链接时立即触发一次,第一次高亮时原来的 href 是空字符串。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAnchor } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const items: AnchorItem[] = [
{ href: '#anchor-change-1', title: '基本信息' },
{ href: '#anchor-change-2', title: '联系方式' },
{ href: '#anchor-change-3', title: '账号设置' }
]
const current = ref('')
const prev = ref('')
const handleChange = (currentHref: string, prevHref: string) => {
current.value = currentHref
prev.value = prevHref
}
</script>
<template>
<p style="margin: 0 0 12px">当前章节:{{ current || '无' }},上一个:{{ prev || '无' }}</p>
<div style="display: flex; gap: 24px">
<div
id="anchor-change-box"
style="flex: 1; height: 240px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<section id="anchor-change-1" style="height: 280px; padding: 16px">基本信息</section>
<section id="anchor-change-2" style="height: 280px; padding: 16px">联系方式</section>
<section id="anchor-change-3" style="height: 280px; padding: 16px">账号设置</section>
</div>
<NsAnchor :items="items" container="#anchor-change-box" @change="handleChange" />
</div>
</template>
用代码滚动
通过 ref 调用 scrollToAnchor(href),可以在代码里滚动到某个章节,效果和点链接时的滚动一样。ref 上还能读到当前高亮的 currentHref。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAnchor, NsButton, NsSpace } from '@ns/ui'
import type { AnchorItem } from '@ns/ui'
const anchorRef = ref<InstanceType<typeof NsAnchor>>()
const items: AnchorItem[] = [
{ href: '#anchor-method-1', title: '基本信息' },
{ href: '#anchor-method-2', title: '联系方式' },
{ href: '#anchor-method-3', title: '账号设置' }
]
</script>
<template>
<NsSpace wrap style="margin-bottom: 12px">
<NsButton @click="anchorRef?.scrollToAnchor('#anchor-method-1')">跳到基本信息</NsButton>
<NsButton @click="anchorRef?.scrollToAnchor('#anchor-method-2')">跳到联系方式</NsButton>
<NsButton @click="anchorRef?.scrollToAnchor('#anchor-method-3')">跳到账号设置</NsButton>
<span>currentHref:{{ anchorRef?.currentHref || '无' }}</span>
</NsSpace>
<div style="display: flex; gap: 24px">
<div
id="anchor-method-box"
style="flex: 1; height: 240px; overflow: auto; border: 1px solid var(--ns-border-color)"
>
<section id="anchor-method-1" style="height: 280px; padding: 16px">基本信息</section>
<section id="anchor-method-2" style="height: 280px; padding: 16px">联系方式</section>
<section id="anchor-method-3" style="height: 280px; padding: 16px">账号设置</section>
</div>
<NsAnchor ref="anchorRef" :items="items" container="#anchor-method-box" />
</div>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| items | AnchorItem[] | [] | 锚点列表 |
| targetOffset | number | 0 | 跳转后目标离滚动容器顶部的距离(px),判断高亮时也按它算;affix 时也是贴住的位置 |
| container | string | HTMLElement | Window | - | 滚动容器,字符串按 CSS 选择器查找。不传时挂载后用 window,选择器找不到时也用 window |
| bound | number | 10 | 判断高亮时额外加的距离(px):章节顶部滚到离顶部 targetOffset + bound 以内就算进入这一节 |
| affix | boolean | false | 是否在滚动时贴在滚动容器顶部(position: sticky) |
| type | 'block' | 'rail' | 'rail' | 风格 |
| showRail | boolean | true | rail 风格下是否显示左边的轨道和墨条,block 风格下不起作用 |
AnchorItem
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| href | string | - | 必填。写成 #id,对应页面上 id 或 data-anchor-id 相同的元素 |
| title | string | VNode | - | 必填。链接显示的内容 |
| target | '_self' | '_blank' | - | 写到链接的 target 属性上。点击会被组件拦截改成页面内滚动,对点击没有影响 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| change | (currentHref: string, prevHref: string) | 高亮的项变化时触发。点击链接时立即触发一次;变成没有高亮项时不触发。第一次高亮时 prevHref 是 '' |
暴露的属性和方法
通过组件的 ref 访问:
| 名称 | 类型 | 说明 |
|---|---|---|
| currentHref | string | 当前高亮的项的 href,没有高亮项时是 '' |
| inkVisible | boolean | rail 风格的墨条是否显示,有高亮项时为 true |
| scrollToAnchor | (href: string) => void | 平滑滚动到 href 对应的元素,找不到元素时什么都不做 |
类型
import type { AnchorProps, AnchorItem, AnchorTarget, AnchorType, AnchorEmits } from '@ns/ui'
import type { VNode } from 'vue'
type AnchorTarget = string | HTMLElement | Window
type AnchorType = 'block' | 'rail'
interface AnchorItem {
href: string
title: string | VNode
target?: '_self' | '_blank'
}
interface AnchorProps {
items?: AnchorItem[]
targetOffset?: number
container?: AnchorTarget
bound?: number
affix?: boolean
type?: AnchorType
showRail?: boolean
}
interface AnchorEmits {
change: [currentHref: string, prevHref: string]
}
注意事项
- 只支持一层链接,
AnchorItem没有children,不能嵌套。 - 组件没有插槽,链接只能通过
items生成。 href必须以#开头,指向当前页面里的元素;其他形式的地址找不到目标,点了不会滚动。- 点击链接只滚动,不改地址栏的 hash,刷新页面后不会回到这一节。
- 点击后在平滑滚动期间,高亮固定在点的那一项,滚动停下来以后才重新按位置计算。
- 最后几节内容很短、页面滚到底也到不了顶部时,直接滚动不会高亮它们,点链接可以高亮。
container指定的是滚动的那个元素(带overflow: auto或scroll),不是它外面的包裹元素。运行时修改container,滚动监听会跟着换。affix依赖position: sticky:锚点的父元素不能比锚点矮,祖先元素上的overflow: hidden也会让它失效。- 链接聚焦后可以用回车触发,当前项带
aria-current="location"。 - 服务端渲染时不访问
window,滚动监听在挂载后才绑定,卸载时自动移除。