图片网格：语法与完整示例

:::grid 是本博客的图片画廊容器指令。它把普通的 Markdown 图片排列成宽高比一致的响应式网格，并自动启用灯箱查看。适合用于文章配图、截图、作品集或小型相册。

同一画廊中的图片共用同一卡片比例。默认情况下，居中裁切会填满每张卡片并保持整行整齐；点击图片会在灯箱中打开完整原图。每个画廊都拥有独立的灯箱分组，不会与文章中的其他图片混在一起。

本文既是功能文档，也是视觉测试页。请在桌面、平板与手机宽度下查看这些示例，然后点击任意图片验证灯箱分组。

最简语法#

把 Markdown 图片直接写在 :::grid 与结束的 ::: 之间：

1
:::grid
2
![图片说明](./image-1.webp)
3

4
![图片说明](./image-2.webp)
5
:::

每张图片必须独占一个段落，图片之间保留空行。画廊中只放图片；段落、列表与代码块请写在容器之外。

下面是最简语法的效果。不带参数时，网格默认使用三列、16/10 比例与 cover。

参数速览#

所有参数都写在起始指令后的花括号中：:::grid{parameter="value"}。

参数	允许取值	默认值	作用
`columns`	`1` 到 `6` 的整数	`3`	桌面端每行的列数。非法值回退为 `3`。
`aspect`	正数比例，如 `16/9`、`3/4`、`1/1`	`16/10`	显示卡片的比例，而非原图比例。
`fit`	`cover`、`contain`	`cover`	图片适配方式。`cover` 裁切填满；`contain` 保留完整图片，可能留下空白。

完整示例：

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

4
![第二张图](./image-2.webp "可选说明文字")
5

6
![第三张图](./image-3.webp "可选说明文字")
7
:::

下面的结果使用上述三列横向语法。请对比卡片比例、列数，以及标题优先于替代文本作为说明文字的方式：

说明文字与替代文本#

图片的替代文本既作为无障碍替代文本，也作为默认说明文字。当图片带有可选的标题时，则改用标题作为说明文字：

1
![用于无障碍的文本](./image.webp "显示在图片下方的说明文字")

同一行中，说明文字会对齐到每张卡片的底部。说明文字换行不会让其他卡片浮动到不同高度。像 3:4、16:9 这样的比例文本可以直接写在正文、标题与替代文本中，无需转义。

本例展示了默认的替代文本说明文字、显式的标题说明文字，以及较长说明文字的底部对齐：

3:4 海报的无障碍描述 — 这是一段较长的说明文字，用于检查每张卡片的说明在换行后是否仍底部对齐

布局与裁切#

桌面端布局使用 columns 指定的列数。低于 768px 时，网格最多使用两列；低于 480px 时，切换为单列。卡片外层固定 aspect 比例并裁掉圆角，图片填满卡片且不带主题默认的图片外边距。

选择 cover：推荐的默认值。图片从中心裁切以填满卡片，让画廊看起来整齐一致。
选择 contain：完整显示原图而不裁切。当图片比例与卡片不同时，主题背景会显现出来；适用于不能被裁切的图片。
若想既保留完整图片又不留空白，请把 aspect 设为接近原图的比例，或让该图片独占一个网格。

下面的示例把同样的竖向图片分别放入 cover 与 contain 的 16/9 卡片中。前者会裁切，后者保留完整图片并留下背景空间。

1
:::grid{columns="3" aspect="16/9" fit="cover"}
2
![图片说明](./image-1.webp "可选说明文字")
3

4
![图片说明](./image-2.webp "可选说明文字")
5
:::
6

7
:::grid{columns="3" aspect="16/9" fit="contain"}
8
![图片说明](./image-1.webp "可选说明文字")
9

10
![图片说明](./image-2.webp "可选说明文字")
11
:::

默认配置#

不带属性时，默认为三列、16/10 比例与 cover 裁切。这三张竖向图片用于验证默认裁切与说明文字。

1
:::grid
2
![图片说明](./image-1.webp)
3

4
![图片说明](./image-2.webp)
5

6
![图片说明](./image-3.webp)
7
:::

三列竖图：3:4#

使用 aspect="3/4" 时，这三张竖向图片会填满比例一致的竖向卡片。若原图比例不同，cover 会从中心裁掉其边缘。

1
:::grid{columns="3" aspect="3/4"}
2
![竖向图片说明](./portrait-1.webp)
3

4
![竖向图片说明](./portrait-2.webp)
5

6
![竖向图片说明](./portrait-3.webp)
7
:::

三列横图：16:9#

这一组展示三列布局中常见的视频封面比例。当横向图片接近卡片比例时，裁切幅度很小。

1
:::grid{columns="3" aspect="16/9"}
2
![横向图片说明](./landscape-1.webp)
3

4
![横向图片说明](./landscape-2.webp)
5

6
![横向图片说明](./landscape-3.webp)
7
:::

两列方图：1:1#

需要更大的预览卡片时，两列效果很好。第三张图片会移到下一行。最后一行保持其网格轨道宽度，而不会拉伸图片去填满整行。

1
:::grid{columns="2" aspect="1/1"}
2
![方图说明](./square-1.webp)
3

4
![方图说明](./square-2.webp)
5

6
![方图说明](./square-3.webp)
7
:::

四列搭配 `contain`#

fit="contain" 不会裁切原图。当图片比例与卡片比例不同时，主题背景会显现出来。这是有意为之，并非布局问题。它同时验证了四列网格与各自独立的灯箱分组不会互相干扰。

1
:::grid{columns="4" aspect="16/9" fit="contain"}
2
![图片说明](./image-1.webp)
3

4
![图片说明](./image-2.webp)
5

6
![图片说明](./image-3.webp)
7
:::

单列细节图#

当图片需要更大的阅读尺寸时，单列是合适的选择。它在桌面、平板与手机上都是一列，原图依然可以在灯箱中查看。

1
:::grid{columns="1" aspect="16/9"}
2
![图片说明](./detail.webp)
3
:::

稀疏的五列一行#

五列用于验证更高的受支持列数。只有三张图片时，最后一行保持左对齐，而不会拉伸图片。

1
:::grid{columns="5" aspect="1/1"}
2
![缩略图说明](./thumb-1.webp)
3

4
![缩略图说明](./thumb-2.webp)
5

6
![缩略图说明](./thumb-3.webp)
7
:::

六列混排#

六列是当前的上限。混排横向与竖向图片可以验证 cover 裁切、窄卡片上的说明文字，以及密集的桌面布局。为了让文章内容便于阅读，通常建议使用两到四列。

1
:::grid{columns="6" aspect="1/1"}
2
![图片说明](./image-1.webp)
3

4
![图片说明](./image-2.webp)
5

6
![图片说明](./image-3.webp)
7

8
![图片说明](./image-4.webp)
9

10
![图片说明](./image-5.webp)
11

12
![图片说明](./image-6.webp)
13
:::

四列方图：1:1#

四张比例相同的方图是典型的四列布局。桌面端一行显示全部四张；平板收缩为两列，手机收缩为一列。

1
:::grid{columns="4" aspect="1/1"}
2
![方图说明](./square-1.webp)
3

4
![方图说明](./square-2.webp)
5

6
![方图说明](./square-3.webp)
7

8
![方图说明](./square-4.webp)
9
:::

六列横图：16:9#

六列横图很适合缩略图预览、作品集与截图索引。即使原图比例略有差异，cover 也能一致地填满每张 16/9 卡片。

1
:::grid{columns="6" aspect="16/9"}
2
![横向图片说明](./landscape-1.webp)
3

4
![横向图片说明](./landscape-2.webp)
5

6
![横向图片说明](./landscape-3.webp)
7

8
![横向图片说明](./landscape-4.webp)
9

10
![横向图片说明](./landscape-5.webp)
11

12
![横向图片说明](./landscape-6.webp)
13
:::

三列竖图：3:4#

这组六张竖向图片展示了人物、海报或手机截图的常见布局。图片排成两行三列，说明文字底部对齐。

1
:::grid{columns="3" aspect="3/4"}
2
![竖向图片说明](./portrait-1.webp)
3

4
![竖向图片说明](./portrait-2.webp)
5

6
![竖向图片说明](./portrait-3.webp)
7

8
![竖向图片说明](./portrait-4.webp)
9

10
![竖向图片说明](./portrait-5.webp)
11

12
![竖向图片说明](./portrait-6.webp)
13
:::

边缘关键内容：`cover` 与灯箱#

这些图片在靠近边缘处包含重要文字或细节。cover 让网格保持整齐，但可能裁掉这些边缘；点击图片即可在灯箱中查看未裁切的原图。对边缘敏感的内容请使用明确的说明文字，或改用下方的 contain。

1
:::grid{columns="3" aspect="16/9" fit="cover"}
2
![边缘关键内容](./critical-1.webp "打开灯箱查看完整的边缘内容")
3

4
![边缘关键内容](./critical-2.webp "打开灯箱查看完整的边缘内容")
5

6
![边缘关键内容](./critical-3.webp "打开灯箱查看完整的边缘内容")
7
:::

极端比例搭配 `contain`#

对于横幅、长截图以及其他极端比例的图片，contain 会完整显示原图。与 cover 不同，它可能留下主题背景空间，但绝不裁切内容。

1
:::grid{columns="3" aspect="16/9" fit="contain"}
2
![完整截图说明](./wide-1.webp)
3

4
![完整截图说明](./wide-2.webp)
5

6
![完整截图说明](./wide-3.webp)
7
:::

透明图片#

透明图片会露出卡片的主题背景。这个单列 contain 示例便于检查透明区域、原图边缘与灯箱行为。

1
:::grid{columns="1" aspect="16/9" fit="contain"}
2
![透明图片说明](./transparent.webp)
3
:::

灯箱导航#

点击网格中的任意图片即可打开 Fancybox 灯箱。在那里可以缩放、旋转、进入全屏、查看缩略图，并使用方向键切换。导航仅限于当前的 :::grid 容器：例如点击「16:9 测试图一」只会打开该小节中的另外两张横向图片。

同一篇文章中的普通 Markdown 图片仍单独处理，不会被加入任何网格画廊。

检查清单#

每个网格中的图片尺寸一致，说明文字位于卡片下方。
图片在悬停时轻微缩放；点击后可以缩放、旋转，并用键盘切换。
点击「16:9 测试图一」后，灯箱只能浏览该小节中的另外两张横向图片。
低于 768px 时，网格最多两列；低于 480px 时为一列。
「四列搭配 contain」中的竖向图片完整可见，留有空白且未被裁切。
五列与六列网格在宽屏上保持指定列数，随后按响应式规则收缩为两列或一列。

蓝色大肥鱼

最简语法#

参数速览#

说明文字与替代文本#

布局与裁切#

默认配置#

三列竖图：3:4#

三列横图：16:9#

两列方图：1:1#

四列搭配 `contain`#

单列细节图#

稀疏的五列一行#

六列混排#

四列方图：1:1#

六列横图：16:9#

三列竖图：3:4#

边缘关键内容：`cover` 与灯箱#

极端比例搭配 `contain`#

透明图片#

灯箱导航#

检查清单#

继续阅读

换条路线

评论

蓝色大肥鱼

最简语法#

参数速览#

说明文字与替代文本#

布局与裁切#

默认配置#

三列竖图：3:4#

三列横图：16:9#

两列方图：1:1#

四列搭配 contain#

单列细节图#

稀疏的五列一行#

六列混排#

四列方图：1:1#

六列横图：16:9#

三列竖图：3:4#

边缘关键内容：cover 与灯箱#

极端比例搭配 contain#

透明图片#

灯箱导航#

检查清单#

分享文章

沿着主题读

换条路线

四列搭配 `contain`#

边缘关键内容：`cover` 与灯箱#

极端比例搭配 `contain`#