锚点 - Semi Design Next

代码演示

如何引入

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

Anchor.Link 也可以按名导入：AnchorLink。

基本示例

使用 Link 可以创建锚点，点击它会跳转到指定位置。

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Anchor>
        <Anchor.Link href="#基本示例" title="基本示例" />
        <Anchor.Link href="#组件" title="组件" />
        <Anchor.Link href="#设计语言" title="设计语言" />
        <Anchor.Link href="#物料平台" title="物料平台" />
        <Anchor.Link href="#主题商店" title="主题商店" />
    </Anchor>
</template>

综合使用

你可以搭配 getContainer，targetOffset，style，offsetTop 完成一个拆箱即用的超链接导航栏。

滚动容器：你可以通过 getContainer 设置滚动内容的容器，默认值为 window 。
距离顶部的距离：可以通过设置 targetOffset 设置文档滚动结束时，锚点距离容器顶部的距离。
自定义定位方式：Anchor 自身不设置定位，你可以通过 style 对象为它指定定位方式，例如 position: fixed。
偏移距离：offsetTop 可以在滚动内容距离容器顶部达到指定偏移量时触发当前 Link 切换。

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';

    const getContainer = () => window;
</script>

<template>
    <div>
        <span>请看右侧固定的 Anchor </span>
        <Anchor :getContainer="getContainer" :offsetTop="100" :style="{ position: 'fixed', right: '20px', top: '100px', width: '200px', zIndex: 3 }" :targetOffset="100">
            <Anchor.Link href="#基本示例" title="我是固定的 Anchor" />
            <Anchor.Link href="#综合使用" title="综合使用" />
            <Anchor.Link href="#尺寸" title="尺寸" />
            <Anchor.Link href="#滑轨主题" title="滑轨主题" />
            <Anchor.Link href="#动态展示" title="动态展示" />
            <Anchor.Link href="#显示工具提示" title="显示工具提示" />
            <Anchor.Link href="#工具提示位置" title="工具提示位置" />
            <Anchor.Link href="#API参考" title="API参考">
                <Anchor.Link href="#Anchor" title="Anchor" />
                <Anchor.Link href="#Anchor.Link" title="Anchor.Link" />
            </Anchor.Link>
        </Anchor>
    </div>
</template>

尺寸

Anchor 设置 size 可以控制锚点的尺寸。

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Anchor size="default">
        <Anchor.Link href="#组件" title="组件" />
        <Anchor.Link href="#设计语言" title="设计语言" />
        <Anchor.Link href="#物料平台" title="物料平台" />
        <Anchor.Link href="#主题商店" title="主题商店" />
    </Anchor>
</template>

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Anchor size="small">
        <Anchor.Link href="#组件" title="组件" />
        <Anchor.Link href="#设计语言" title="设计语言" />
        <Anchor.Link href="#物料平台" title="物料平台" />
        <Anchor.Link href="#主题商店" title="主题商店" />
    </Anchor>
</template>

滑轨主题

Anchor 设置 railTheme 可以控制滑轨的主题色。默认值为 primary。

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Anchor :offsetTop="100" railTheme="primary" :targetOffset="60">
            <Anchor.Link href="#尺寸" title="尺寸" />
            <Anchor.Link href="#滑轨主题" title="滑轨主题" />
            <Anchor.Link href="#设计语言" title="设计语言" />
            <Anchor.Link href="#物料平台" title="物料平台" />
            <Anchor.Link href="#主题商店" title="主题商店" />
        </Anchor>
    </div>
</template>

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Anchor :offsetTop="100" railTheme="tertiary" :targetOffset="60">
            <Anchor.Link href="#尺寸" title="尺寸" />
            <Anchor.Link href="#滑轨主题" title="滑轨主题" />
            <Anchor.Link href="#设计语言" title="设计语言" />
            <Anchor.Link href="#物料平台" title="物料平台" />
            <Anchor.Link href="#主题商店" title="主题商店" />
        </Anchor>
    </div>
</template>

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Anchor :offsetTop="100" railTheme="muted" :targetOffset="60">
            <Anchor.Link href="#尺寸" title="尺寸" />
            <Anchor.Link href="#滑轨主题" title="滑轨主题" />
            <Anchor.Link href="#设计语言" title="设计语言" />
            <Anchor.Link href="#物料平台" title="物料平台" />
            <Anchor.Link href="#主题商店" title="主题商店" />
        </Anchor>
    </div>
</template>

动态展示

Anchor 设置 autoCollapse 可以动态展示下一级锚点。默认值为 false。

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Anchor autoCollapse :offsetTop="100" :targetOffset="60">
            <Anchor.Link href="#动态展示" title="1. 动态展示">
                <Anchor.Link href="#组件" title="1.1 组件">
                    <Anchor.Link href="#头像" title="1.1.1 Avatar" />
                    <Anchor.Link href="#按钮" title="1.1.2 Button" />
                    <Anchor.Link href="#图标" title="1.1.3 Icon" />
                </Anchor.Link>
                <Anchor.Link href="#物料" title="1.2 物料" />
                <Anchor.Link href="#主题商店" title="1.3 主题商店" />
            </Anchor.Link>
            <Anchor.Link href="#设计语言" title="2. 设计语言" />
        </Anchor>
    </div>
</template>

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Anchor :autoCollapse="false" :offsetTop="100" :targetOffset="60">
            <Anchor.Link href="#动态展示" title="1. 动态展示">
                <Anchor.Link href="#组件" title="1.1 组件">
                    <Anchor.Link href="#头像" title="1.1.1 Avatar" />
                    <Anchor.Link href="#按钮" title="1.1.2 Button" />
                    <Anchor.Link href="#图标" title="1.1.3 Icon" />
                </Anchor.Link>
                <Anchor.Link href="#物料" title="1.2 物料" />
                <Anchor.Link href="#主题商店" title="1.3 主题商店" />
            </Anchor.Link>
            <Anchor.Link href="#设计语言" title="2. 设计语言" />
        </Anchor>
    </div>
</template>

显示工具提示

Anchor 设置 showTooltip 可以在 Link 超出最大宽度时显示 Link 的文字内容。默认值为 false, 更多使用参考 API 说明。

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Anchor :offsetTop="100" showTooltip :targetOffset="60">
            <Anchor.Link href="#显示工具提示" title="工具提示是一个有用的工具，它可以在文字缩略时展示全部内容。" />
            <Anchor.Link href="#组件" title="组件" />
            <Anchor.Link href="#设计语言" title="设计语言" />
            <Anchor.Link href="#物料平台" title="物料平台" />
            <Anchor.Link href="#主题商店" title="主题商店" />
        </Anchor>
    </div>
</template>

工具提示位置

Anchor 设置 position 可以设置Tooltip的显示位置。它仅在 showTooltip 为 true 时起作用。

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Anchor :offsetTop="100" position="right" showTooltip :targetOffset="60">
            <Anchor.Link href="#工具提示位置" title="工具提示是一个有用的工具，它可以在文字缩略时展示全部内容。" />
            <Anchor.Link href="#组件" title="组件" />
            <Anchor.Link href="#设计语言" title="设计语言" />
            <Anchor.Link href="#物料平台" title="物料平台" />
            <Anchor.Link href="#主题商店" title="主题商店" />
        </Anchor>
    </div>
</template>

自定义滚动位置

通过 scrollIntoViewOptions 可以调整点击锚点后目标元素在容器中的位置，类型为 scroll-into-view-if-needed 的 Options，支持 block、inline、scrollMode、boundary、skipOverflowHiddenElements。不传时 block 为 start，即目标元素滚动到容器顶部。

scrollMotion 决定滚动是否带动画（behavior），targetOffset 在 block 计算出的位置上再向上偏移，两者与 scrollIntoViewOptions 同时传入时依然生效。
只会滚动离目标最近的、可纵向滚动的容器；仅当传入 inline 时才同时调整横向位置。

点击链接后，章节 1 会滚动到容器中间

点击链接后，章节 2 会滚动到容器中间

点击链接后，章节 3 会滚动到容器中间

代码

<script setup lang="ts">
    import { Anchor } from '@fibrous/semi-ui-vue';

    const sections = ['section-a', 'section-b', 'section-c'];
    const getContainer = () => document.getElementById('scroll-box');
</script>

<template>
    <div :style="{ display: 'flex', gap: '24px' }">
        <Anchor :getContainer="getContainer" :scrollIntoViewOptions="{ block: 'center' }" scrollMotion :style="{ width: '160px' }">
            <Anchor.Link v-for="(id, index) in sections" :key="id" :href="`#${id}`" :title="`章节 ${index + 1}`" />
        </Anchor>
        <!-- Focusable so the keyboard can scroll this container -->
        <section id="scroll-box" aria-label="章节" :style="{ height: '240px', width: '320px', overflow: 'auto', border: '1px solid #ddd' }" tabindex="0">
            <div v-for="(id, index) in sections" :id="id" :key="id" :style="{ height: '200px', padding: '8px' }">点击链接后，章节 {{ index + 1 }} 会滚动到容器中间</div>
        </section>
    </div>
</template>

API 参考

Anchor

Props

属性	说明	类型	默认值
autoCollapse	是否在滚动时动态展示下一级锚点。	`boolean`	`semiDefault("Anchor", "autoCollapse", false)`
defaultAnchor	默认高亮的锚点。	`string`	`semiDefault("Anchor", "defaultAnchor", "")`
getContainer	指定滚动的容器，缺省为 window；返回模板 ref 的值时容器出现或替换后自动换绑。	`Type`	`undefined`
maxHeight	组件的 max-height，超出时显示滚动条；style 中的 max-height 优先。	`string \| number`	`semiDefault("Anchor", "maxHeight", strings.MAX_HEIGHT)`
maxWidth	组件的 max-width，超出时显示省略；style 中的 max-width 优先。	`string \| number`	`semiDefault("Anchor", "maxWidth", strings.MAX_WIDTH)`
offsetTop	滚动内容距离容器顶部达到指定偏移量时触发当前链接切换。	`number`	`semiDefault("Anchor", "offsetTop", 0)`
position	showTooltip 开启时 Tooltip 的显示位置，可选值同 Tooltip 的 position。	`Type`	`semiGlobalDefault("Anchor", "position")`
railTheme	滑轨主题，可选 primary、tertiary、muted。	`"muted" \| "primary" \| "tertiary"`	`semiDefault("Anchor", "railTheme", "primary")`
scrollMotion	点击锚点滚动时是否带动画。	`boolean`	`semiDefault("Anchor", "scrollMotion", false)`
scrollIntoViewOptions	点击锚点滚动时传给 scroll-into-view-if-needed 的选项，与 scrollMotion、targetOffset 合并使用。	`Type`	`semiGlobalDefault("Anchor", "scrollIntoViewOptions")`
showTooltip	文字缩略时是否显示 Tooltip 及相关配置：type 为浮层组件，支持 tooltip（默认）和 popover，opts 为传给浮层组件的属性。	`boolean \| ShowTooltip`	`semiDefault("Anchor", "showTooltip", false)`
size	锚点尺寸，可选 small、default。	`"small" \| "default"`	`semiDefault("Anchor", "size", "default")`
targetOffset	锚点滚动结束时，目标距离容器顶部的偏移量。	`number`	`semiDefault("Anchor", "targetOffset", 0)`

Events

事件	说明	回调参数
change	高亮的锚点改变时触发，参数为当前锚点与上一个锚点。	`[currentLink: string, previousLink: string]`
click	点击锚点或在锚点上按 Enter 时触发，参数为原生 MouseEvent 或 KeyboardEvent 与当前锚点；声明为组件事件后，@click 不再作为根元素的原生点击监听。	`[event: AnchorClickEvent, currentLink: string]`

Slots

插槽	说明	作用域参数
default	由 Anchor.Link 组成的子项。	`any`

Exposes

名称	说明	类型
无

class、style 与原生属性经 attrs 落在根元素上；style 中的 max-width、max-height 优先于 maxWidth、maxHeight 属性。click 声明为组件事件后，@click 不再作为根元素的原生点击监听。

Anchor.Link

Props

属性	说明	类型	默认值
disabled	是否禁用，禁用后不响应点击跳转。	`boolean`	`false`
href	跳转的目标，以 # 开头时按元素 id 查找，其余按 CSS 选择器查找。	`string`	`"#"`
title	纯文本标题；未开启 showTooltip 时同时作为原生 title，提供 title 插槽时以插槽为准。	`string`	`undefined`

Events

事件	说明	回调参数
无

Slots

插槽	说明	作用域参数
default	嵌套的下一级 Anchor.Link。	`any`
title	节点形式的标题，优先于 title 属性。	`any`

Exposes

名称	说明	类型
无

class、style 与原生属性经 attrs 落在链接最外层的 div（role="listitem"）上。Anchor.Link 必须放在 Anchor 内，否则抛出错误。

文案规范

按句子大小写书写
保持简洁，避免换行

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$transition_duration-anchor_title-text	var(--semi-transition_duration-none)	锚点标题文字-文字-动画持续时间
$transition_function-anchor_title-text	var(--semi-transition_function-easeIn)	锚点标题文字-文字-过渡曲线
$transition_delay-anchor_title-text	var(--semi-transition_delay-none)	锚点标题文字-文字-延迟时间
$transform_scale-anchor_title-text	var(--semi-transform_scale-none)	锚点-放大
$color-anchor_slide_default-bg-default	var(--semi-color-border)	滑轨背景颜色
$color-anchor_slide_primary-bg-active	var(--semi-color-primary)	选中颜色 - Primary
$color-anchor_slide_tertiary-bg-active	var(--semi-color-tertiary)	选中颜色 - Tietrary
$color-anchor_title-text-default	var(--semi-color-text-2)	文字颜色 - 未选中
$color-anchor_title-text-hover	var(--semi-color-tertiary-hover)	文字颜色 - 未选中悬浮态
$color-anchor_title_active-text-hover	$color-anchor_title-text-hover	文字颜色 - 选中悬浮态
$color-anchor_title-text-active	var(--semi-color-text-0)	文字颜色 - 选中
$color-anchor_title-text-disabled	var(--semi-color-disabled-text)	文字颜色 - 禁用
$color-anchor_title-bg-default	transparent	背景色
$color-anchor_title-bg-active	transparent	背景色 - 选中
$color-anchor_title-outline-focus	$color-focus-ring	轮廓 - 聚焦
$spacing-anchor_slide-left	$spacing-none	滑轨左侧位置
$spacing-anchor_slide-top	$spacing-none	滑轨顶部位置
$spacing-anchor_slide_default-Y	$spacing-extra-tight	选项间距 - 默认
$spacing-anchor_slide_small-Y	$spacing-extra-tight	选项间距 - 紧凑
$spacing-anchor_link_title-paddingTop	$spacing-extra-tight	选项文字顶部内边距
$spacing-anchor_link_title-paddingBottom	$spacing-extra-tight	选项文字底部内边距
$width-anchor_slide_default	2px	滑轨宽度
$height-anchor_slide_default	20px	选项高度 - 默认
$height-anchor_slide_small	16px	选项高度 - 小尺寸
$radius-anchor_slide	1px	滑轨圆角
$width-anchor-outline	$width-focus-ring	anchor轮廓宽度
$width-anchor-outlineOffset	-2px	anchor轮廓 outline-offset 宽度
$width-anchor-outline_border_radius	3px	anchor轮廓圆角

FAQ

为何我的 Link 没有高亮和滑动跟随？
检查下点击锚点是否可以滚动到指定位置：
- 不可以，说明 href 有问题，检查文档中是否存在该 id；
- 可以，可能是滚动容器设置不正确，确保文档内容被包裹在滚动容器内。滚动容器默认为 window，如果你的容器是 .my-container 的 div，则应该将滚动容器设置为该 div。

<script setup lang="ts">
import { Anchor } from '@fibrous/semi-ui-vue';

// 此容器不是 Anchor 组件的容器，是文档内容的容器，因为要根据文档容器去计算当前是哪个 id 在容器上方
const getContainer = () => document.querySelector<HTMLElement>('.my-container');
</script>

<template>
    <Anchor :getContainer="getContainer">
        <!-- Links -->
    </Anchor>
</template>