ℹ️ 关于内容组件 本文档详细介绍 Clarity 主题中所有自定义内容组件的使用方法。

⚠️ 前置要求 使用这些组件需要安装 Markdown / HTML 内容块 插件，并将组件代码写入 HTML 编辑块中。

Alert 提示框

用于展示重要信息提醒，支持 5 种类型和卡片样式。

基本语法

<c-alert type="类型" title="自定义标题" card>
  提示内容，支持 HTML
</c-alert>

参数说明

类型对照表

使用示例

示例 1：基本提示

<c-alert type="tip">
  这是一条提醒信息，默认绿色样式。
</c-alert>

示例 2：警告信息

<c-alert type="warning">
  <strong>注意：</strong>此操作不可逆，请谨慎执行。
</c-alert>

示例 3：自定义标题

<c-alert type="info" title="小知识">
  Halo 是一款现代化的开源建站工具，致力于提供最佳的博客体验。
</c-alert>

示例 4：带卡片样式的错误提示

<c-alert type="error" title="连接失败" card>
  无法连接到数据库，请检查配置信息：
  <ul>
    <li>确认数据库服务已启动</li>
    <li>检查用户名和密码是否正确</li>
    <li>验证端口号是否开放</li>
  </ul>
</c-alert>

示例 5：问题提示

<c-alert type="question" title="常见问题">
  为什么我的主题样式没有生效？<br>
  答：请尝试清除浏览器缓存后刷新页面。
</c-alert>

Tab 标签页

用于在多个内容面板之间切换展示。

基本语法

<c-tab tabs="标签1,标签2,标签3" center active="1">
  <c-tab-panel>第一个标签的内容</c-tab-panel>
  <c-tab-panel>第二个标签的内容</c-tab-panel>
  <c-tab-panel>第三个标签的内容</c-tab-panel>
</c-tab>

参数说明

使用示例

示例 1：基本用法

<c-tab tabs="JavaScript,Python,Go">
  <c-tab-panel>
    <pre><code>console.log('Hello, World!');</code></pre>
  </c-tab-panel>
  <c-tab-panel>
    <pre><code>print('Hello, World!')</code></pre>
  </c-tab-panel>
  <c-tab-panel>
    <pre><code>fmt.Println("Hello, World!")</code></pre>
  </c-tab-panel>
</c-tab>

示例 2：居中显示，默认第二个

<c-tab tabs="macOS,Windows,Linux" center active="2">
  <c-tab-panel>
    使用 Homebrew 安装：<br>
    <code>brew install halo</code>
  </c-tab-panel>
  <c-tab-panel>
    从官网下载安装包，双击运行。
  </c-tab-panel>
  <c-tab-panel>
    使用包管理器：<br>
    <code>apt install halo</code>
  </c-tab-panel>
</c-tab>

示例 3：复杂内容

<c-tab tabs="功能介绍,安装步骤,常见问题">
  <c-tab-panel>
    <h4>主要功能</h4>
    <ul>
      <li>三栏响应式布局</li>
      <li>深色模式支持</li>
      <li>丰富的内容组件</li>
    </ul>
  </c-tab-panel>
  <c-tab-panel>
    <ol>
      <li>下载主题包</li>
      <li>上传到 Halo 后台</li>
      <li>启用主题并配置</li>
    </ol>
  </c-tab-panel>
  <c-tab-panel>
    <p><strong>Q: 为什么样式不生效？</strong></p>
    <p>A: 请清除浏览器缓存后刷新。</p>
  </c-tab-panel>
</c-tab>

Copy 复制命令

用于展示可一键复制的命令行代码。

基本语法

<c-copy code="要复制的命令" prompt="$"></c-copy>

或行内写法：

<c-copy prompt="#">npm install</c-copy>

参数说明

使用示例

示例 1：基本命令

<c-copy code="npm install"></c-copy>

效果：$ npm install [复制按钮]

示例 2：自定义提示符

<c-copy code="pip install halo" prompt=">"></c-copy>

效果：> pip install halo [复制按钮]

示例 3：无提示符

<c-copy code="https://github.com/acanyo/theme-clarity" prompt=""></c-copy>

效果：https://github.com/acanyo/theme-clarity [复制按钮]

示例 4：多条命令组合

<c-copy code="git clone https://github.com/acanyo/theme-clarity.git"></c-copy>
<c-copy code="cd theme-clarity"></c-copy>
<c-copy code="pnpm install"></c-copy>
<c-copy code="pnpm dev"></c-copy>

示例 5：使用井号提示符（root 权限）

<c-copy code="systemctl restart nginx" prompt="#"></c-copy>

Folding 折叠面板

用于隐藏/展示次要内容，节省页面空间。

基本语法

<c-folding title="点击展开标题" open>
  折叠的内容，支持 HTML
</c-folding>

参数说明

使用示例

示例 1：基本折叠

<c-folding title="查看更多配置选项">
  <ul>
    <li><code>primary_color</code> - 主色调</li>
    <li><code>accent_color</code> - 强调色</li>
    <li><code>font_family</code> - 字体设置</li>
  </ul>
</c-folding>

示例 2：默认展开

<c-folding title="安装要求" open>
  <ul>
    <li>Halo 2.21.0 或更高版本</li>
    <li>现代浏览器（Chrome、Firefox、Safari、Edge）</li>
  </ul>
</c-folding>

示例 3：代码折叠

<c-folding title="查看完整配置文件">
  <pre><code>apiVersion: theme.halo.run/v1alpha1
kind: Theme
metadata:
  name: theme-clarity
spec:
  displayName: Clarity
  version: "1.0.0"</code></pre>
</c-folding>

示例 4：嵌套折叠

<c-folding title="第一章：入门指南">
  <p>这是第一章的内容...</p>
  
  <c-folding title="1.1 安装步骤">
    <ol>
      <li>下载主题</li>
      <li>上传安装</li>
      <li>启用配置</li>
    </ol>
  </c-folding>
</c-folding>

Tip 悬浮提示

为文本添加鼠标悬浮时显示的提示信息。

基本语法

<c-tip tip="提示文本">需要提示的文字</c-tip>

参数说明

使用示例

示例 1：术语解释

<c-tip tip="Cascading Style Sheets，层叠样式表">CSS</c-tip> 是网页样式的基础。

效果：CSS（虚线下划线）悬浮显示 "Cascading Style Sheets，层叠样式表"

示例 2：缩写说明

本主题基于 <c-tip tip="Content Management System，内容管理系统">CMS</c-tip> 平台 Halo 开发。

示例 3：操作提示

点击 <c-tip tip="位于页面右上角">设置按钮</c-tip> 进入配置页面。

示例 4：多个提示

<c-tip tip="Hypertext Markup Language">HTML</c-tip>、
<c-tip tip="Cascading Style Sheets">CSS</c-tip> 和 
<c-tip tip="一种编程语言">JavaScript</c-tip> 是前端三剑客。

Blur 模糊遮罩

隐藏敏感内容，鼠标悬浮时显示。

基本语法

<c-blur>需要模糊的内容</c-blur>

参数说明

无参数，直接包裹需要模糊的内容即可。

使用示例

示例 1：隐藏答案

问题：1 + 1 = ？
答案：<c-blur>2</c-blur>

示例 2：剧透警告

电影结局：<c-blur>主角最终战胜了反派，拯救了世界。</c-blur>

示例 3：敏感信息

默认密码：<c-blur>admin123</c-blur>（请及时修改）

示例 4：配合其他元素

API 密钥：<c-blur><code>sk-xxxxxxxxxxxx</code></c-blur>

Timeline 时间线

用于展示时间轴形式的事件列表。

基本语法

<c-timeline>
  <c-timeline-item time="时间1">事件1的描述</c-timeline-item>
  <c-timeline-item time="时间2">事件2的描述</c-timeline-item>
  <c-timeline-item time="时间3">事件3的描述</c-timeline-item>
</c-timeline>

参数说明

使用示例

示例 1：版本更新记录

<c-timeline>
  <c-timeline-item time="2024-12-01">
    <strong>v1.0.0</strong> - 正式发布
    <ul>
      <li>三栏响应式布局</li>
      <li>深色模式支持</li>
    </ul>
  </c-timeline-item>
  <c-timeline-item time="2024-11-15">
    <strong>v0.9.0</strong> - 公测版本
    <ul>
      <li>修复已知问题</li>
      <li>优化性能</li>
    </ul>
  </c-timeline-item>
  <c-timeline-item time="2024-11-01">
    <strong>v0.1.0</strong> - 内测开始
  </c-timeline-item>
</c-timeline>

示例 2：项目进度

<c-timeline>
  <c-timeline-item time="第一阶段">需求分析与设计</c-timeline-item>
  <c-timeline-item time="第二阶段">功能开发与测试</c-timeline-item>
  <c-timeline-item time="第三阶段">部署上线与运维</c-timeline-item>
</c-timeline>

示例 3：个人经历

<c-timeline>
  <c-timeline-item time="2020年">开始学习前端开发</c-timeline-item>
  <c-timeline-item time="2021年">第一份开发工作</c-timeline-item>
  <c-timeline-item time="2022年">成为全栈工程师</c-timeline-item>
  <c-timeline-item time="2023年">创建个人博客</c-timeline-item>
</c-timeline>

Quote 引用块

用于展示大段引用文本，带装饰性引号图标。

基本语法

<c-quote icon="🎯">
  引用的内容
</c-quote>

参数说明

使用示例

示例 1：名人名言

<c-quote>
  任何足够先进的技术，都与魔法无异。<br>
  <small>—— 亚瑟·克拉克</small>
</c-quote>

示例 2：自定义图标

<c-quote icon="💡">
  好的代码是自解释的，但优秀的代码需要文档。
</c-quote>

示例 3：诗歌引用

<c-quote icon="📜">
  白日依山尽，黄河入海流。<br>
  欲穷千里目，更上一层楼。
</c-quote>

示例 4：产品宣言

<c-quote icon="🚀">
  让每一个人都能轻松拥有自己的博客。
</c-quote>

Chat 聊天对话

用于展示对话形式的内容，如聊天记录、FAQ 等。

基本语法

<c-chat>
  <c-chat-item name="发言人1">消息内容1</c-chat-item>
  <c-chat-item name="发言人2" self>消息内容2</c-chat-item>
</c-chat>

参数说明

使用示例

示例 1：简单对话

<c-chat>
  <c-chat-item name="用户">请问如何安装这个主题？</c-chat-item>
  <c-chat-item name="客服" self>您好！您可以在 Halo 后台的主题管理中上传安装。</c-chat-item>
  <c-chat-item name="用户">好的，谢谢！</c-chat-item>
  <c-chat-item name="客服" self>不客气，有问题随时联系我们~</c-chat-item>
</c-chat>

示例 2：技术讨论

<c-chat>
  <c-chat-item name="小明">这个 Bug 怎么解决啊？</c-chat-item>
  <c-chat-item name="我" self>你试试清除缓存？</c-chat-item>
  <c-chat-item name="小明">试过了，不行...</c-chat-item>
  <c-chat-item name="我" self>那看看控制台有没有报错信息</c-chat-item>
  <c-chat-item name="小明">找到了！是跨域问题！</c-chat-item>
</c-chat>

示例 3：FAQ 形式

<c-chat>
  <c-chat-item name="Q">主题支持哪些浏览器？</c-chat-item>
  <c-chat-item name="A" self>支持所有现代浏览器：Chrome、Firefox、Safari、Edge。</c-chat-item>
  <c-chat-item name="Q">如何开启深色模式？</c-chat-item>
  <c-chat-item name="A" self>点击侧边栏底部的主题切换按钮即可。</c-chat-item>
</c-chat>

Key 键盘按键

用于展示键盘快捷键，自动适配 Mac/Windows 显示。

基本语法

<c-key code="K" cmd></c-key>
<c-key text="自定义文本"></c-key>

参数说明

平台自适应

组件会自动检测用户系统，显示对应的按键符号：

使用示例

示例 1：搜索快捷键

按 <c-key code="K" cmd></c-key> 打开搜索框。

效果（Mac）：按 ⌘K 打开搜索框。 效果（Win）：按 Ctrl+K 打开搜索框。

示例 2：组合键

保存：<c-key code="S" cmd></c-key><br>
撤销：<c-key code="Z" cmd></c-key><br>
全选：<c-key code="A" cmd></c-key>

示例 3：带 Shift 的组合键

新建标签页：<c-key code="T" cmd></c-key><br>
重新打开标签页：<c-key code="T" cmd shift></c-key>

示例 4：自定义文本

按 <c-key text="Enter"></c-key> 确认，<c-key text="Esc"></c-key> 取消。

示例 5：完整快捷键说明

<table>
  <tr><td>打开搜索</td><td><c-key code="K" cmd></c-key></td></tr>
  <tr><td>切换主题</td><td><c-key code="D" cmd shift></c-key></td></tr>
  <tr><td>返回顶部</td><td><c-key text="Home"></c-key></td></tr>
</table>

CardList 卡片列表

将普通列表转换为卡片网格布局。

基本语法

<c-card-list>
  <ul>
    <li>列表项1</li>
    <li>列表项2</li>
    <li>列表项3</li>
  </ul>
</c-card-list>

参数说明

无参数，自动将内部的 <ul> 或 <ol> 转换为卡片网格。

使用示例

示例 1：功能列表

<c-card-list>
  <ul>
    <li>
      <strong>🎨 主题定制</strong><br>
      支持自定义主色调和强调色
    </li>
    <li>
      <strong>🌓 深色模式</strong><br>
      三种模式：浅色/深色/跟随系统
    </li>
    <li>
      <strong>📱 响应式</strong><br>
      完美适配各种设备尺寸
    </li>
    <li>
      <strong>🔍 搜索支持</strong><br>
      集成搜索插件，快捷键唤起
    </li>
  </ul>
</c-card-list>

示例 2：工具推荐

<c-card-list>
  <ul>
    <li>
      <strong>VS Code</strong><br>
      最流行的代码编辑器
    </li>
    <li>
      <strong>Figma</strong><br>
      协作设计工具
    </li>
    <li>
      <strong>Notion</strong><br>
      笔记与项目管理
    </li>
  </ul>
</c-card-list>

Pic 图片展示

带标题的图片展示组件。

基本语法

<c-pic src="图片地址" caption="图片说明" width="宽度" height="高度"></c-pic>

参数说明

使用示例

示例 1：基本图片

<c-pic src="/upload/screenshot.png" caption="主题预览截图"></c-pic>

示例 2：指定尺寸

<c-pic src="/upload/logo.png" caption="Logo 设计" width="200"></c-pic>

示例 3：响应式宽度

<c-pic src="/upload/banner.jpg" caption="首页横幅" width="100%"></c-pic>

示例 4：无说明

<c-pic src="/upload/photo.jpg"></c-pic>

Progress 进度条

用于展示进度或完成度。

基本语法

<c-progress value="当前值" max="最大值" label="标签" color="颜色" show-percent></c-progress>

参数说明

使用示例

示例 1：基本进度

<c-progress value="75"></c-progress>

效果：显示 75% 的进度条

示例 2：带标签

<c-progress value="85" label="项目进度"></c-progress>

示例 3：自定义颜色

<c-progress value="60" label="HTML" color="#e34c26"></c-progress>
<c-progress value="40" label="CSS" color="#264de4"></c-progress>
<c-progress value="50" label="JavaScript" color="#f0db4f"></c-progress>

示例 4：技能展示

<h4>技能水平</h4>
<c-progress value="90" label="Vue.js" color="#42b883"></c-progress>
<c-progress value="85" label="React" color="#61dafb"></c-progress>
<c-progress value="75" label="TypeScript" color="#3178c6"></c-progress>
<c-progress value="70" label="Node.js" color="#339933"></c-progress>

示例 5：自定义最大值

<c-progress value="750" max="1000" label="积分"></c-progress>

示例 6：隐藏百分比

<c-progress value="50" label="加载中" show-percent="false"></c-progress>

EmojiClock 表情时钟

显示当前时间对应的时钟 emoji。

基本语法

<c-emoji-clock></c-emoji-clock>

参数说明

无参数，自动根据当前时间显示对应的时钟表情。

时间对照

• 🕛 12:00 | 🕧 12:30 | 🕐 1:00 | 🕜 1:30 | ...

使用示例

示例 1：文章开头

现在是 <c-emoji-clock></c-emoji-clock>，欢迎阅读本文。

示例 2：签名

文章写于 <c-emoji-clock></c-emoji-clock> 时分。

Split 分栏布局

将内容分成多列显示。

基本语法

<c-split cols="列数" gap="间距">
  <div>第一列内容</div>
  <div>第二列内容</div>
</c-split>

参数说明

使用示例

示例 1：两栏对比

<c-split cols="2">
  <div>
    <h4>优点</h4>
    <ul>
      <li>性能优秀</li>
      <li>体积小巧</li>
      <li>易于上手</li>
    </ul>
  </div>
  <div>
    <h4>缺点</h4>
    <ul>
      <li>生态较小</li>
      <li>社区资源少</li>
    </ul>
  </div>
</c-split>

示例 2：三栏布局

<c-split cols="3" gap="2rem">
  <div>
    <h4>🚀 快速</h4>
    <p>基于现代构建工具</p>
  </div>
  <div>
    <h4>💡 简单</h4>
    <p>开箱即用的配置</p>
  </div>
  <div>
    <h4>🔧 灵活</h4>
    <p>高度可定制化</p>
  </div>
</c-split>

示例 3：响应式自动列数

<c-split cols="250px">
  <div>卡片1</div>
  <div>卡片2</div>
  <div>卡片3</div>
  <div>卡片4</div>
</c-split>

效果：每列最小 250px，根据屏幕宽度自动调整列数

Stepper 步骤条

用于展示流程步骤。

基本语法

<c-stepper>
  <c-step title="步骤标题">步骤详细描述</c-step>
  <c-step title="步骤标题">步骤详细描述</c-step>
</c-stepper>

参数说明

使用示例

示例 1：安装流程

<c-stepper>
  <c-step title="下载主题">
    前往 <a href="https://github.com/acanyo/theme-clarity/releases">Releases</a> 页面下载最新版本的 zip 文件。
  </c-step>
  <c-step title="上传安装">
    登录 Halo 后台，进入「外观」-「主题」，点击「安装主题」，选择本地上传。
  </c-step>
  <c-step title="启用主题">
    安装完成后，点击「启用」按钮激活主题。
  </c-step>
  <c-step title="配置设置">
    进入主题设置，根据需要配置各项参数。
  </c-step>
</c-stepper>

示例 2：开发流程

<c-stepper>
  <c-step title="需求分析">
    与产品经理沟通，明确功能需求和验收标准。
  </c-step>
  <c-step title="技术设计">
    <ul>
      <li>确定技术方案</li>
      <li>编写设计文档</li>
      <li>评审通过</li>
    </ul>
  </c-step>
  <c-step title="编码实现">
    按照设计文档进行功能开发，编写单元测试。
  </c-step>
  <c-step title="测试上线">
    完成集成测试、性能测试，通过后发布上线。
  </c-step>
</c-stepper>

示例 3：使用教程

<c-stepper>
  <c-step title="创建文章">
    在 Halo 后台点击「写文章」
  </c-step>
  <c-step title="插入组件">
    在编辑器中切换到源码模式，粘贴组件代码
  </c-step>
  <c-step title="预览效果">
    切换回可视化模式或点击预览查看效果
  </c-step>
</c-stepper>

Note 便签

仿便利贴样式的内容展示。

基本语法

<c-note color="颜色" rotate>
  便签内容
</c-note>

参数说明

颜色效果

使用示例

示例 1：默认黄色便签

<c-note>
  记得每天写博客！📝
</c-note>

示例 2：绿色便签

<c-note color="green">
  ✅ 任务完成！主题已成功上线。
</c-note>

示例 3：蓝色便签（向右倾斜）

<c-note color="blue" rotate>
  💡 小技巧：按 Ctrl+K 快速搜索
</c-note>

示例 4：粉色便签

<c-note color="pink">
  ⚠️ 重要提醒：<br>
  记得备份数据库！
</c-note>

示例 5：紫色便签

<c-note color="purple">
  🎉 恭喜你完成了所有教程的学习！
</c-note>

示例 6：多个便签组合

<c-split cols="3">
  <c-note color="yellow">待办事项 1</c-note>
  <c-note color="green" rotate>待办事项 2</c-note>
  <c-note color="blue">待办事项 3</c-note>
</c-split>

组合使用示例

示例 1：功能介绍页面

<c-alert type="info" title="关于本主题">
  Clarity 是一款注重阅读体验的三栏博客主题。
</c-alert>

<c-timeline>
  <c-timeline-item time="2024-12">正式发布 v1.0.0</c-timeline-item>
  <c-timeline-item time="2024-11">完成主要功能开发</c-timeline-item>
</c-timeline>

<c-tab tabs="特性,安装,配置">
  <c-tab-panel>
    <c-card-list>
      <ul>
        <li><strong>三栏布局</strong> - 清晰的信息层次</li>
        <li><strong>深色模式</strong> - 保护你的眼睛</li>
      </ul>
    </c-card-list>
  </c-tab-panel>
  <c-tab-panel>
    <c-stepper>
      <c-step title="下载">从 GitHub 下载</c-step>
      <c-step title="安装">上传到 Halo</c-step>
      <c-step title="启用">激活主题</c-step>
    </c-stepper>
  </c-tab-panel>
  <c-tab-panel>
    <c-folding title="查看配置项">
      <c-progress value="100" label="基础配置"></c-progress>
      <c-progress value="80" label="高级配置"></c-progress>
    </c-folding>
  </c-tab-panel>
</c-tab>

示例 2：技术文档

<c-quote icon="📚">
  本文将介绍如何使用 Clarity 主题的内容组件。
</c-quote>

<c-alert type="warning">
  请确保你的 Halo 版本 >= 2.21.0
</c-alert>

<h3>快捷键</h3>
<p>搜索：<c-key code="K" cmd></c-key></p>

<h3>安装命令</h3>
<c-copy code="git clone https://github.com/acanyo/theme-clarity.git"></c-copy>

<h3>目录结构</h3>
<c-folding title="展开查看">
  <pre>theme-clarity/
├── src/
├── templates/
└── theme.yaml</pre>
</c-folding>

注意事项

1. HTML 模式：在 Halo 编辑器中使用这些组件时，需要切换到 HTML/源码模式
2. 空格问题：标签属性值中避免多余空格
3. 嵌套规则：部分组件支持嵌套，但不要过度嵌套
4. 性能考虑：单页面组件数量建议不超过 50 个
5. 兼容性：组件基于 Preact 渲染，需要 JavaScript 支持

问题反馈

如遇问题，请通过以下渠道反馈：

• GitHub Issues: https://github.com/acanyo/theme-clarity/issues
• QQ 群: 766203360