互动功能与多媒体配置

Mizuki 主题中的互动功能（评论、搜索、日记动态、密码保护）与多媒体能力（视频嵌入、Mermaid 图表、音乐播放器、全屏壁纸、分享海报）共同构成站点的用户交互层。本页说明这些能力在代码架构中的组织方式、内容侧的配置写法，以及它们与内容渲染管线的衔接关系。

目的与范围

本页覆盖：

• src/components/features/ 下互动与多媒体功能组件的目录边界与职责划分（comment、search、protection、media）
• 内容文件（src/content/posts/*.md）中多媒体与交互元素的配置写法：视频 iframe 嵌入、Mermaid 图表
• 旧组件向 features/media 归位的迁移规则

本页不覆盖以下内容，它们属于兄弟页面：

• 内容创作流程与 frontmatter 字段规范 —— 见"内容创作"相关页面
• 内容渲染管线（Markdown → HTML 的完整链路）—— 见"内容渲染"相关页面
• 部署与构建 —— 见"部署"相关页面

概述

Mizuki 是一个基于 Astro + Svelte 的博客主题。站点对"互动"与"多媒体"的处理分为两条线：

1. 功能组件线：Svelte/Astro 组件以 src/components/features/ 为家目录，按业务域拆分为四个子目录——comment（评论互动）、search（站内搜索）、protection（密码保护，属于访问控制型互动）、media（媒体相关）。这种按 feature 而非按组件类型（atom/molecule/organism）归类的做法，目的是让"一个用户可感知的功能"在文件树上聚拢，便于维护与查找。

2. 内容配置线：博主在 src/content/posts/ 下的 Markdown 文件中，通过 HTML 直嵌（如 <iframe> 视频嵌入）和容器指令（如 Mermaid 代码块）来声明多媒体内容，由渲染管线在构建期转换为最终页面。

关键概念：

架构

下图为互动与多媒体能力在组件层与内容层的真实组织结构（依据 docs/rule/03-file-organization-architecture.md 的目录规范）：

设计意图解读：

• media 作为聚合域：features/media/ 不是"图片文件夹"，而是"媒体型功能组件"的家——播放器、壁纸、海报生成、Markdown 渲染器都归入此处。官方迁移规则明确写着 FullscreenWallpaper.astro → features/media/、Markdown.astro → organisms/ 或 features/media/、SharePoster.svelte → features/media/，说明该目录被定位为媒体能力的统一落点。
• comment / search 与媒体分离：评论与搜索是纯互动功能，不涉及媒体资源，因此与 media 平级而非嵌套其中。
• protection 单独成域：密码保护属于访问控制，被列为独立 feature，避免与业务展示逻辑耦合。

实现细节

功能组件目录的划分依据

src/components/features/ 下的四个子目录是项目文件组织规范中明确规定的。规范给出的初始化命令为：

Source: 03-file-organization-architecture.md

配套的目录树定义（节选自规范中的组件目录结构）：

Source: 03-file-organization-architecture.md

以及组件层面的归位说明：

Source: 03-file-organization-architecture.md

这条规范回答了"一个新组件应该放哪"的问题：凡是承载一个完整用户可感知功能的组件，进入 features/<功能名>/，而不是散落在 atoms/ 或 organisms/ 中。这样做的收益是：修改评论功能时只需要关注一个目录，代码评审的 diff 也天然按功能聚合。

多媒体内容的两种配置形态

Mizuki 中博主配置多媒体内容主要走两条路径：

形态一：HTML 直嵌（构建期直通）

视频等内容直接在 Markdown 中书写标准 HTML，示例取自仓库内的演示文章 src/content/posts/video.md：

Source: video.md

注意 allow 属性中列出的 encrypted-media、picture-in-picture、web-share 等权限——这是嵌入第三方播放器时浏览器安全模型的要求，直嵌方式把这些控制权完全交给内容作者。

形态二：容器指令（渲染期处理）

Mermaid 图表使用 fenced code block 声明，由渲染管线在构建期转换为 SVG，演示文章 markdown-mermaid.md 中包含饼图示例：

Source: markdown-mermaid.md

两种形态的本质差异：直嵌的 HTML 在运行时仍由浏览器直接执行（iframe 独立加载第三方资源）；容器指令则在构建期就被静态化为 SVG，页面加载后没有额外的脚本执行开销。这也是演示内容同时提供两种示例的原因——让作者直观对比取舍。

互动功能的站点级能力

站点规格文件 src/content/spec/about.md 描述了面向用户的互动能力清单，其中提到：

• Diary/Moments Page — 以类似社交媒体动态的方式分享生活瞬间
• Friends Links Page — 以卡片形式展示友站
• 评论、搜索等由 features/comment/、features/search/ 组件承载

Source: about.md

使用示例

新增一个视频文章

在 src/content/posts/ 下创建 Markdown 文件，直接粘贴标准 iframe 嵌入代码（完整示例见上方"形态一"）。仓库自带的 video.md 即为此用法的一个完整可运行样例。

在文章中插入 Mermaid 图表

在 Markdown 中使用 ```mermaid 代码块，参考仓库演示文章 src/content/posts/markdown-mermaid.md（其饼图数据段见上方"形态二"引用）。

把旧组件迁移到 media 目录

规范中给出的迁移对照表明确定义了归位目标：

Source: 03-file-organization-architecture.md

注意其中 ImageWrapper.astro → atoms/ 的对照：它说明"与媒体沾边"并不自动进入 features/media/——只有承载完整功能行为的媒体组件才进 feature 目录，纯展示的原子组件仍归 atoms/。这是一条重要的判断准则。

核心流程

一篇包含多媒体与互动元素的文章，从书写到呈现的链路如下：

流程要点：

1. Mermaid 在构建期处理：图表在构建阶段就变成 SVG，浏览器拿到的是静态标记。
2. iframe 在运行期执行：直嵌的 HTML 到浏览器端才真正加载第三方资源，因此视频可用性依赖外链服务的可达性。
3. Markdown.astro 是正文渲染的落点：它被规范归入 organisms/ 或 features/media/，处于媒体组件与内容管线的交界处。

配置选项

本页主题对应的可配置项主要分布在两处：内容文件本身（Markdown 内的多媒体写法）与 astro.config.mjs（Astro 站点级配置入口，已在仓库根目录确认存在）。

注意：astro.config.mjs 中与互动/多媒体直接相关的具体键名及其默认值，未能在本次源码探查预算内读取到实现细节。此部分留待后续在对应的"站点配置"页面补充，避免在无源码佐证的情况下虚构配置表。

已从源码与规范中确认的"配置形态"汇总如下：

失败模式与边界情况

基于已读源码可确认的边界行为：

• iframe 外链依赖：直嵌视频依赖第三方服务（如示例中的 YouTube）在读者网络环境下可达。页面本身是静态产物，第三方不可达时表现为嵌入区域空白，但不影响页面其余部分渲染——这是直嵌方案天然的容错边界。
• 浏览器权限白名单：allow 属性决定了嵌入内容能使用哪些浏览器能力（autoplay、clipboard-write、encrypted-media 等）。过度收紧会破坏播放器功能，过度放开则扩大第三方脚本的权限面，需要内容作者自行权衡。
• 组件放置错误：把原子组件误放进 features/media/（或反之）不会造成运行时错误，但会破坏规范约定的可维护性。规范中的迁移对照表正是用于纠正这类偏差。
• Mermaid 语法错误：容器指令在构建期处理，语法错误会在构建阶段暴露，而不是等到读者访问时——这属于"尽早失败"的良性设计。

实现细节超出本次源码探查范围、未能验证的部分（如评论与搜索组件的具体数据流、protection 的密码校验实现），本文不作臆测。

扩展点

• 新增媒体功能组件：在 src/components/features/media/ 下新建组件，遵循既有命名（MusicPlayer.svelte、SharePoster.svelte 均为功能名直译），然后按 docs/rule/03-file-organization-architecture.md 的规范接入。
• 新增互动功能域：按 comment/search/protection 的既有模式，新建 features/<功能名>/ 目录承载完整功能。
• 多媒体内容形态扩展：内容侧可继续沿用"直嵌 HTML"或"容器指令"两种既有形态，无需改动组件层。

相关链接

• 内容创作规范（CONTENT_AUTHORING）
• 内容渲染（CONTENT_RENDERING）
• 文件组织架构规范
• 视频嵌入示例文章
• Mermaid 示例文章