从 Wagtail 迁移到 Astro（六）：主题与功能打磨

作者: Alex Xiang

博客

本文是「Wagtail 迁移 Astro」系列的第六篇，介绍迁移完成后对站点做的主题与功能打磨：深色模式、站内搜索、面包屑、文字对比度与无障碍、以及页脚备案信息等。

一、深色模式

1.1 实现思路

使用 CSS 变量 区分浅色/深色：在 :root 和 html.dark 下分别定义背景色、文字色、边框色、卡片色等。
在 Header 放一个主题切换按钮，点击时给 <html> 加上或去掉 dark 类。
持久化：用 localStorage 保存用户选择（如 zicode-theme: dark | light），页面加载时先读再设类；若未选过，可跟随系统 prefers-color-scheme: dark。

1.2 注意点

所有用到颜色的地方尽量走 CSS 变量，避免硬编码色值，这样切主题时只需改变量。
图片、边框、阴影在深色下可适当调整，保证对比度与可读性。

示例变量（仅作参考）：

:root {
  --bg: #ffffff;
  --text: #0f172a;
  --muted: #64748b;
}
html.dark {
  --bg: #0f172a;
  --text: #f1f5f9;
  --muted: #94a3b8;
}

切换时执行 document.documentElement.classList.toggle('dark', isDark)，并把 isDark 写入 localStorage，下次加载时先读再应用。

二、站内搜索

2.1 静态搜索

构建时生成 搜索索引：把每篇文章的 title、description、slug、category、tags 等输出为 JSON（如 /search-index.json），由 Astro 的 endpoint 或静态 JSON 页面提供。
前端在 Header 放搜索入口（图标或快捷键 Ctrl/Cmd+K），打开弹层后请求该 JSON，根据用户输入在内存中过滤，展示标题与链接。

2.2 体验

输入防抖、结果高亮、键盘导航与 Esc 关闭，可按需加上。
不依赖第三方服务，适合纯静态站点。

索引生成可在 Astro 的 src/pages/search-index.json.ts 中实现：在 getStaticPaths 或单次构建时调用 getCollection('blog')，把每篇的 title、description、slug、tags 等序列化为 JSON 并输出到该路由，前端 fetch 该 URL 即可。

三、面包屑与导航

面包屑：在每页主内容上方展示「首页 > 文章 > 分类/专栏/当前文章」，用组件接收 items: { label, href? }[]，当前页无 href。
顶部导航：保留首页、分类、专栏、文章、关于等入口，与 Wagtail 时期的信息架构一致，便于老读者习惯。

四、对比度与无障碍

文字与背景：正文、标题、次要文字使用对比度足够的颜色（如 #0f172a、#475569 在浅色底上，#f1f5f9、#94a3b8 在深色底上），避免「灰底灰字」。
链接与按钮：默认、hover、focus 状态区分明显，焦点环不取消。
图片：头图、正文图尽量带 alt；装饰性图片可用 alt=""。
深色模式下，卡片、导航、页脚、标签 pill 等统一用同一套变量，保证全站一致可读。

五、备案与页脚

在 Footer 中展示 ICP 备案号，并链接到工信部查询页（如 https://beian.miit.gov.cn/），符合国内建站要求。
版权与站点说明保留在 Footer，风格与整体设计统一。

六、系列小结

本系列六篇文章覆盖了从 为何迁移、选型，到 迁移阶段、添加新文章、上线，再到 数据同步与脚本化 以及 主题与功能打磨，可作为「Wagtail → Astro」迁移的完整参考。若你也在考虑从传统 CMS 迁到静态站点，欢迎按需裁剪与扩展上述步骤。

建议顺序：先完成内容迁移与上线（一～四），再补同步脚本（五）和主题功能（六），这样即使同步脚本尚未就绪，也能先用手动导入的内容对外服务，再逐步自动化。

本系列文章：（一）为什么迁移与选型 · （二）迁移的几个阶段 · （三）添加新文章 · （四）上线 · （五）数据同步与脚本化 · （六）主题与功能打磨（本文）