图片画廊网格：语法与完整实例指南

:::grid 是本博客专门用于渲染图片画廊的容器指令。它能够将普通的 Markdown 图片排列为宽高比统一、响应式自适应的优雅图片网格，并自动开启大图灯箱预览（Lightbox）。非常适合用于文章插图展示、屏幕截图集锦、作品集或小型相册展示。

同一个画廊网格内的所有图片共享统一的卡片比例。默认采用居中裁剪方式填满卡片，让每行排版显得整齐划一；点击任意图片即可在弹出层灯箱中查看完整无损的大图。每个画廊网格均为独立的灯箱组，不会与其他画廊网格混淆。

本文既是画廊指令的功能使用说明书，也是视觉效果测试页。您可以在桌面端、平板端和移动端切换查看响应式布局，点击任意图片验证灯箱分组效果。

最简基础语法#

只需在 :::grid 和闭合 ::: 之间直接编写标准的 Markdown 图片语法即可：

:::grid
![图片描述](./image-1.webp)

![图片描述](./image-2.webp)
:::

注意事项：每张图片必须单独占一行，且图片之间需留有空行。画廊容器内请仅包含图片元素，段落、列表或代码块等请写在容器外部。

以下是最简语法的实际渲染效果。在未指定参数时，网格默认采用 3 列排版、16/10 宽高比以及 cover 居中裁剪填充：

参数配置一览#

所有参数均以属性键值对的形式写在开始指令后的花括号中：:::grid{parameter="value"}。

完整配置示例：

:::grid{columns="3" aspect="16/9" fit="cover"}
![第一张图片](./image-1.webp "可选说明标题")

![第二张图片](./image-2.webp "可选说明标题")

![第三张图片](./image-3.webp "Optional caption")
:::

下方实际效果应用了上方的 3 列横屏参数配置。注意观察卡片宽高比例、列数排布，以及 title 属性如何优先作为下方展示标题：

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

图片标题与 Alt 无障碍文本#

图片语法中的 alt 文本既用作无障碍阅读替代文本，也用作默认的下方展示标题。当您显式指定了 title 时，title 文本将优先作为下方展示标题：

![无障碍替代文本](./image.webp "显示在图片下方的标题说明")

在同一行中，所有标题均在卡片底部自动对齐。换行的较长标题不会导致相邻卡片的底边产生落差。诸如 3:4 与 16:9 这类的比例文本可在正文和标题中直接书写，无需特殊转义。

:::grid{columns="3" aspect="1/1"}

:::

布局与裁剪细节#

桌面端排版将严格遵循 columns 设置的列数；屏幕宽度小于 768px 时，网格自动降级为最多 2 列；小于 480px 时降级为 1 列。卡片外壳固定 aspect 比例并应用圆角剪裁，图片自动充满卡片。

• 选择 cover：推荐的默认方式。图片从中心裁切充满卡片，使画廊保持整洁一致的视觉美感。
• Choose contain：完整显示原图不裁切。当图片比例与卡片不一致时，会露出主题背景色；适合展示不能被裁切细节的图片。

下面展示将相同的竖屏图片分别置于 cover 和 contain 模式下的 16<9> 卡片中：

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

:::grid{columns="3" aspect="16/9" fit="contain"}

:::

默认缺省配置示例#

如果不提供属性参数，默认效果为 3 列、16/10 比例以及 cover 裁切。

三列竖屏展示：3<4> 比例#

设置 aspect="3/4" 时，竖屏图片填充在纵向卡片中，非常适合用于展示人物海报或移动端截图。

:::grid{columns="3" aspect="3/4"}

:::

三列横屏展示：16<9> 比例#

标准的视频封面比例，适合展示横版风景或桌面截图。

:::grid{columns="3" aspect="16/9"}

:::

两列正方形网格：1<1> 比例#

当需要更大的预览大图时，2 列网格是不二之选。末尾多出的图片会自动换行并保持原列宽，不会被强制拉伸。

:::grid{columns="2" aspect="1/1"}

:::

单列大图展示#

1 列适合需要大图阅读体验的场合，在电脑端、平板和手机端均保持单列全宽展示。

:::grid{columns="1" aspect="16/9"} :::

四列正方形网格：1<1>#

四张正方形图片排布为标准的 4 列画廊。桌面端一排四图，平板降级为 2 列，手机端自动降级为 1 列。

:::grid{columns="4" aspect="1/1"}

:::

灯箱联动与交互#

点击网格中的任意图片均可触发 Fancybox 弹出层大图灯箱。在灯箱中，您可以自由放大、旋转、进入全屏、切换缩略图，或通过键盘方向键进行无缝上下张翻页。翻页浏览仅在当前 :::grid 画廊组内生效，不会与页面上的其他画廊或独立 Markdown 图片混淆。