📖 UIkit 与 MDX 组件库终极使用手册

本手册详细介绍了博客中所有自定义组件的通用 API、高级特性及排版技巧。得益于 Astro 的全局组件注入机制，以下所有组件在书写时均不需要任何 import 语句，开箱即用，极其优雅。

⚙️ 1. Markdown 头部配置 (Frontmatter)

在每篇文章的开头，可以通过配置以下 YAML 参数来控制文章的展示效果与元数据：

📋 完整配置示例

title: "UIkit 与 MDX 组件库终极使用手册" # 文章的主标题
published: 2026-06-06                  # 发布时间
description: "这是一份针对 Astro 静态博客的自定义组件库完整使用指南。" # 文章简短摘要
tags: [博客, Astro, MDX]                # 文章标签（数组）
category: 博客搭建                      # 文章所属分类
image: 'https://img.example.com/a.webp' # 文章的封面大图链接
comment: true                           # 是否开启评论 (可选，默认为 true)
customUrl: 'uikit-mdx-guide'            # 自定义文章路径路径 (可选)
author: 一隅之地                         # 文章作者 (可选)
avatar: 'https://img.example.com/v.webp' # 作者头像 (可选)
template: 'style2'                      # 特殊模板布局选项 (可选)
slides:                                 # 幻灯片图集 (可选，用于在文章顶部展示多张轮播图)
  - "https://img.example.com/slide1.webp"
  - "https://img.example.com/slide2.webp"

🚨 2. 警报框 (Alert)

警报框常用于文章中的提示、警告或补充说明，支持极其自由的定制与防溢出保护。

💡 语法与参数说明

type: 决定通知框的颜色类型。可选：primary (蓝), success (绿), warning (黄), danger (红)。
closable: 是否显示关闭按钮，默认为 true。
textColor: 自定义文字颜色，可传入 UIkit 关键字或自定义 HEX/RGB 色值。
fitText: 默认为 true，会自动彻底清除内容段落的上下边距，防止撑破动画高度。
animation: 是否开启关闭动画，默认为 true。
duration: 关闭动画时长（单位毫秒），默认 60。

📝 代码示例

这是一个普通的 primary (蓝色) 提示框。

🎉 恭喜，这是一条 success (绿色) 成功消息！

⚠️ 注意，这是一条 warning (黄色) 警告信息。

💣 危险操作，这是一条 danger (红色) 错误拦截！

这个黄框的字被我强行改成了红色，并且框的宽度刚好包裹住文字。

🔒 这是一个不可关闭的重要通知，字是蓝色的。

静态平滑消失：关掉我时，我会用整整 1 秒钟平滑收缩。

⚡ 瞬间消失：没有任何动画，干脆利落。

🏷️ 3. 标签/徽章 (Label)

标签极其适合用来标注文章的分类、软件版本号或状态。

💡 语法与参数说明

type: 标签颜色。可选：primary, success, warning, danger。
pill: 是否开启胶囊形状（完全圆角）。
class: 允许传入自定义类名（如 Tailwind 类名）透传。

📝 代码示例

我的技术栈包含 Astro 和 Vue 。

Astro 框架目前已更新到 v4.0 当前章节属于高能预警，请仔细阅读。

利用 Tailwind 类名调节：我的博客使用了 Astro 强推构建。

🖱️ 4. 按钮 (Button)

按钮组件通过内置的魔法机制，当检测到传入了 href 且未被禁用时，会自动从 <button> 标签切换为 <a> 链接标签，完美解决了语义冲突。

💡 语法与参数说明

href: 跳转链接，若有此属性则自动变身为链接。
type: 按钮风格。可选：default, primary, secondary, danger, text, link。
size: 尺寸大小。可选：small, large。
fullWidth: 是否撑满整行，默认为 false。
disabled: 是否禁用状态。
target: 链接打开方式，如 _blank。
textColor: 自定义文本颜色（支持 UIkit 关键色及任意 HEX/RGB 颜色）。
align: 对齐方式，可选 left, center, right。会接管并转化为块级元素进行 margin 智能排版。
mt / mb: 上下快捷外边距，传入数字（如 8）会自动乘以 4 像素（32px）。

📝 代码示例

访问我的 GitHub (新窗口打开)

💬 5. 高级提示块 (Admonitions)

独立于 UIkit 自带的 Alert，更适合技术文档风格的提示块，原生支持 5 种预设类型。

💡 语法与参数说明

type: 提示块类型。可选：note (笔记), tip (提示), important (重要), warning (警告), caution (危险)。
title: 自定义提示块标题，若不传则默认展示大写的 type 名称。
color: 高阶核心参数。直接传入自定义色彩（如 #ff00ff），组件会通过 CSS color-mix 机制自动生成 10% 不透明度的配套背景色，并强制应用到边框与标题。

📝 代码示例

注意点
高亮显示用户需要注意的信息，即使是粗略浏览也不应错过。

小技巧
提供可选的提示信息，帮助用户更顺利地完成操作。

重要声明
提供用户必须了解的关键重要信息。

潜在风险
警告内容：涉及潜在风险，需要用户立即注意。

危险操作
危险提醒：此操作可能会带来负面后果，请谨慎操作。

自定义色彩魔法
这个提示块的边框、标题会显示为品红色，而背景色则会自动生成 10% 透明度的柔和色彩！

📁 6. 折叠面板 (Fold)

用于收纳长文本、大段日志或非核心代码块，保持页面清爽度。

💡 语法与参数说明

title: 折叠栏显示的标题文字（默认：“点击展开详细内容”）。
open: 布尔值。若设置为 true，则页面加载时该面板默认就是展开状态。

📝 代码示例

点击查看完整的依赖配置文件 (package.json)

{
  "name": "astro-blog",
  "version": "4.0.0",
  "dependencies": {
    "astro": "^4.0.0"
  }
}

这是一个默认展开的高级选项

在这里配置你的秘钥参数或高级设置项。

🖼️ 7. 全媒体混合网格 (ImageGrid)

极其强悍的多功能弹性媒体网格排版系统，具备智能性能黑魔法。

💡 语法与参数说明

columns: 桌面端展示的列数，默认为 6。
aspectRatio: 统一网格的纵横比（如 16/9, 1/1, 4/3），确保布局绝对对齐。若不传，则高度会弹性撑满。
images: 字符串数组。支持图片直链、视频直链、甚至是 iframe/embed 嵌入代码字符串！
eagerCount: 性能优化核心指标（默认 2）。前 N 个媒体将全速高优先级加载（首屏无缝抢占），其余后面的媒体自动退化为延迟懒加载（Lazy），极其节省网络带宽。

📝 代码示例

⚡ 性能黑魔法释义：

组件会对数组内的内容进行智能探测（正则匹配视频与 iframe）。

对于第三方 Iframe，组件会自动在构建阶段拦截并注入 loading="lazy"，彻底防止外部链接拖慢你的博客核心渲染。

第 1 张图会享有 fetchpriority="high" 与 loading="eager" 优先级，而后方的视频和图片则会自动切换到 preload="metadata" 与 lazy。