本文集中展示 XPro 主题内置的全部短代码组件：按钮、选项卡、折叠框、提示框、时间线、进度条、图片网格/相册、下载卡片、GitHub 卡片、哔哩哔哩卡片、音乐卡片、文章引用卡片。
目录
- 按钮
[abutton]/[button] - 选项卡
[tabs]/[tab] - 折叠框
[collapse] - 提示框
[alert] - 时间线
[timeline]/[event] - 进度条
[progress] - 图片网格 / 相册
[gallery] - 下载卡片
[download] - GitHub 卡片
[github] - 哔哩哔哩卡片
[bilibili] - 音乐卡片
[music] - 文章 / 页面引用卡片
[post]/[page]
按钮 [abutton] / [button]
介绍：两种按钮组件。[abutton] 渲染为 <a> 链接，适合跳转页面；[button] 渲染为 <button>，适合执行脚本。按钮内容支持内嵌 SVG 图标。
| 组件 | 渲染标签 | 参数 | 类型 | 说明 |
|---|---|---|---|---|
abutton | <a> | url | 字符串 | 链接地址，必填，省略时默认为 # |
button | <button> | onclick | 字符串 | 点击执行的 JavaScript 表达式 |
| 共用 | - | theme | 枚举 | primary 默认主题色、secondary 次要色、ghost 幽灵透明、danger 危险红，默认 primary |
| 共用 | - | size | 枚举 | sm 小、lg 大，省略为默认尺寸 |
语法示例：
[abutton url="https://baidu.com" theme="primary"]<svg>自定义图标</svg>前往查看[/abutton]
[abutton url="/about.html" theme="ghost" size="sm"]关于本站[/abutton]
[button theme="danger" onclick="alert('弹窗提示')"]点击这里[/button]实例展示：
前往查看关于本站
选项卡 [tabs] / [tab]
介绍：选项卡容器，支持点击与键盘方向键切换，支持任意层级嵌套，各层级切换互不影响。状态同步到 aria-selected。
| 组件 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
tabs | （无） | - | - | 容器标签，包裹多个 [tab]，支持嵌套 |
tab | title | 字符串 | 是 | 选项卡标题，显示在标签栏上 |
tab | active | 布尔 | 否 | 标记该面板为初始激活；不指定则默认激活第一个 |
语法示例：
[tabs]
[tab title="概览"]这是「概览」面板。[/tab]
[tab title="更新" active]这是「更新」面板，默认激活。[/tab]
[/tabs]实例展示（嵌套选项卡）：
折叠框 [collapse]
介绍：轻量折叠面板，可多个同时展开互不干扰，默认收起。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
title | 字符串 | 是 | 折叠面板标题，显示在可点击的标题栏上 |
open | 布尔 | 否 | 标记后初始渲染默认展开；不标记则默认折叠 |
语法示例：
[collapse title="默认展开的折叠框" open]默认展开的内容[/collapse]
[collapse title="关闭状态"]默认收起的内容[/collapse]实例展示：
提示框 [alert]
介绍：带图标的提示框，四种语义类型，warning / danger 类型使用 role="alert"。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | 枚举 | 否 | info 信息、success 成功、warning 警告、danger 危险，默认 info |
title | 字符串 | 否 | 提示标题，省略则仅显示内容 |
语法示例：
[alert type="info" title="提示"]这是信息提示。[/alert]
[alert type="success" title="成功"]操作已完成。[/alert]
[alert type="warning" title="警告"]请注意备份数据。[/alert]
[alert type="danger" title="错误"]操作失败，请重试。[/alert]实例展示：
提示
这是信息提示。
成功
操作已完成。
警告
请注意备份数据。
错误
操作失败，请重试。
时间线 [timeline] / [event]
介绍：垂直时间线，按事件节点展示更新记录或发展历程。
| 组件 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
timeline | （无） | - | - | 容器标签，包裹多个 [event] |
event | date | 字符串 | 否 | 事件日期，显示在时间节点上方 |
event | title | 字符串 | 否 | 事件标题，加粗显示 |
event | （内容） | 文本 | 否 | 事件描述，可省略 |
语法示例：
[timeline]
[event date="2026-06-24" title="v2.1"]新增相册折叠样式[/event]
[event date="2026-01-24" title="v1.1"]完善移动端适配[/event]
[/timeline]实例展示：
v2.1
新增相册折叠样式v1.1
完善移动端适配
进度条 [progress]
介绍：带文字标签与数值的进度条，无需闭合标签。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
label | 字符串 | 否 | 左侧文字标签 |
value | 数字 | 是 | 进度值 0 ~ 100，超出范围自动截断 |
color | 枚举 | 否 | success 绿色、warning 橙色、danger 红色，省略为主题色 |
语法示例：
[progress label="主题开发进度" value="85" color="success"]
[progress label="文档完善度" value="60" color="warning"]实例展示：
图片网格 / 相册 [gallery]
介绍：图片容器。指定 visible 且小于图片总数时渲染为「相册折叠」样式（超出部分折叠并显示剩余数量蒙层，点击查看全部）；否则渲染为普通网格。所有图片自动接入 Fancybox 灯箱预览。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
cols | 枚举 | 否 | 列数 2 / 3 / 4，默认 3 |
visible | 数字 | 否 | 网格中直接显示的图片张数；小于图片总数时启用相册折叠 |
ar | 字符串 | 否 | 图片宽高比，格式 宽/高，如 9/16、16/9、1/1、1.5/2 |
| （内容） | 图片 | - | 使用 Markdown 图片语法逐行列出 |
语法示例：
[gallery cols="4" ar="9/16"]
![图1][1]
![图2][2]
![图3][3]
![图4][4]
[/gallery]实例展示：网格（4 列、9/16 竖图）
实例展示：相册（仅展示 3 张，其余折叠）
下载卡片 [download]
介绍：文件下载卡片，支持显示文件名、大小、来源与提取码；填写 code 后自动生成「复制提取码」按钮。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | 字符串 | 否 | 文件名，默认「文件」 |
url | 字符串 | 否 | 下载地址，默认 # |
size | 字符串 | 否 | 文件大小，如 12.5MB |
source | 字符串 | 否 | 来源名称，默认「网盘」 |
code | 字符串 | 否 | 提取码，填写后显示并可一键复制 |
语法示例：
[download name="主题安装包.zip" url="https://astrsource.com" size="12.5MB" source="百度网盘" code="xpro"]实例展示：
GitHub 卡片 [github]
介绍：展示指定仓库的名称、描述、语言与 Star / Fork 数据。数据通过本地代理请求 GitHub API，缓存 10 小时；首次访问显示骨架屏后自动填充。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
repo | 字符串 | 是 | 仓库标识，格式 owner/repo |
语法示例：
[github repo="typecho/typecho"]
[github repo="astrsource/XPro-For-Typecho_Theme"]实例展示：
A PHP Blogging Platform. Simple and Powerful.
Typecho X/Twitter 风格主题
哔哩哔哩卡片 [bilibili]
介绍：展示 B 站视频封面、标题、UP 主与播放/弹幕/点赞/投币数据，点击跳转视频页。数据缓存 10 小时，首次访问显示骨架屏。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
bv | 字符串 | 二选一 | BV 号，如 BV1xx411c7Xg |
aid | 字符串 | 二选一 | AV 号，如 16 |
语法示例：
[bilibili bv="BV1xx411c7Xg"]
[bilibili aid="16"]实例展示：
音乐卡片 [music]
介绍：音乐播放卡片，支持两种用法：通过网易云 / QQ 音乐 / 酷狗歌曲 ID 自动解析，或手动指定音频地址。
| 用法 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 平台歌曲 | wy | 字符串 | 按需 | 网易云歌曲 ID |
| 平台歌曲 | tx | 字符串 | 按需 | QQ 音乐歌曲 ID |
| 平台歌曲 | kg | 字符串 | 按需 | 酷狗歌曲 ID |
| 手动音频 | title | 字符串 | 是 | 歌名 |
| 手动音频 | url | 字符串 | 是 | 音频地址，支持相对路径（自动补全站点地址） |
| 手动音频 | artist | 字符串 | 否 | 歌手名 |
| 手动音频 | pic | 字符串 | 否 | 封面图地址，省略时使用默认占位图 |
语法示例：
[music wy="29562701"]
[music tx="0017RuqE1UYQjk"]
[music kg="11F90A8E71E3241C6735FEAB801FB44D"]
[music title="示例歌曲" url="/usr/uploads/audio/demo.mp3" artist="示例歌手" pic="/usr/uploads/2026/08/demo.png"]实例展示：
文章 / 页面引用卡片 [post] / [page]
介绍：引用站内文章或独立页面，渲染为带封面、类型、日期、标题与摘要的引用卡片。
| 组件 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
post | cid | 数字 | 是 | 文章内容 ID（cid） |
page | cid | 数字 | 是 | 独立页面内容 ID（cid） |
语法示例：
[post cid="1"]
[page cid="2"]实例展示：
常见问题
Q：短代码在代码块中被意外解析？
A：不会。所有 ` 代码块中的内容会被保护，短代码会原样显示，方便撰写教程。
Q：为什么 [github]、[bilibili]、[music] 首次打开是空白骨架？
A：这些组件通过 API 异步获取数据并缓存 10 小时，首次访问先显示骨架屏，随后自动填充，属正常现象。
Q：选项卡支持嵌套吗？
A：支持任意层级嵌套，各层级独立切换，互不影响。
评论（3）
—— DeepSeek酱