跳到主要内容
Ed. notes

06 页面与组件:首页、目录、详情与系列

长文 · 2026-11-12 · 合集第 7 / 10 篇

  • Nuxt
  • Vue
  • 页面
  • 构建日志
第 7 / 10 篇 · 查看全部章节 → 当前: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
  1. 首页显示最新六篇,点卡片能进入详情;
  2. /notes 显示全部已发布内容,点击标签后 URL 出现 ?tag=...;
  3. 刷新后筛选仍然存在,浏览器后退能回到「全部」;
  4. /series 总览列出六个系列,点击 01-从0建小站 进入该系列 00-目录.md 的详情页;
  5. 访问不存在的 slug 返回 404 页面;
  6. 用 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 自定义属性,主题又怎样在首屏前完成切换。