Table of Contents
通过锚点链接浏览文章章节,目录指示器随阅读位置更新。
适用场景
- 用于较长的指南、参考文档或文章,让读者快速跳转章节并确认阅读位置。
安装
选择安装方式,用法示例将同步更新导入路径。
$ bunx --bun shadcn-vue@2.8.2 add https://orvui.efu.me/r/table-of-contents.json
首次使用时,将安装的 src/components/orvui/styles.css 导入项目样式入口。
示例
预览
Overview
Follow this article using the links alongside it. The active section updates as you scroll.
Installation
Follow this article using the links alongside it. The active section updates as you scroll.
Usage
Follow this article using the links alongside it. The active section updates as you scroll.
Accessibility
Follow this article using the links alongside it. The active section updates as you scroll.
packages/vue/src/motion/table-of-contents/demo.vue
<script setup lang="ts">
import { ref, useId } from "vue";
import { TableOfContents } from "@/components/orvui/motion/table-of-contents";
const target = ref<HTMLElement | null>(null);
const instance = useId();
const items = ["Overview", "Installation", "Usage", "Accessibility"].map(
(label, i) => ({ id: `${instance}-section-${i}`, label }),
);
</script>
<template>
<div class="grid w-full max-w-2xl grid-cols-[minmax(0,1fr)_9rem] gap-5 p-4">
<div
ref="target"
class="h-72 overflow-y-auto rounded-xl border border-border bg-background px-5"
tabindex="0"
aria-label="Example article"
>
<section
v-for="item in items"
:id="item.id"
:key="item.id"
class="min-h-52 py-6"
>
<h3 class="text-base font-medium">{{ item.label }}</h3>
<p class="mt-3 text-sm leading-6 text-muted-foreground">
Follow this article using the links alongside it. The active section
updates as you scroll.
</p>
</section>
</div>
<TableOfContents
:items="items"
:target="target ?? undefined"
:offset="16"
/>
</div>
</template>
packages/vue/src/motion/table-of-contents/src/TableOfContents.vue
状态与事件
需要由表单、路由或父组件管理时,绑定下列状态并接收对应更新。v-model 是属性与 update 事件的简写;值的类型应与 API 一致。
| 组件 | Vue 绑定 | 更新事件 |
|---|---|---|
TableOfContents | v-modelstring | update:modelValue |
可选受控属性未传入时,按组件文档的默认行为工作;不要用固定的 false 或空值代替未传入。异步请求和持久化在应用中处理,再把结果传回组件。
API 参考
itemsTableOfContentsItem[]—target?string | HTMLElement | ComponentPublicInstance | Ref<HTMLElement | ComponentPublicInstance | null | undefined, HTMLElement | ComponentPublicInstance | null | undefined> | () => HTMLElement | null—offset?number88modelValue?stringlocal.valuetitle?string"On this page"事件
update:modelValue[id: string]@update:modelValue插槽
title() => unknown#titleitem(props: { item: TableOfContentsItem; active: boolean; }) => unknown作用域参数: item, active
#item无障碍
为交互控件提供明确的无障碍名称。保留文档中的键盘路径、可见焦点与减少动态效果状态;自定义插槽应继续保留所替代部件的语义。
常见问题
- 如何配置 Table of Contents?
- 传入包含稳定章节 ID 的 items,以及正文元素或选择器 target。通过 modelValue 与 update:modelValue 读取阅读位置;offset 默认 88px。
- 如何连接到应用状态?
- 监听 update:modelValue,将组件连接到应用状态。
- 可以在服务端渲染吗?
- 可以在 Vue SSR 应用中正常渲染。服务端与客户端的初始 props 应保持一致;浏览器测量与交互资源在挂载后启动。
更新于
来源与许可 ↗MIT · 0.1.1