Sep 01·12 min· PV

实验：自定义组件预览

预览本博客主题使用的自定义 Markdown 组件，附使用说明和源码示例。

Blog·CSS·Markdown

本页面预览本博客主题中可用的自定义组件。各节先展示渲染后的组件，再展示重现所需的 Markdown 或 HTML。

这些组件是嵌入 Markdown 的自定义 HTML 元素。使用组件前务必加载对应模块，并在 script 标签上加上 data-swup-reload-script，确保客户端导航后组件能重新加载。

本文可作为快速参考，但在实际文章中请有目的地使用组件。组件应当让结构、对比或上下文更清晰。如果纯 Markdown 能更好传达想法，就用纯 Markdown。

标签页

标签页适用于读者需要对比相关视图、但不想滚动重复内容的场景。本文中，每个组件均使用标签页来分隔实时预览和源码 Markdown。

标签标题尽量简短。在默认的 <x-tab> 上添加 active，每个面板使用一个 <x-tab title="...">。标签内容前后留空行，尤其是内容包含 Markdown 块或自定义 HTML 时。

图片轮播

当多张图片属于同一序列、场景或对比时，适合使用图片轮播。适用于旅行笔记、视觉导览和紧凑图集。

使用前加载 /js/components/image-carousel.IYKDK3C2.js。在 <image-carousel> 内部使用 Markdown 图片语法，图片列表前后留空行。只有在动态效果增强页面时才使用 autoplay，否则让读者手动浏览。interval 单位为毫秒。

宽高比来自第一张图片的自然尺寸，因此肖像和风景混合的图片不会被迫裁切到固定的 3/2 比例。传入显式 ratio（如 ratio="16/9"）可覆盖，使每张幻灯片固定为同一比例。导航通过前/后按钮、圆点、键盘方向键和触摸滑动实现；自动播放会在鼠标悬停、轮播滚出视野或标签页隐藏时自动暂停。

<script data-swup-reload-script type="module" src="/js/components/image-carousel.IYKDK3C2.js"></script><image-carousel autoplay interval="4000">![登山](https://assets.vluv.space/登山者.avif)![渔村](https://assets.vluv.space/珠山秀谷-珠山海边村落.avif)![山,海,船](https://assets.vluv.space/山海.avif)![映山湖与海](https://assets.vluv.space/映山湖与海.avif)</image-carousel>

图文段落

当图片和段落需要一起阅读时，使用图文段落。当图片为人物、地点、引言或历史注释提供背景时，它比独立图片更好。

使用前加载 /js/components/text-image-section.JMC6RB5X.js。提供有意义的 alt 值，有意识地设置 width，文字保持精炼。长文本也可以，但图片和文字形成紧凑一体的效果最佳。

图片渲染为 <figure>（alt 文字复用为 <figcaption>），默认浮动在文字右侧；添加 left 属性可翻转布局。屏幕宽度小于 640px 时，图片会堆叠在文字上方全宽显示。宿主元素内部创建独立的块格式化上下文，因此 Hexo 包裹的 <blockquote> 不会在移动端将左侧边框渗入图片区域。

赫尔曼·卡尔·黑塞（1877年7月2日－1962年8月9日）是一位德国-瑞士诗人和小说家，1946年诺贝尔文学奖得主。他对东方宗教、精神和哲学传统的兴趣，加上他对荣格分析心理学的涉猎，塑造了他的文学创作。他最著名的小说包括《德米安》《荒原狼》《悉达多》《纳尔齐斯与歌尔德蒙》和《玻璃球游戏》，每部作品都探索了个体对真实、自知和精神性的追寻。

<script data-swup-reload-script type="module" src="/js/components/text-image-section.JMC6RB5X.js"></script><text-image-section image="https://www.myinterestingfacts.com/wp-content/uploads/2014/03/Hermann-Hesse-Image.jpg" alt="Hermann Hesse" width="200px" font-size="1.1rem" font-family="homemade-apple">**Hermann Karl Hesse** (2 July 1877 – 9 August 1962) was a German-Swiss poet and novelist, and winner of the 1946 Nobel Prize in Literature. His interest in Eastern religious, spiritual, and philosophical traditions, combined with his involvement with Jungian analysis, helped to shape his literary work. His best-known novels include Demian, Steppenwolf, Siddhartha, Narcissus and Goldmund, and The Glass Bead Game, each of which explores an individual's search for authenticity, self-knowledge, and spirituality.</text-image-section>

手风琴 🪗

手风琴适用于较长的可选说明。它保持主页面的可读性，同时允许感兴趣的读者展开细节。

使用前加载 /js/components/accordion.GK5MQZPB.js。每个 <accordion-item> 需要一个明确的 title。标签与 Markdown 内容之间留空行。嵌套的 Markdown 缩进保持一致，尤其是列表和代码块，因为格式错误可能导致自定义元素内的渲染中断。

使用 # 创建标题，数量决定层级。Markdown 支持六级标题，分别对应 HTML 的 <h1> 到 <h6>。通常一篇文章只有一个一级标题作为页面标题，正文内容从二级标题开始。

# 一级标题## 二级标题### 三级标题

用 **粗体** 和 *斜体* 来强调文字。删除线用 ~~删除~~。行内代码用反引号包裹，如 `code`。

这些样式可以自由组合：

粗体 **text**
斜体 *text*
~~删除线~~ ~~text~~
行内代码 `code`

链接语法为 [文字](URL)，图片在链接语法基础上加一个 !：![替代文字](URL)。

[OpenAI](https://openai.com)![Logo](https://example.com/logo.png)

链接的 URL 部分也支持引用式写法，适合需要多次引用同一链接的场景。

<script data-swup-reload-script type="module" src="/js/components/accordion.GK5MQZPB.js"></script><x-accordion>  <accordion-item title="Headings">  Use `#` to create headings. The count of `#` determines the level. Markdown supports six heading levels, corresponding to `<h1>` through `<h6>`. Typically a post has one top-level heading as the page title, and body content starts from level two.  ```md  # Heading 1  ## Heading 2  ### Heading 3  ```  </accordion-item>  <accordion-item title="Text Styles">  Use `**bold**` and `*italic*` for emphasis. Strikethrough uses `~~text~~`. Inline code wraps in backticks, e.g. `` `code` ``.  These styles can be combined freely:  - **bold** `**text**`  - *italic* `*text*`  - ~~strikethrough~~ `~~text~~`  - `inline code` `` `code` ``  </accordion-item>  <accordion-item title="Links &amp; Images">  Link syntax is `[text](URL)`. Images add a `!` prefix: `![alt text](URL)`.  ```md  [OpenAI](https://openai.com)  ![Logo](https://example.com/logo.png)  ```  URLs also support reference-style notation, useful when the same link appears multiple times.  </accordion-item></x-accordion>

文件树 🌳

当目录结构是解释的一部分时，使用文件树。特别适用于主题、脚本、生成资源和中小型项目布局。

使用前加载 /js/components/tree.GS5OHBY3.js。用 root 命名顶级目录。在 <x-tree> 内部，每一项写成 Markdown 列表项，每级缩进用两个空格。当文件夹没有列出子项时，加上尾部 /，让组件仍能将其渲染为文件夹。树的大小以可快速浏览为宜。

source/
- js/
  - components/
    - accordion.js
    - tree.js
    - image-carousel.js
  - main.js
- css/
  - style.css
  - themes/
    - nord.css
    - catppuccin.css
- images/
  - logo.png
scripts/
package.json
README.md
hexo.config.js

<script data-swup-reload-script type="module" src="/js/components/tree.GS5OHBY3.js"></script><x-tree root="gnix-theme">- source/  - js/    - components/      - accordion.js      - tree.js      - image-carousel.js    - main.js  - css/    - style.css    - themes/      - nord.css      - catppuccin.css  - images/    - logo.png- scripts/- package.json- README.md- hexo.config.js</x-tree>

边注

当补充背景信息应当靠近其解释的段落，而又不打断主要阅读流时，使用边注。适用于简短定义、来源引用、注意事项或实现备注。

使用前加载 /js/components/sidenote.AOLVVU76.js。将 <side-note> 紧接在其注释的段落或块之后。宽屏幕上，注释会移到右侧边距，多个注释之间会计算位置以避免重叠；较小屏幕上则回退到正常的文章流中。

本段提出主要观点。下方的边注在不强制读者离开当前句子的前提下补充了背景信息。

边注在宽屏幕下位于文章边距中。最好简短且聚焦。

第二段有另一个边注，展示了堆叠注释会相互避让，而不是共享同一顶部位置。

如果两条注释会碰撞，靠后的一条会被下推，但仍靠近其锚点段落。

<script data-swup-reload-script type="module" src="/js/components/sidenote.AOLVVU76.js"></script>This paragraph introduces the main claim. The side note below adds context without forcing the reader to leave the sentence they are reading.<side-note>Side notes sit in the article margin on wide screens. They are best kept short and focused.</side-note>This second paragraph has another side note, which demonstrates that stacked notes avoid each other instead of sharing the same top position.<side-note>If two notes would collide, the later one is pushed down while staying close to its anchor paragraph.</side-note>

聊天 💬

当问答格式能让解释更易于理解时，使用聊天组件。适用于调试笔记、AI 辅助解释和需要关注顺序的简短对话。

使用前加载 /js/components/chat.JTADAQ45.js。每个 <chat-message> 应包含 name；avatar 和 timestamp 是可选的，但有助于结构化。添加 is-me 可将自己的消息对齐。每条消息保持简洁，否则聊天布局会比普通段落更难浏览。

布局使用双行网格：头像和头部（名称 + 时间戳）位于第一行，消息气泡位于第二行。移动端气泡会下落到头部下方的全宽行，头像不再占用水平空间。气泡内的行内 <code>、<kbd>、列表和代码块会获得专用样式，不会泄露到 shadow DOM 之外。

大家好！项目进展如何？

进展顺利！刚完成了认证模块。

不错！我们用了 JWT token 加 refresh token 轮换。基本结构如下： auth.refreshToken.rotate()

太棒了！期待看到 PR

<script data-swup-reload-script type="module" src="/js/components/chat.JTADAQ45.js"></script><x-chat>  <chat-message name="Alice" avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=Alice" timestamp="10:30">    Hey everyone! How's the project going?  </chat-message>  <chat-message name="Bob" avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=Bob" timestamp="10:32">    Going well! Just finished the authentication module.  </chat-message>  <chat-message name="Charlie" avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=Charlie" timestamp="10:35">    Nice! We're using JWT tokens with refresh token rotation. Here's the basic structure:    <code>auth.refreshToken.rotate()</code>  </chat-message>  <chat-message name="GnixAij" avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=GnixAij" timestamp="10:38" is-me>    Awesome work! Can't wait to see the PR  </chat-message></x-chat>