AstroPaper博客美化与功能定制记录

本文属于「个人博客搭建记录」系列：

从 Obsidian 到 Cloudflare：Astro 博客建站与自动部署记录

为 Astro 博客接入 Waline 评论系统

AstroPaper 博客美化与功能定制记录

1 定制目标

AstroPaper 默认主题简洁、阅读体验良好，但视觉风格比较克制。我希望在保留文章可读性的基础上，增加更有个人特色的展示效果。

最终完成的主要功能包括：

首页全屏随机壁纸。
内页横幅壁纸。
博客名称和自定义语录。
固定在顶部并支持自动隐藏的导航栏。
可调节的主题色相。
左下角 QQ 音乐播放器。
可展开和收起的歌词区域。
页脚技术栈标签。
Markdown 图片图注自动编号。
手机端响应式适配。

部分交互和视觉效果参考了 Firefly Astro 主题，但实际功能基于现有 AstroPaper 项目单独实现。

2 首页全屏壁纸

首页使用完整视口展示随机壁纸，并在中央显示博客名称和语录：

不吃鱼的小天地
去码头整点薯条~

全屏壁纸区域使用接近 100vh 的高度。页面下方仍保留文章首页正文，用户可以点击向下箭头进入正文，也可以继续滚动返回壁纸区域。

基本结构：

<section class="wallpaper-hero">
  <div class="wallpaper-hero__content">
    <h1>不吃鱼的小天地</h1>
    <p>去码头整点薯条~</p>
  </div>

  <a href="#page-content" aria-label="进入正文">⌄</a>
</section>

<main id="page-content">
  <!-- 首页正文 -->
</main>

壁纸使用随机图片 API。为减轻首次加载时的明显闪烁，可以采用以下优化：

页面先显示与壁纸接近的纯色或渐变背景。
图片加载完成后再执行淡入。
使用 background-size: cover 填满区域。
对随机图片 API 设置合理缓存。
避免在一次页面加载中重复请求不同随机图。

3 内页横幅壁纸

文章、标签和关于页面不适合占用完整屏幕，因此使用较矮的横幅区域展示壁纸和当前页面标题。

例如：

文章
标签
关于我

横幅与正文之间使用柔和的渐变或波浪形过渡，避免壁纸与白色正文区域形成突兀边框。

首页使用全屏壁纸，内页使用横幅壁纸，两者共享相同的随机壁纸来源和主题色变量。

4 顶部导航栏自动隐藏

导航栏在所有壁纸模式和页面中固定显示于顶部，方便随时访问：

文章｜标签｜关于｜归档｜搜索｜主题切换

为了让壁纸有更大的展示空间，导航栏支持自动隐藏：

页面首次加载时显示。
一段时间没有操作后隐藏。
鼠标靠近页面顶部时重新显示。
向上滚动时显示。
向下滚动时隐藏。
键盘聚焦导航栏时保持显示。

移动端没有鼠标悬停，因此必须保留触摸友好的显示方式，例如滚动向上时重新显示。

导航栏使用半透明背景和模糊效果，让它在不同壁纸上保持可读，同时不过度遮挡图片：

backdrop-filter: blur(16px);
background: color-mix(in srgb, var(--card-bg) 78%, transparent);

5 自定义主题色相

博客提供主题色相滑动设置，允许用户根据壁纸调整界面强调色。

核心思路是将色相保存为 CSS 变量：

:root {
  --theme-hue: 202;
  --accent-color: hsl(var(--theme-hue) 85% 48%);
}

滑块变化时更新变量，并将用户选择写入 localStorage：

localStorage.setItem("theme-hue", String(hue));
document.documentElement.style.setProperty("--theme-hue", String(hue));

下次访问时读取保存值，避免每次刷新后恢复默认颜色。

6 QQ 音乐播放器

页面左下角加入了可展开和收起的音乐播放器。播放器通过 QQ 音乐资源信息加载歌曲，并支持以下类型：

song      单曲
playlist  歌单
album     专辑
artist    艺术家

示例单曲：

类型：song
歌曲：Pirre
QQ 音乐歌曲 ID：003BlDgH3Gi3Tw

播放器展示：

封面。
歌曲名称。
艺术家。
播放进度。
音量。
上一首、播放、下一首。
播放列表入口。
歌词展开按钮。

播放器默认收起为左下角的音乐按钮，点击后展开完整面板。这样既能保留功能，也不会长期遮挡文章内容。

6.1 歌词展开与收起

歌词区域由独立按钮控制：

点击一次展开歌词。
再次点击收起。
没有歌词时显示“暂无歌词”。
歌词区域设置最大高度，并允许内部滚动。

在手机端，播放器宽度应根据视口计算，并为正文保留足够空间：

width: min(24rem, calc(100vw - 2rem));

浏览器通常禁止网页自动播放带声音的媒体，因此音乐只能在用户主动点击播放后开始。

7 页脚技术栈标签

页脚用于简要说明博客所使用的工具和平台：

Markdown 编辑器：Obsidian
博客框架：Astro
参考主题：AstroPaper
代码托管：GitHub
网站托管：Cloudflare Pages

标签采用紧凑的彩色徽章样式，在桌面端和手机端自动换行。技术栈信息始终展示，不与音乐播放器的展开和隐藏状态绑定。

8 Markdown 图片图注自动编号

在 Obsidian 中为图片手动编写 <figure> 标签并不方便，逐张维护“图 1”“图 2”编号也容易出错。

因此博客增加了自动图注转换规则。写作时只需要在图片下方添加斜体说明：

![胶质细胞示意图](https://example.com/image.png)

*不同类型胶质细胞的结构与功能*

博客构建时会自动转换为：

<figure>
  <img src="https://example.com/image.png" alt="胶质细胞示意图">
  <figcaption>图 1：不同类型胶质细胞的结构与功能</figcaption>
</figure>

同一篇文章中的图片按照出现顺序自动编号，不需要在 Obsidian 中手动维护数字。

如果图片下方没有斜体说明，则保持为普通图片，不生成图注。

这种写法在 Obsidian 中仍然容易阅读，也不会依赖复杂 HTML：

![图片说明](图片 URL)

*图注文字*

9 手机端适配

新增视觉功能后，移动端适配比桌面端更容易出现问题。需要重点检查：

导航栏是否可以正常显示和恢复。
全屏壁纸文字是否超出屏幕。
内页横幅高度是否适中。
设置面板是否超出视口。
音乐播放器是否遮挡正文。
歌词区域是否可以正常滚动。
页脚徽章是否自动换行。
Waline 评论区是否产生横向滚动条。

响应式设计中，应优先使用：

min()
max()
clamp()
calc()

而不是为每种设备写死宽度和高度。

10 性能与可用性注意事项

视觉效果不能以明显影响阅读体验为代价。定制过程中需要注意：

10.1 随机壁纸

图片 API 不稳定时应保留默认背景。
图片加载前避免页面出现纯白闪烁。
不要频繁更换壁纸导致重复下载。

10.2 动画

自动隐藏导航栏和面板动画应简短。
尊重 prefers-reduced-motion，为减少动画的用户关闭非必要过渡。

10.3 可访问性

图标按钮必须提供 aria-label。
键盘可以访问导航栏和播放器。
浅色与深色模式下文字均需保持足够对比度。
壁纸上的标题增加阴影或遮罩，避免因图片过亮而无法阅读。

11 配置与内容分离

适合经常修改的信息应集中放入配置文件，而不是散落在组件中，例如：

export const siteConfig = {
  title: "不吃鱼的小天地",
  quote: "去码头整点薯条~",
};

音乐配置也应独立管理：

export const musicConfig = {
  source: "qq",
  type: "song",
  id: "003BlDgH3Gi3Tw",
};

这样更换语录、歌曲或随机壁纸 API 时，不需要修改播放器和页面组件内部逻辑。

12 最终效果与经验

这次美化并不是完全替换 AstroPaper，而是在其清晰排版和文章结构基础上增加个性化功能。

最终保留了 AstroPaper 适合阅读的正文样式，同时通过随机壁纸、主题色和音乐播放器增强了博客辨识度。所有功能都需要遵循一个原则：装饰可以吸引注意，但不能阻碍导航、阅读和移动端使用。

13 相关阅读

上一篇：从 Obsidian 到 Cloudflare：Astro 博客建站与自动部署记录
上一篇：为 Astro 博客接入 Waline 评论系统
AstroPaper
Firefly
Astro 官方文档