06 页面与组件:首页、目录、详情与系列
结论
页面层只做三件事:拿数据、组织布局、渲染组件。它不读文件系统,也不解析 frontmatter。
app/app.vue
→ app/layouts/default.vue 跳转链接、页头、主内容区、页脚
→ app/pages/index.vue 首页
→ app/pages/notes/index.vue 目录与标签筛选
→ app/pages/notes/[slug].vue 详情(三栏阅读布局)
→ app/pages/series/index.vue 系列总览
→ app/pages/about.vue 关于
首页、目录页和系列总览共用同一份 /api/notes 数据。详情页额外请求单篇 HTML、标题锚点和同系列章节列表;系列总览不另开接口,而是从列表响应里的 series 字段取分组。每个系列的入口指向该系列第一篇,也就是 00-目录.md 的详情页。
站点的结构是「系列优先」:读者先从系列进入,再顺着章节往下读;笔记目录仍然保留,但不再是唯一入口。
问题与设计
布局只负责骨架
default.vue 是全局骨架,按可访问性基线组织:
- 第一个可聚焦元素是「跳到主要内容」,指向
#main-content; - 页头是
header,主导航有aria-label="主导航"; - 主内容区是
<main id="main-content" tabindex="-1">; - 页脚在布局里,不跟每个页面重复;
- 可选的 AI 浮窗挂在布局末尾,但默认关闭,不属于博客主线。
页面只负责 <main> 里的内容。这样首页、目录、详情和关于页不需要各自处理跳转链接、页头或页脚。
列表数据只请求一次
useNotes() 是对 useFetch('/api/notes') 的薄封装,并固定了 key: 'notes':
export const useNotes = () => useFetch<NotesResponse>('/api/notes', { key: 'notes' })
同一个渲染过程中,多个组件使用相同的 key 会复用同一份数据。首页、目录页和系列总览都基于这份响应,不需要各自定义接口形状。
目录筛选放在 URL 里
标签筛选没有引入状态管理库,而是把当前标签放在查询参数里:
/notes?tag=Nuxt
页面从 route.query.tag 读当前值,点击标签时用 router.push({ query }) 更新。这样做有三个直接好处:
- 刷新页面不丢筛选;
- 链接可以分享;
- 浏览器前进/后退符合直觉。
筛选本身在客户端对已加载的列表做 filter。当前内容量下没有必要再发一次请求。
详情页在服务端拿 HTML
详情页请求 /api/notes/[slug],拿到的 html 已经渲染好。页面用 v-html 插入正文,并用一个全局的 article-prose 命名空间处理正文排版。
这里必须区分两类安全边界:
- 博客正文来自仓库内 Markdown,且
markdown-it关闭了原始 HTML; - AI 回答是模型输出,走另一套纯文本渲染,不能直接复用
v-html。
系列总览复用列表响应
系列总览不需要单独接口。它直接遍历 /api/notes 的 series 数组,每个系列一张卡片,卡片标题是文件夹原名,入口是该系列第一篇:
const firstChapterPath = (series: SeriesAggregate) =>
series.notes[0] ? `/notes/${series.notes[0].slug}` : ''
系列不再是独立资源,而是「文件夹聚合」:文件夹名就是系列名,00-目录.md 是系列第一篇,和其余文章一样有 slug、详情页和正文。
关键代码
首页:最新六篇
const { data } = await useNotes()
const notes = computed(() => (data.value?.notes ?? []).slice(0, 6))
模板用 NoteCard 渲染卡片,并在没有内容时显示 EmptyState。首页只取前六篇,完整列表留给 /notes。
目录页:标签与筛选
const { data } = await useNotes()
const activeTag = computed(() => (typeof route.query.tag === 'string' ? route.query.tag : ''))
const filteredNotes = computed(() =>
activeTag.value
? (data.value?.notes ?? []).filter((note) => note.tags.includes(activeTag.value))
: (data.value?.notes ?? []),
)
const setTag = (tag: string) => {
const query = { ...route.query }
if (tag) {
query.tag = tag
} else {
delete query.tag
}
router.push({ query })
}
模板里「全部」按钮和每个标签都使用 TopicFilter。它渲染成真正的 button,用 aria-pressed 表达选中状态:
<button type="button" :aria-pressed="selected" @click="$emit('toggle')">
{{ label }}
</button>
这比用 div 加 class 更可靠:键盘可以聚焦,屏幕阅读器能读出按下状态。
卡片:整张卡片是一个链接
<NuxtLink :to="to" :class="$style.card">
<div :class="$style.content">
<p :class="$style.meta">{{ meta }}</p>
<h3 :class="$style.title">{{ title }}</h3>
<p :class="$style.summary">{{ summary }}</p>
<ul v-if="tags?.length" :class="$style.tags" aria-label="标签">
<li v-for="tag in tags" :key="tag">
<BaseTag :label="tag" />
</li>
</ul>
</div>
</NuxtLink>
卡片标题用 h3,因为页面上已经有 h1 和 h2。整个卡片可点击,同时保留键盘焦点和 :focus-visible 焦点环。
详情页:404 与正文
const route = useRoute()
const slug = String(route.params.slug)
const { data, error } = await useFetch<NoteDetailResponse>(`/api/notes/${encodeURIComponent(slug)}`)
const note = data.value?.note
if (error.value || !note) {
throw createError({ statusCode: 404, statusMessage: '笔记不存在' })
}
正文容器是:
<!-- eslint-disable-next-line vue/no-v-html -- 内容来自仓库内 Markdown,markdown-it 已禁用原始 HTML -->
<div :class="[$style.prose, 'article-prose']" v-html="note.html" />
正文排版单独放在一个全局样式块里,以 article-prose 为命名空间。原因是 v-html 生成的节点拿不到 CSS Modules 的哈希类名,直接用模块类名不会生效。
详情页的三栏阅读布局
详情页在 1280px 以上是三栏:左侧系列导航、中间正文、右侧本文目录。宽度来自 tokens,不在组件里写死:
.reading-layout {
display: grid;
gap: tokens.$space-32;
@include mixins.media-up(tokens.$breakpoint-reading) {
grid-template-columns:
tokens.$reading-sidebar-width
minmax(0, tokens.$reading-content-width)
tokens.$reading-toc-width;
gap: tokens.$reading-gap;
align-items: start;
}
}
三栏的数据都来自详情接口:左侧是 chapters(同系列完整章节列表,当前篇高亮),右侧是 headings(正文标题锚点),文末的下篇卡用 next。窄屏时本文目录隐藏,系列导航折叠成一个「查看全部章节」的入口块。
系列总览:文件夹就是系列
没有 /series/[name] 详情页。系列总览只负责分组和导航:每个系列显示文件夹原名、篇数和前几篇章节目录;点击「阅读」跳到第一篇,也就是 00-目录.md。
系列内文章由内容层按阅读序号正序排好,00 因此自然排在最前,页面直接遍历 series.notes,不再排序。要写系列说明,就写 00-目录.md 的正文;旧的 series.meta.audience、series.meta.outcomes 已经删除,不再有独立的系列元数据。
布局里的当前导航
const current = computed<'home' | 'series' | 'notes' | 'about' | 'chat' | undefined>(() => {
if (route.path === '/') return 'home'
if (route.path.startsWith('/series')) return 'series'
if (route.path.startsWith('/notes')) return 'notes'
if (route.path.startsWith('/about')) return 'about'
if (route.path.startsWith('/chat')) return 'chat'
return undefined
})
SiteHeader 用这个值设置 aria-current="page"。导航项是链接而不是按钮,视觉上像按钮,语义上仍然是导航。
验证
启动开发服务器后,按交互逐项检查:
cd frontend
npm run dev
- 首页显示最新六篇,点卡片能进入详情;
/notes显示全部已发布内容,点击标签后 URL 出现?tag=...;- 刷新后筛选仍然存在,浏览器后退能回到「全部」;
/series总览列出六个系列,点击01-从0建小站进入该系列00-目录.md的详情页;- 访问不存在的 slug 返回 404 页面;
- 用 Tab 键从页面顶部开始移动,第一个焦点应是「跳到主要内容」。
组件和内容的单元测试:
npm run test
浏览器端到端用例在 frontend/e2e/,需要先构建;对应命令是 npm run test:e2e 和 npm run test:a11y。
边界
- 标签筛选在客户端完成,不分页、不搜索;内容量变大后需要改为服务端筛选或虚拟列表。
- 详情页的
v-html只适用于仓库内受控 Markdown,不能把用户输入或模型输出直接传进去。 - 系列总览依赖
/api/notes的完整响应;如果以后把列表接口分页,分组也要跟着调整。 - 布局末尾挂了可选的
ChatAssistantFeature,但 AI 默认关闭,博客页面不依赖它。 - 页面的视觉细节和设计 token 在下一篇;更完整的响应式与无障碍取舍在 构建实践。
下一篇看样式:tokens 怎样分成 SCSS 变量和 CSS 自定义属性,主题又怎样在首屏前完成切换。