02-组件说明

本文覆盖 src/components/ 下全部 21 个 Astro 组件（src/components/ 13 个通用组件 + src/components/views/ 8 个页面级组件）与 1 个布局。

组件分层约定
项目把组件分成两层，理解这一点能省很多力气：

• 页面级组件 src/components/views/*.astro：承载某个页面的完整内容（标题区、列表、空状态），只接收数据 props；
• 路由文件： src/pages/*.astro：只做「取数据 → 传给页面组件 → 包一层 BaseLayout」的薄封装。

所以「改页面长相」去 components/views/，「改 URL 或取数逻辑」去 src/pages/。

1. 组件总览

所有组件的 lang 都默认为 defaultLang（即 siteConfig.defaultLang）。当前项目所有路由都传 defaultLang，因为只构建默认语言页面（详见 07-页面与路由.md#5）。

PostPage 的三个补充说明

1. CSS 按需注入：katex/dist/katex.min.css 只有在正文出现 .katex 时才注入，photoswipe/style.css 只有在正文有图片、真要初始化灯箱时才注入。两者都用 ?inline 取 CSS 文本后写入 <style data-…-css>，因为 astro.config.mjs 的 build.inlineStylesheets: 'always' 会把动态 import 出来的 CSS 资源内联进每个文章页 HTML 并删掉资源文件（无公式 / 无图片的页面也会被内联，且公式页会多出一个 404 请求）。

2. 系列目录当前项：浅色模式为 bg-accent/10 text-ink + 左侧 border-l-2 border-accent 竖条（实测对比度 11.97:1）；暗色模式维持原样 dark:text-accent 且不描边（4.91:1）。早先的 text-accent 浅色下仅 4.48:1，不达 WCAG AA 4.5:1。

3. 拆分：系列目录与上下篇导航分别抽成 SeriesToc.astro / PostNav.astro；客户端逻辑抽到 lib/photoswipe.ts（灯箱）、lib/postActions.ts（复制按钮 + 锚点滚动）、lib/postContent.ts（图片框载入态 + 滚动淡入）、lib/postToc.ts（目录定位 / 折叠 / 当前项跟踪），PostPage.astro 只保留数据计算、视图组合与 onPageLoad 编排。

2. 基础原子组件

2.1 Icon.astro

<Icon d={mdiCalendarOutline} class="text-sm" />

输出结构：

<svg class="mdi-icon text-sm" width="1em" height="1em" viewBox="0 0 24 24"
     fill="currentColor" aria-hidden="true"><path d="…"></path></svg>

要点：

• 尺寸用 1em，所以通过字体大小 class 控制图标大小（text-sm / text-lg / text-[11px]）；
• 颜色继承 currentColor，跟随文字色；
• 固定 aria-hidden="true"，装饰性图标不进无障碍树。需要语义时请在父元素上写 aria-label（如 ScrollControls 的 title）。

2.2 客户端字符串版本 iconSvg()

有些地方需要在构建期拼 HTML 字符串（代码块头部、复制按钮），不能渲染组件，于是 src/lib/icons.ts 提供了同名函数：

import { iconSvg, type IconName } from '@/lib/icons'
iconSvg('mdi-content-copy')          // → '<svg class="mdi-icon" …></svg>'
iconSvg('mdi-check', 'text-green')   // 第二参数追加 class

3. 常驻组件（位于 #swup-container 之外）

3.1 SiteHeader.astro

导航项 = 注册表 + 配置白名单两级：SiteHeader.astro 内的 NAV_DEFS 登记每个可用 path 的词条 key 与图标，siteConfig.nav（字符串数组）决定「显示哪些、什么顺序」；首页 / 固定第一位、不可移除，无需写入配置：

// src/site.config.ts
nav: ['/archive', '/categories', '/tags', '/series', '/friends', '/about'],

// SiteHeader.astro
const navConfig = siteConfig.nav ?? []                              // 缺失/类型非法时回退空数组
const navItems = [
  { path: '/', label: t('nav.home'), icon: mdiHomeOutline },        // 固定第一项
  ...[...new Set(Array.isArray(navConfig) ? navConfig : [])]
    .filter((path) => path !== '/' && path in NAV_DEFS)             // 去重、忽略未登记的 path
    .map((path) => ({ path, label: t(NAV_DEFS[path].key), icon: NAV_DEFS[path].icon })),
]

现有导航页（/archive ~ /about）只需在 siteConfig.nav 里增删/排序，空数组 [] 则顶栏只剩首页一项；新增自定义页面还要在 NAV_DEFS 登记词条 key 与图标 + 在三个 i18n 的 JSON 里加对应 nav.* 词条。图标来自 src/lib/icons.ts（MDI path 常量）。

结构要点：

交互脚本（SiteHeader.astro 底部 <script>）：点击 header details 外部时移除 open 属性关闭菜单；同一脚本内的 fitNavLabels() 按 --nav-window 缩放导航词条（选择器限定为 header nav .nav-label），并在 document.fonts.ready 后再复校一次。

首页高亮特例：isHomePaged = /^\/\d+(\/|$)/.test(currentPath)，即 /2/、/3/ 这类分页路径也视为[首页]高亮。

3.2 SiteFooter.astro

构建期取最早一篇文章的发布时间，运行时长（天/时/分/秒）由客户端脚本每秒实时计算。published 在 content.config.ts 中按 UTC 解析（无时区字符串补 Z），因此存储的是真实 UTC 时刻；运行时长 = 访问者当前 UTC（Date.now() 即 UTC epoch）− 发布 UTC，不依赖构建机、也不依赖访问者的本地时区，所有访问者看到一致的结果：

// 构建期：只确定起点，并把初始时长写进页面作为无 JS 的回退显示。
// earliest 已是真实 UTC 时刻（schema 层按 UTC 解析）
const publishedPosts = await getPublishedPosts()
const earliest = publishedPosts.reduce<Date | null>(
  (min, p) => (min === null || p.data.published < min ? p.data.published : min),
  null,
)
function breakdown(ms: number) { /* …拆分天/时/分/秒… */ }
const buildUnits = earliest ? breakdown(Date.now() - earliest.valueOf()) : null

// 客户端：当前时间与最早文章时间的差值实时计算，精确到秒（<script> in SiteFooter.astro）
function breakdown(ms: number) {
  const total = Math.max(0, Math.floor(ms / 1000))
  return {
    days: Math.floor(total / 86400),
    hours: Math.floor((total % 86400) / 3600),
    minutes: Math.floor((total % 3600) / 60),
    seconds: total % 60,
  }
}
function updateRunningTime() {
  document.querySelectorAll<HTMLElement>('[data-running-days]').forEach((el) => {
    const iso = el.dataset.earliest
    const template = el.dataset.template
    if (!iso || !template) return
    const u = breakdown(Date.now() - new Date(iso).getTime())
    const text = template
      .replaceAll('{days}', String(u.days))
      .replaceAll('{hours}', String(u.hours))
      .replaceAll('{minutes}', String(u.minutes))
      .replaceAll('{seconds}', String(u.seconds))
    if (el.textContent !== text) el.textContent = text
  })
}
updateRunningTime()
document.addEventListener('astro:page-load', updateRunningTime)
// 每秒刷新，秒位实时跳动；重复执行时只挂一个定时器
if (!('__runningTimeTimer' in window)) {
  ;(window as any).__runningTimeTimer = setInterval(updateRunningTime, 1000)
}

运行时长的实现细节：

• <p data-running-days> 上挂 data-earliest（ISO 时间，带 Z，构建期写入）和 data-template（当前语言的 footer.running 文案），服务端先渲染构建期算好的初始值。
• 完全实时，不受构建固定：首次加载、Swup 换页（astro:page-load）、以及每秒的定时器都会用客户端当前时间与最早文章时间的差值重算四个单位；仅文本变化时写 DOM，避免无谓重排。页面一直开着，秒位也会实时跳动并自动进位。
• 语义为"经过的时长"（毫秒差拆分为天/时/分/秒），时区无关。

3.3 SearchModal.astro

DOM 关键 id（改样式时直接定位这些 id）：

行为参数（源码内常量，可直接调）：

搜索结果渲染的字段（与 Pagefind 返回结构对应）：

item.url              // 结果链接（页面级，无 hash）
item.meta?.title      // 标题（缺省回退到 url）
item.excerpt          // 页面级摘要（Pagefind 自带高亮 <mark>），仅在没有子结果时兜底显示
item.sub_results      // 章节级子结果：按带 id 的 h1~h6 拆分页面，命中多的章节优先
//   sub.url         // 形如 /posts/xxx/#章节id（中文锚点已百分号编码）
//   sub.title       // 章节标题（首个无锚点子结果是页面本身，渲染时跳过）
//   sub.excerpt     // 该章节内的高亮摘录
//   sub.anchor      // { element, id, text, location }，用于去重与回退取标题

excerpt 是 Pagefind 生成的 HTML，未经 escapeHtml，这是有意为之（保留高亮 <mark>，用 [&_mark]: 任意属性选择器上主题色）；url 与 title 走了 escapeHtml。

结果卡片结构：文章标题（点击进文章顶部）→ 分隔线 → 命中章节列表（最多 MAX_SUB_RESULTS 条，点击滚动到对应标题）。文章无带 id 的标题时退化为「标题 + 页面级摘录」。

3.4 ScrollControls.astro

右侧整合菜单：底部一个常驻「菜单」触发器（data-scroll-menu，汉堡图标，只负责展开/收起），点击后其余按钮从触发器左侧横向弹出（在 .scroll-control-nav 上加 .is-open）；从左到右：目录 → 主题 → 搜索 → 回顶（回顶最靠近触发器）。滚动、点击外部、按 Esc 或换页（astro:before-swap）都会自动收起。

弹层内按钮（从左到右，回顶最靠近触发器）：

定位：触发器 fixed right-5 bottom-8 z-[90] max-md:right-3 max-md:bottom-16，弹出层用绝对定位锚定在其左侧（right: calc(100% + 8px); bottom: 0），横向排开。启用音乐播放器时，音乐 FAB 由 MusicPlayer.reposition() 固定在右下底部槽位（桌面 32 / 移动 64），菜单触发器随之挪到音乐按钮正上方（原搜索位置）。

桌面侧边目录（#toc-affix，仅 xl 且有目录时出现）自带收起/展开：标题行右侧的 #toc-collapse 按钮把面板淡出，同时在右下菜单触发按钮正上方浮出 #toc-expand FAB（复用 scroll-control-btn 样式；位置由 PostPage 的 positionTocExpandFab() 读取 [data-scroll-menu] 矩形实时计算，音乐按钮启用时菜单上移、FAB 跟随，音乐仍保持最底；菜单弹层向左弹出后不占用该位置，菜单展开时 FAB 无需隐藏）。收起状态存于模块变量 tocCollapsed，换文章页时由 initPage() 重新应用（跨文章保持）。移动端（<xl）不渲染该控件，仍走 toc-fab 弹窗目录。

⚠️ hidden 属性必须靠 CSS 显式覆盖。ScrollControls.css 里有 .scroll-control-btn[hidden] { display: none }，因为 display: inline-flex 优先级高于 hidden 属性的默认样式。自定义按钮时别丢这条规则。

3.5 Pet.astro

Prop：lang?: Lang（默认 defaultLang）。宠物本体没有文案，但长按弹出的「请去休息」气泡需要翻译，用到 pet 下的 dialogLabel / title / desc / confirm 四个词条（三份语言包齐全，由 scripts/check-i18n.js 保证键集合一致）；另有 pet.restore 供名片上的「唤回宠物」按钮使用。

渲染条件与结构：

const petEnabled = siteConfig.pet?.enabled === true

<div class="pet" data-pet>
  <div class="pet-face" data-pet-face aria-hidden="true">
    <div class="pet-slide" data-pet-slide>
      <div class="pet-eyes" data-pet-eyes>
        <span class="pet-eye" data-pet-eye></span>
        <span class="pet-eye" data-pet-eye></span>
      </div>
    </div>
  </div>
  <div class="pet-card" data-pet-card role="dialog" aria-label="…" hidden>
    <p class="pet-card-title">…</p>
    <p class="pet-card-desc">…</p>
    <div class="pet-card-actions">
      <button class="pet-btn pet-btn-ok" type="button" data-pet-dismiss>…</button>
    </div>
  </div>
</div>

各层各管一件事（Pet.css + lib/client/pet.ts）：.pet 定位与尺寸；.pet-face 承载描边与辉光，装饰本体整体带 aria-hidden="true"（气泡是对外可读的对话框，所以放在它外面、与本体同级）；.pet-slide 只做纵向滑出位移；.pet-eyes 只做视线位移；.pet-eye 只做 scaleY 眨眼。消解 / 聚合期间由 JS 临时插进 .pet-face 的方格层 .pet-grid（子元素 .pet-cell）不写进模板，见下文「方格消解与聚合」。组件还内嵌一段 is:inline 守卫脚本，见下文「休息期与首帧守卫」。

外形：.pet 是 8×8 个 --pet-unit 的方框，.pet-face::before 用 border: var(--pet-unit) solid var(--pet-ink) 描出一圈 1 格厚的方边（z-index: 2），中间留出 6×6 的空洞当「脸」；两只 .pet-eye 各 1 格宽 × 2.5 格高、间距 1 格（合计 3 格宽），--pet-ink: var(--wp-accent)，外圈再带一层主色 35% 的柔光（box-shadow 的 --pet-glow）。.pet-face 自身 overflow: hidden，滑出的眼睛到边沿就被裁掉，看起来是从框里滑出去。所以宠物完全由主色与方格组成，没有图片资源。这套 8×8 几何同时也是消解 / 聚合动画的基础：那圈 1 格厚的描边正好等于网格的最外圈（28 格），JS 按行列生成等大的方格就与描边完全重合，不必另算坐标。

尺寸与定位（Pet.css 顶部的变量）：

• position: fixed，left: max(16px + env(safe-area-inset-left), anchor − size − 28px)：宽屏时紧贴内容列左侧停放，窄屏兜底到视口左缘 16px，不会溢出视口。
• bottom: max(var(--pet-bottom), env(safe-area-inset-bottom))：CSS 里先按 ScrollControls 的档位兜底（bottom-8 = 32px，≤768px 时 max-md:bottom-16 = 64px），随后 syncBottom() 量测右侧按钮组（.scroll-control-nav 与启用时的 .music-fab）中最低的那条底边，改写成 窗口高 − 底边，宠物底边因此始终与按钮组最低处齐平——音乐播放器把 FAB 放到底部槽位、菜单触发器上移时也跟得上。z-index: 80（低于右下按钮组的 90 / 顶层的 100）。
• pointer-events: none：纯装饰，永不拦截点击；aria-hidden="true"：不进无障碍树。

行为（lib/client/pet.ts，常量集中在文件头部）：

实现要点：

长按气泡与 24 小时休息

方格消解与聚合

宠物外框按 8×8 网格拆解，只取最外圈 28 格——正好与 .pet-face::before 那一格厚的描边完全重合：

休息期与首帧守卫

<Pet /> 在 #swup-container 之外，由客户端脚本（deferred module）接管，而宠物先于脚本绘制——如果只靠脚本判断，被关掉的宠物会先闪一帧再消失。所以组件内嵌一段 is:inline 守卫脚本，在宠物 DOM 解析前就给 <html> 打类名：

initPet() 遇到未过期的 petClosedUntil 时只调 syncRestoreBtn(true) 就返回，不初始化宠物本体；不再像从前那样把根节点 remove()，否则「唤回」就没有落脚点了。

唤回按钮（名片侧）

宠物去休息后，入口落在首页名片的社交条上（ProfileCard.astro 的 .social-strip 内、时钟切换按钮左侧），仅当 siteConfig.pet?.enabled === true 时渲染；平时带 hidden，由 lib/client/pet.ts 在宠物进入 / 退出休息时切换：

4. 内容展示组件

4.1 ProfileCard.astro

数据全部来自构建期计算：

社交按钮与时钟开关（渲染在名片正下方的 .social-strip：条首是 42×42 直角 .card-toggle 时钟开关，与右侧社交块并入一个整体、全部共边零间隙；启用宠物时它左侧还会多一颗同规格的「唤回宠物」按钮 .pet-restore，平时带 hidden 不占位，只在宠物处于 24 小时休息期时出现，出现 / 收起动画与点击复活见 §3.5；社交块 42×42 纯图标正方形、块间与卡片底边共边无缝、整排居中，hover/focus 均用顶栏 nav-clip 同款品牌色板下拉动效；卡片内部不再渲染社交行与横线，wrapper 也不再需要 pt-8 顶部空间）：

siteConfig.socials 每项 { platform, url }，映射逻辑（源码第 44–82 行）：

已内置的 platform 键（大小写不敏感，会 toLowerCase()）：

按钮 hover 变色通过内联自定义属性实现：

<a class="social-btn" style={'--p-brand:' + s.brand} aria-label={s.label} title={s.label}>…</a>

CSS 里色板动效 .social-btn::before 直接取 var(--p-brand)（nav-clip 同款：hover/focus 时从上方 translateY(-101%) → 0 拉下，0.5s cubic-bezier(0.4, 0, 0.2, 1)），hover/focus 同时把图标转白（color: #fff，SVG 走 currentColor）、边框改为品牌色。所以加平台只改 ProfileCard.astro 的两个映射表即可，无需动 CSS。

外链处理：isExternal(url) = /^(https?:|mailto:)/，外链加 target="_blank" rel="noopener noreferrer"；mailto: 不加 target。

平台名文本：label = platform.charAt(0).toUpperCase() + platform.slice(1)，即 github → Github。方块为纯图标，label 用作 aria-label / title；想改提示文案（如 GitHub），需改这段逻辑或改用固定映射表。

响应式断点（ProfileCard.css）

顶边居中的时钟切换采用「刷漆」动效，机制如下（时钟视图与走时 / 切换逻辑已整体拆到 components/DigitalClock.astro，由本节的名片渲染调用；布局与样式未变，.clock-layer 样式仍在 ProfileCard.css）：

另一套主题预览镜头（鼠标划入首页名片；窗口样式在 main.css 的共享 .card-preview 块，行为由 src/lib/pointerPreview.ts 的 attachPointerPreview(el, options) 统一提供，ProfileCard.astro 只传自己的外观 / 同步参数）：方窗里不是色块，而是把卡片克隆一份、整体套上相反主题 token 后的真实渲染——即「访客切到暗夜 / 白天模式时这张名片长什么样」。

名片与文章卡共用同一份实现（src/lib/pointerPreview.ts 的 attachPointerPreview(el, options)）：创建浮窗、跟随指针、进出淡入、克隆构建与生命周期只有一处代码，两张卡片只在 options 里声明差异：

名片侧的具体行为：

4.2 PostCard.astro

渲染内容与来源：

角标定位机制（PostCard.css）：角标分为三组，定位方式不同——

统一形成「骑在卡片边缘」的贴纸效果。移动端（≤768px）偏移量收到 -4px，高度 30→26px，字号 12→10px。

hover 效果：卡片 hover:-translate-y-0.5 hover:shadow-card-hover；角标 hover:scale(1.05) + box-shadow: 0 4px 16px color-mix(in srgb, var(--wp-accent) 40%, transparent)。

预览方窗（与名片同一套机制：同一份 lib/pointerPreview.ts 的 attachPointerPreview，样式在 main.css 共享块，克隆的 hover 复刻在 PostCard.css；PostCard.astro 只传 prepareClone / resetOnDetach / hover 三项差异参数）：每张文章卡同样内嵌 .card-preview 覆盖层（position: absolute; inset: -1px、overflow: hidden、pointer-events: none、inert），鼠标划入时用 clip-path: inset(...) 露出指针处 56×56 方窗，窗口里是反主题克隆：

4.3 Pagination.astro

URL 生成规则：

pageUrl(1)  → `${base}/`        // 第 1 页不带页码
pageUrl(n)  → `${base}/${n}/`   // 其余带页码，注意尾斜杠

页码省略算法（源码第 21–32 行，s = 1 为[当前页两侧各保留 1 个]）：

想改「当前页两侧保留几个」，改 const s = 1。

样式（组件内 <style>，非独立 CSS 文件）：

hover 统一：变主题色背景 + scale(1.05) + box-shadow: 0 4px 16px color-mix(in srgb, var(--wp-accent) 40%, transparent)。

4.4 HomePage.astro

渲染顺序：ProfileCard → <h1 class="sr-only"> （无障碍标题）→ 文章卡片列表 → Pagination。

空状态：posts.length === 0 时显示 t('list.empty')（暂无文章）。

4.5 ArchivePage.astro

被三个路由复用：/archive（全部文章）、/categories/[name]（某分类）、/tags/[name]（某标签）。

分组逻辑：

const pinned = posts.filter(p => p.data.index > 0)                    // 置顶区，单独展示
const grouped = groupByYear(
  posts.filter(p => p.data.index <= 0)                                // 非置顶按年分组
       .sort((a,b) => b.data.published.valueOf() - a.data.published.valueOf())
)

每行结构：MM-DD 日期 → 标题（truncate）→ 分类图标+名 / 首个标签（md 以上才显示）。

4.6 TaxonomyPage.astro

分类总览与标签云合并为一个组件，由 kind 决定词汇表差异（渲染 / 搜索 / 排序逻辑只此一份）。

两种词汇表的差异（其余 DOM 结构完全一致）：

交互（客户端脚本，按根元素 id 判定当前词汇表）：

排序偏好持久化：src/stores/ui.ts 的 categoriesSort / tagsSort（localStorage 同名 key，取值 'name' | 'count'，默认 'count'）。

想加「按拼音排序」

把 localeCompare(b, 'zh') 换成 localeCompare(b, 'zh-Hans-CN', { numeric: true })，或引入 pinyin-pro（依赖里已有）先转拼音再比较。

4.7 FriendsPage.astro

数据归一化（src/lib/friends.ts）：

卡片结构：<a class="friend-card"> → 头像槽（.friend-avatar，内含首字母 .friend-avatar-fallback + 可选 <img onerror="this.remove()">）→ 名称/描述 → 跳转图标。

入场错峰动画：内联 style={--stagger: ${Math.min(i, 8) * 60}ms}，最多 8 档（即第 8 张及以后都是 480ms），避免长列表尾部等待过久。

空状态：friends.length === 0 时渲染一个手绘 SVG 哭脸（FriendsPage.css 里驱动眼睛/眼泪动画），文案 friends.emptyTitle + friends.emptySub（后者用 set:html 注入 <code>src/site.config.ts</code>）。

页面底部：额外渲染一个 <Comments />（即友链页也有评论区，受 siteConfig.commentScript 控制）。

4.8 AboutPage.astro

自定义页面，支持使用 html 。

4.9 Comments.astro

无 Props。是否渲染完全由 siteConfig.commentScript 决定：

const commentScript = siteConfig.commentScript
{commentScript && (
  <section class="comment-section is-loading" data-comment-script={commentScript} aria-label="Comments">
    <div class="comment-skeleton" aria-hidden="true"><span/><span/><span/></div>
    <div class="comment-mount" />
  </section>
)}
<script>import '@/comments/client'</script>

comment-mount 是插件唯一被允许写入的容器。契约见 08-插件系统.md#2。

4.10 MusicPlayer.astro

代码结构（T10 拆分后）：MusicPlayer.astro 只留视图（面板 / 列表 / 控制条 DOM）与事件绑定，逻辑分三处：

组件与 lib/player.ts 通过 MediaPort（组件实现：setSource / play / pause / isPaused / 进度 / 音量）+ 状态回调（onState / onTrack）通信，双方都不直接操作对方 DOM。

播放列表来源（两级优先）：

扫描支持的扩展名（源码 src/lib/musicPlaylist.ts 的 AUDIO_EXTS）：

# 已验证
.flac  .mp3

# 未验证
.m4a  .ogg  .wav  .opus  .aac  .webm

自动生成的条目：title = 去扩展名的文件名，src = /music/${encodeURIComponent(文件名)}（中文名会被 URL 编码）。

封面来源：cover 显式指定优先；否则客户端用 src/lib/audioCover.ts 通过 Range 请求只读文件头 ≤ 2MB，解析 FLAC PICTURE 块或 MP3 ID3v2 APIC 帧，URL.createObjectURL 成 blob 展示。拿不到封面时按钮显示音符图标。

audioCover.ts 的 FETCH_LIMIT = 2 * 1024 * 1024（2MB），若你的音频封面位于 2MB 之后会取不到（极少见）。

关键 DOM 属性（改样式/写脚本时定位用）：

注入给客户端的配置：

<script is:inline define:vars={{ playlist, ui }}>
  window.__musicPlayerConfig = { playlist }   // 曲目列表
  window.__musicPlayerUI = ui                 // 控件文案（来自 i18n 的 player.* 词条）
</script>

两个都要注入：客户端读 window.__musicPlayerUI 来设置按钮文案，只注入 __musicPlayerConfig 会让按钮缺失无障碍文案。

功能：播放/暂停/停止、上一首/下一首、随机、顺序、单曲循环、音量、进度条拖拽、播放列表选择、曲目索引与时长显示。切换页面不中断（组件在 #swup-container 外）。

开关：siteConfig.musicPlayer.enabled（当前 true）。设为 false 时整个组件不渲染。

4A. 图标系统（src/lib/icons.ts）

全站图标硬编码在 src/lib/icons.ts：66 个 export const mdiXxx = '<path d>' 常量，加一个 icons 映射表（kebab-case 名 → path）与两个导出。

设计取向（源码注释 + 添加自定义图标.md）：零网络请求、零依赖，代价是加图标要手写三步。

4A.1 三个导出

export function iconSvg(name: IconName, cls = ''): string {
  return `<svg class="mdi-icon${cls ? ` ${cls}` : ''}" width="1em" height="1em" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="${icons[name]}"></path></svg>`
}

4A.2 添加图标的三个步骤

第 1 步：在 MDI 图标库 复制 SVG path，按字母序粘贴到 src/lib/icons.ts 顶部：

export const mdiAbTesting = 'M4 2A2 2 0 0 0 2 4V12H4V8H6V12H8V4…'

第 2 步：在文件底部的 icons 映射表加条目（key 必须是 kebab-case 全名，与常量名对应）：

export const icons = {
  // ...
  'mdi-ab-testing': mdiAbTesting,
} as const

第 3 步：在组件里使用

---
import Icon from '@/components/Icon.astro'
import { mdiAbTesting } from '@/lib/icons'
---

<Icon d={mdiAbTesting} class="text-sm" />

或在构建期拼字符串：iconSvg('mdi-ab-testing')。

漏掉第 2 步会类型报错

IconName = keyof typeof icons，只加常量不加映射时，iconSvg('mdi-ab-testing') 会 TS 报错。

4A.3 现有图标 → 使用位置对照（部分）

4A.4 平台图标（首页社交按钮）

ProfileCard.astro 里有两张独立的映射表，加平台只改组件、不用改 CSS：

品牌色通过内联 CSS 变量传递，驱动 nav-clip 同款色板下拉动效（ProfileCard.css）：

<a class="social-btn" style={'--p-brand:' + s.brand} aria-label={s.label} title={s.label}>…</a>

.social-btn::before { background-color: var(--p-brand); transform: translateY(-101%); transition: transform 0.5s cubic-bezier(0.4, 0, 0.2, 1); }
.social-btn:hover::before { transform: translateY(0); } /* 色板拉下盖住方块 */
.social-btn:hover { border-color: var(--p-brand); color: #fff; }

5. BaseLayout.astro 参数与注入项

5.1 Props

5.2 OG locale 映射

const ogLocale = { zh: 'zh_CN', ja: 'ja_JP', en: 'en_US' }[lang]

5.3 输出到 <html> 的属性

5.4 防闪烁主题脚本（<head> 内联）

var stored = localStorage.getItem('themeMode')
var mode = (stored === 'light' || stored === 'dark') ? stored : defaultTheme
if (mode !== 'light' && mode !== 'dark') {                 // 即 defaultTheme === 'auto'
  mode = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
}
document.documentElement.classList.toggle('dark', mode === 'dark')
document.documentElement.style.colorScheme = mode

这段脚本必须在 <head> 同步执行，否则会出现「先白后黑」闪烁。改主题逻辑时不要把它改成 module 或挪到 <body> 末尾。

5.5 #swup-container 外的脚本职责（src/lib/client/*）

BaseLayout.astro 底部只有一行 <script>import '@/lib/client'</script>，实现按职责拆到 src/lib/client/（入口 index.ts 按下列顺序执行）：

各绑定与迁移前一致（逐段搬运）：

跨页锚点（/posts/xxx#slug）的平滑滚动由上述「跨页锚点点击委托」+ consumePendingScrollHash() 实现；配合 <head> 里一段内联「去 hash」脚本，直接打开收藏/分享的 # 深链接同样不闪现。完整流程见 07-页面与路由.md#84。

6. 全局事件与 data 属性协议速查

改组件或加组件时，沿用这些约定就能自动接入现有交互：

6.1 自定义事件

6.2 data-* 属性

新增常驻脚本的正确姿势：

在 .astro 里写 <script>，并用 onPageLoad() 包裹初始化：

ts复制

123

import { onPageLoad } from '@/lib/pageLifecycle'
function initMyWidget() { /* 幂等初始化 */ }
onPageLoad(initMyWidget)

onPageLoad 会同时监听 astro:page-load 并在「本次加载已经触发过」时立即执行，避免 Swup 换页后脚本不跑。