跳到主要内容
Ed. notes

04 前端:Nuxt + SCSS 的页面实现

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

  • 构建日志
  • Nuxt
  • SCSS
  • 可访问性
  • 前端
第 5 / 12 篇 · 查看全部章节 → 当前:04 前端:Nuxt + SCSS 的页面实现

04 前端:Nuxt + SCSS 的页面实现

一句话结论:页面实现的难点不在把设计稿翻译成组件,而在让内容模型、响应式、主题和可访问性在同一套代码里互不打架;这些约束编译时不会报错,只有真实浏览器和测试能发现。

它解决什么问题

上一篇结束时,内容管线已经能稳定输出 notes、tags 和 series 三份数据:

{
  notes: NoteSummary[]
  tags: TagAggregate[]
  series: SeriesAggregate[]
}

但数据不会自己变成页面。接下来要回答的是一组更具体的问题:

  • 首页、目录、详情都要笔记数据,怎样避免每个页面各请求一次;
  • 标签筛选的状态放在组件里还是 URL 里,刷新和分享时还能不能还原;
  • 1440、1024、768、390 四个宽度下,卡片应该排几列,容器两边留多少;
  • 亮暗主题怎样在首屏前生效,避免先闪一下白底;
  • 详情页正文是 Markdown 渲染出来的 HTML,样式怎么作用到 h2、p、img 这些动态节点;
  • 键盘用户怎样跳过导航,焦点环在亮暗主题下是否都看得见;
  • 笔记不存在、标签没有结果时,页面应该显示什么。

这些问题单独看都不复杂,但它们会互相牵制。比如为了主题不闪烁,把判断塞进内联脚本;为了正文样式能命中动态节点,又要在 CSS Modules 之外开一个全局命名空间。最后能不能成立,不能靠 TypeScript,得靠构建后的真实页面。

我怎么试的

1. 先画页面地图,再决定数据从哪来

阶段 0 只有四个页面:

路径 数据来源 主要职责
/ /api/notes 定位说明,最新 6 篇笔记
/notes /api/notes + ?tag= 卡片目录、标签筛选、系列入口
/notes/[slug] /api/notes/[slug] 笔记详情、正文、外链、404
/about 静态内容 简介、技能、经历、联系方式

首页和目录共用同一个组合式函数:

export const useNotes = () => useFetch<NotesResponse>('/api/notes', { key: 'notes' })

key: 'notes' 让两个页面共享同一份请求结果。用户从首页点进目录时,不会再打一次 /api/notes;服务端渲染时,数据也会跟着 payload 一起送到客户端。

详情页单独请求:

const { data, error } = await useFetch<NoteDetailResponse>(`/api/notes/${encodeURIComponent(slug)}`)

if (error.value || !data.value?.note) {
  throw createError({ statusCode: 404, statusMessage: '笔记不存在' })
}

列表页不需要正文,详情页才需要 HTML。这个边界在内容管线里已经定好,页面层只是照着用。

2. 布局:一个容器,四档边距

所有页面共用 app/layouts/default.vue。它做三件事:放跳转链接、放页头页脚、把主内容区撑满剩余高度。

<a :class="$style['skip-link']" href="#main-content">跳到主要内容</a>
<SiteHeader :current="current" />
<main id="main-content" :class="$style.main" tabindex="-1">
  <slot />
</main>
<SiteFooter />

main 上的 tabindex="-1" 很关键:跳转链接点击后,焦点要真正落到主内容区,而不是只改变滚动位置。主内容区本身不显示焦点环,因为它不是可操作控件。

容器宽度由 AppContainer 统一控制,页面里不直接写 max-width:

.container {
  width: min(calc(100% - #{2 * tokens.$gutter-mobile}), tokens.$container-wide);
  margin-inline: auto;

  @include mixins.media-up(tokens.$breakpoint-tablet) {
    width: min(calc(100% - #{2 * tokens.$gutter-tablet}), tokens.$container-wide);
  }

  @include mixins.media-up(tokens.$breakpoint-desktop) {
    width: min(calc(100% - #{2 * tokens.$gutter-desktop}), tokens.$container-wide);
  }

  @include mixins.media-up(tokens.$breakpoint-wide) {
    width: min(calc(100% - #{2 * tokens.$gutter-wide}), tokens.$container-wide);
  }
}

移动端边距 24px,平板 32px,桌面 48px,宽屏 120px;最大宽度 1200px,正文页收窄到 720px。这样页面只需要决定「用宽容器还是正文容器」,不用每次重算 calc()。

3. 首页:一屏说明,下面是内容

首页由两部分组成:文案区和最新内容。文案区回答「这是谁、为什么来这里」,内容区直接给 6 张卡片。

const notes = computed(() => (data.value?.notes ?? []).slice(0, 6))

卡片网格在三个断点上变化:

.grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: tokens.$space-24;

  @include mixins.media-up(tokens.$breakpoint-tablet) {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }

  @include mixins.media-up(tokens.$breakpoint-wide) {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}

minmax(0, 1fr) 是为了防止长标题把网格撑破。默认的 1fr 最小宽度是 auto,遇到不可换行的内容时列会变宽;显式写 0 才能让卡片老老实实收缩。

首页在 1440 宽度下的浅色主题

首页:上方是定位说明,下方是最新 6 篇内容;1440 宽度下排成三列。

首页没有笔记时显示空状态,而不是留一片空白。空状态和筛选无结果状态共用 EmptyState,文案和操作按钮由页面传入。

4. 目录:筛选状态放进 URL

目录页的筛选没有用组件内部的 ref,而是直接读写 ?tag=:

const activeTag = computed(() => (typeof route.query.tag === 'string' ? route.query.tag : ''))

const filteredNotes = computed(() =>
  activeTag.value ? notes.value.filter((note) => note.tags.includes(activeTag.value)) : notes.value,
)

const setTag = (tag: string) => {
  const query = { ...route.query }
  if (tag) {
    query.tag = tag
  } else {
    delete query.tag
  }
  router.push({ query })
}

这样做的好处是刷新、前进后退、复制链接都能还原筛选结果。筛选按钮用 aria-pressed 表示选中状态,而不是只靠背景色:

<button type="button" :aria-pressed="selected" @click="$emit('toggle')">
  {{ label }}
</button>

标签数量目前不多,筛选在客户端完成;等笔记规模上来,再把筛选和分页移到 API,URL 仍然是同一份状态,不用改交互。

目录页在 1440 宽度下按 MCP 标签筛选

目录页:系列入口在上方,标签筛选在中间,下面是筛选后的卡片。

5. 详情:正文样式要单独开一个命名空间

详情页把 Markdown 渲染好的 HTML 直接交给 v-html:

<div :class="[$style.prose, 'article-prose']" v-html="note.html" />

这里同时挂了两个类:$style.prose 是 CSS Modules 生成的哈希类,负责正文的基础颜色和字号;article-prose 是一个稳定的全局类,专门给 v-html 生成的子节点用。

原因是 CSS Modules 只处理模板里写死的类名,v-html 插入的 h2、p、img 不会被加上哈希。第一版我用了 .prose :deep(h2),看起来像 Vue 的标准写法,但 :deep() 只在 <style scoped> 里生效;写在 <style module> 里,构建后的 CSS 会原样保留 :deep(img):

._prose_z8oe2_63 :deep(img) {
  max-width: 100%;
}

浏览器不认识 :deep(),整条规则被丢弃。页面在桌面上看起来还算正常,因为浏览器给 h2、p 的默认样式能兜底;到了 390 宽度的详情页,问题就暴露了:

390 /notes/magpie {"scrollWidth":625,"innerWidth":390}

正文里那张 601px 宽的截图没有 max-width 约束,直接把页面撑出了横向滚动。改成独立的全局样式块后:

.article-prose img {
  display: block;
  max-width: 100%;
  height: auto;
  margin: tokens.$space-24 0;
  border: tokens.$border-1 solid var(--color-border);
  border-radius: tokens.$radius-8;
}

同一组宽度再测:

390 /notes/magpie ok
390 /notes ok
390 /about ok

这类问题不会在 typecheck 或构建时报错,只有测量 scrollWidth、或者真的在手机宽度下滚一遍,才会发现。

笔记详情页在 1440 宽度下的暗色主题

详情页:标题、摘要、标签、正文和「继续探索」外链。正文图片现在会被容器宽度约束。

6. 关于页:语义结构比视觉更重要

关于页没有复杂交互,但它是全站语义结构的样板:

<section :class="$style.section" aria-labelledby="intro">
  <h2 id="intro">简介</h2>
  ...
</section>

每个区块都有 aria-labelledby,技能列表用 aria-label 区分「前端」「AI 工程」「工程与部署」。这些属性不影响视觉效果,但屏幕阅读器能把页面读成有层次的区块,而不是一串连续的文本。

7. 主题:内联脚本负责首屏,组件负责切换

颜色 token 和尺寸 token 是分开的:字号、间距、圆角、断点用 SCSS 变量,编译后固定;亮暗主题的颜色用 CSS 自定义属性,运行时切换。

首屏前,nuxt.config.ts 里的内联脚本会先读 localStorage 和系统偏好,把结果写到 <html data-theme>:

const preference =
  stored === 'light' || stored === 'dark' || stored === 'system' ? stored : 'system'
const dark =
  preference === 'dark' ||
  (preference === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches)
document.documentElement.dataset.theme = dark ? 'dark' : 'light'

这段脚本必须在样式之前执行,否则用户会先看到一帧亮色,再跳到暗色。useTheme 在客户端挂载后再接管状态,负责切换和持久化。

主题按钮的第一版用动态 aria-label:

<BaseButton :aria-label="resolved === 'dark' ? '切换到浅色' : '切换到暗色'">
  {{ resolved === 'dark' ? '浅色' : '暗色' }}
</BaseButton>

浅色主题下 e2e 测试是通过的。但 axe 在暗色主题下报了一个 serious 级别的问题:

label-content-name-mismatch
nodes: ["button"]

原因是 SSR 输出的是浅色状态,按钮的可访问名称是「切换到暗色」;客户端初始化成暗色后,可见文案变成了「浅色」,aria-label 却没有同步更新。可访问名称和可见文案对不上,屏幕阅读器用户听到的按钮含义就会和视觉用户看到的不一致。

最后的做法是把两个文案都放进 DOM,用 CSS 控制显示:

<span :class="$style['sr-only']">切换到</span>
<span :class="[$style.label, $style['label-light']]">暗色</span>
<span :class="[$style.label, $style['label-dark']]">浅色</span>
.label-dark {
  display: none;
}

:global([data-theme='dark']) .label-light {
  display: none;
}

:global([data-theme='dark']) .label-dark {
  display: inline;
}

这样可访问名称始终来自当前可见的文案,不再依赖属性同步。亮暗两套主题都要跑 axe,只测浅色会漏掉这类问题。

8. 四档宽度和测试

布局验证不是只看截图,还要量横向溢出和列数:

1440 /       {"scrollWidth":1440,"innerWidth":1440,"gridColumns":3}
1024 /       {"scrollWidth":1024,"innerWidth":1024,"gridColumns":2}
768  /       {"scrollWidth":768,"innerWidth":768,"gridColumns":2}
390  /       {"scrollWidth":390,"innerWidth":390,"gridColumns":1}

首页、目录、详情、关于四个页面在四个宽度下都满足 scrollWidth === innerWidth。断点没有按设备型号硬编码,而是按内容宽度:768 开始两列,1440 才三列,1024 仍然两列,避免卡片被压得太窄。

目录页在 768 宽度下保持两列

768 宽度:导航仍然在一行,标签自动换行,卡片保持两列。

详情页在 390 宽度下的暗色主题

390 宽度:标题、正文和图片都在单列内,图片不再撑破容器。

测试分三层:

$ npm test
 Test Files  4 passed (4)
      Tests  89 passed (89)

$ PLAYWRIGHT_CHANNEL=chrome npx playwright test e2e/site.spec.ts e2e/a11y.spec.ts
 18 passed (18.7s)

单元测试覆盖内容管线;Playwright 端到端测试覆盖首页、标签筛选、详情、/series 总览和 404;axe 在亮暗两套主题下扫首页、目录、详情、系列总览和关于页。test:e2e 会先 npm run build,再启动 .output/server/index.mjs,所以测的是生产构建,不是开发服务器。

坑和限制

1. :deep() 写在 style module 里不会生效。 这是这次最隐蔽的问题。它不报错、不警告,构建后的 CSS 里留着一个浏览器不认识的伪类,整条规则被静默丢弃。CSS Modules 加 v-html 的组合,要么用独立的全局命名空间,要么显式使用 :global();不能想当然地把 scoped 的写法搬过来。

2. SSR 和客户端状态不一致,会先体现在可访问名称上。 主题、登录态、语言偏好这类「服务端不知道、客户端首屏才知道」的状态,最容易出现文案和属性不同步。视觉上可能完全正常,axe 和屏幕阅读器才会报错。亮暗主题、刷新、首次访问三种路径都要测。

3. v-html 的安全边界必须写死在渲染层。 详情页用的是 markdown-it,配置为 html: false,正文里的原始 HTML 不会执行。这个开关不能为了嵌入一个 iframe 就打开;需要嵌入式内容时,应该加受控的 shortcode 或组件白名单。

4. 卡片高度是统一的,不是瀑布流。 min-height: 336px 让一屏里的卡片有稳定的节奏,但摘要短的卡片会留白。内容密度优先还是视觉整齐优先,是一个产品选择;现在选的是后者。

5. 标签筛选还在客户端。 110 个测试、18 篇已发布内容时完全够用;内容到几百篇后,首屏传输和筛选计算都会变成负担。那时需要把 ?tag= 传到 API,并补分页,而不是继续在浏览器里过滤全量数据。

6. 主题只有亮/暗两个切换结果。 默认跟随系统,但用户点过按钮后,偏好就固定成 light 或 dark,没有「回到系统」的入口。要支持三态,需要在界面上再加一个选项,而不是只改 useTheme。

7. axe 只筛了 serious 和 critical。 这能挡住最严重的问题,但 moderate、minor 仍然可能存在;键盘走查、缩放、屏幕阅读器的人工检查不能省。

8. 端到端测试依赖浏览器。 本地没有安装 Playwright 浏览器时,可以用 PLAYWRIGHT_CHANNEL=chrome 复用系统 Chrome;CI 里仍然需要 npx playwright install,否则测试会在启动浏览器这一步失败。

适合谁

如果你用 Nuxt 或 Vue 做内容站,这套页面层可以直接借鉴:一个共享的 useNotes、一个统一容器、URL 驱动的筛选、一个给 v-html 用的正文命名空间,再加上亮暗主题和 axe 测试,足以支撑一个规模不大的个人站。

如果你正在从「能跑」走向「能维护」,这里更值得拿走的是两个检查习惯:在真实宽度下量 scrollWidth,以及在两套主题下跑可访问性测试。它们比多看几遍代码更容易发现样式层的问题。

它不太适合这几类场景:需要可视化编辑的 CMS 站点;想要开箱即用博客主题的人;以及内容规模已经需要搜索、权限和审核流的团队。

下一篇是 05 部署(一):镜像与多阶段构建。先把 Nuxt 产物装进一个可复现的镜像,再谈发布、回滚和生产验证。

继续探索