目录
- 极简语法
- 参数一览
- 图注与 Alt 文本
- 布局与裁剪
- 默认配置
- 三列竖图：3:4
- 三列横图：16:9
- 两列方形图：1:1
- 四列使用 contain
- 单列细节图
- 稀疏的五列行
- 六列混合图片
- 四列方形图：1:1
- 六列横图：16:9
- 三列竖图：3:4（六张）
- 边缘敏感内容：cover 与灯箱
- 极端比例使用 contain
- 透明图片
- 灯箱导航
- 检查清单
:::grid 是博客的图片画廊容器指令。它把普通 Markdown 图片排列成宽高比一致、响应式的网格，并自动启用灯箱浏览。可用于文章配图、截图、作品集或小相册。
同一画廊内的图片使用相同的卡片比例。默认情况下，居中裁剪会填满每张卡片并保持每行整齐；点击图片会在灯箱中打开完整的原始图片。每个画廊都有独立的灯箱分组，不会与文章中的其他图片混在一起。
本文既是功能文档，也是视觉测试页。请在桌面、平板和手机宽度下查看示例，然后点击任意图片以验证灯箱分组。
极简语法
在 :::grid 与结束标记 ::: 之间直接写入 Markdown 图片：
:::grid
:::每张图片必须独占一个段落，图片之间留空行。画廊内只放图片；段落、列表和代码块请写在容器外面。
下面是极简语法的效果。不带参数时，网格默认使用三列、16/10 比例和 cover 填充。
参数一览
在开头指令后的花括号中写入全部参数：:::grid{parameter="value"}。
| Parameter | Allowed values | Default | 说明 |
|---|---|---|---|
columns | Integers from 1 to 6 | 3 | 桌面端每行的列数。无效值回退为 3。 |
aspect | A positive ratio, such as 16/9, 3/4, or 1/1 | 16/10 | 显示的卡片比例，非原始图片比例。 |
fit | cover, contain | cover | 图片填充方式。cover 裁剪以填满；contain 保留完整图片，可能留有空白。 |
完整示例：
:::grid{columns="3" aspect="16/9" fit="cover"}
:::下面使用上述三列横图语法。请对比卡片比例、列数，以及标题优先于 alt 文本作为图注的效果：
图注与 Alt 文本
图片的 alt 文本既作为无障碍替代文本，也作为默认图注。当图片带有可选的 title 时，则改用 title 作为图注：
在同一行中，图注与每张卡片的底部对齐。图注换行不会让其他卡片浮动到不同高度。像 3:4、16:9 这样的比例文本可直接写在正文、标题和 alt 文本中，无需转义。
本例演示了默认的 alt 文本图注、显式 title 图注，以及较长图注的底部对齐：
布局与裁剪
桌面布局使用 columns 指定的列数。宽度低于 768px 时，网格最多两列；低于 480px 时切换为一列。卡片包装器固定 aspect 比例并裁剪圆角，图片则填满卡片，不带主题默认的外边距。
- 选择
cover：推荐默认值。图片从中心裁剪以填满卡片，使画廊看起来整齐一致。 - 选择
contain：显示完整的原始图片，不裁剪。当比例与卡片不同时，主题背景会透出；适用于不能裁剪的图片。 - 若想完整显示图片且不留空白，可将
aspect设为接近原始图片比例，或将图片单独放入一个网格。
下面两例把相同的竖图放入 16/9 卡片，分别使用 cover 与 contain。前者裁剪，后者保留完整图片并留有背景空间。
:::grid{columns="3" aspect="16/9" fit="cover"}
:::
:::grid{columns="3" aspect="16/9" fit="contain"}
:::
默认配置
Without attributes, the default is three columns, a 16/10 ratio, and cover cropping. 这三张竖图用于验证默认裁剪与图注。
:::grid
:::三列竖图：3:4
使用 aspect="3/4" 时，三张竖图会填满比例一致的纵向卡片。若原始图片比例不同，cover 会从中心裁剪边缘。
:::grid{columns="3" aspect="3/4"}
:::三列横图：16:9
本组在三列布局中演示常见的视频封面比例。当横图比例接近卡片比例时，裁剪最少。
:::grid{columns="3" aspect="16/9"}
:::
两列方形图：1:1
需要较大预览卡片时，两列效果很好。第三张图片会移到下一行。最后一行保持网格轨道宽度，而不会拉伸图片去填满整行。
:::grid{columns="2" aspect="1/1"}
:::
四列使用 contain
fit="contain" 不会裁剪原始图片。当图片比例与卡片比例不同时，主题背景会透出。这是有意为之，并非布局问题。同时也验证四列网格与独立灯箱分组互不干扰。
:::grid{columns="4" aspect="16/9" fit="contain"}
:::单列细节图
当图片需要更大阅读尺寸时，单列是合适的选择。它在桌面、平板和手机上都保持一列，灯箱中仍可查看原始图片。
:::grid{columns="1" aspect="16/9"}:::稀疏的五列行
五列用于验证更高的支持列数。仅有三张图片时，最后一行保持左对齐，而不会拉伸图片。
:::grid{columns="5" aspect="1/1"}
:::六列混合图片
六列是当前的最大值。混合横图与竖图可验证 cover 裁剪、窄卡片上的图注，以及密集的桌面布局。为保证文章可读性，通常更推荐两到四列。
:::grid{columns="6" aspect="1/1"}
:::四列方形图：1:1
四张等比例的方形图是典型的四列布局。桌面端一行显示四张；平板折成两列，手机为一列。
:::grid{columns="4" aspect="1/1"}
:::
六列横图：16:9
六列横图非常适合缩略图预览、作品集和截图索引。即便原始比例略有差异，cover 也能一致地填满每张 16/9 卡片。
:::grid{columns="6" aspect="16/9"}
:::
三列竖图：3:4（六张）
这六张竖图演示了人物、海报或手机截图的常见布局。图片排成两行三列，图注与底部对齐。
:::grid{columns="3" aspect="3/4"}
:::
边缘敏感内容：cover 与灯箱
这些图片在边缘附近含有重要文字或细节。cover 能保持网格整齐，但可能裁掉这些边缘；点击图片可在灯箱中查看未裁剪的原始图。对边缘敏感图片请使用清晰的图注，或改用下面的 contain。
:::grid{columns="3" aspect="16/9" fit="cover"}
:::
极端比例使用 contain
对于横幅、长截图等极端比例的图片，contain 会显示完整的原始图。与 cover 不同，它可能会留出主题背景空间，但绝不会裁剪内容。
:::grid{columns="3" aspect="16/9" fit="contain"}
:::
透明图片
透明图片会透出卡片的主题背景。这个单列 contain 示例便于观察透明区域、原始边缘和灯箱行为。
:::grid{columns="1" aspect="16/9" fit="contain"}:::
灯箱导航
点击网格中任意图片即可打开 Fancybox 灯箱。在其中可缩放、旋转、进入全屏、查看缩略图，并用方向键导航。导航仅限于当前 :::grid 容器：例如点击“16:9 测试图一”只会打开本节另外两张横图。
同一文章中的普通 Markdown 图片仍被单独处理，不会被加入任何网格画廊。
检查清单
- Images in each grid have consistent dimensions, with captions below the cards.
- Images scale slightly on hover; after clicking, they can be zoomed, rotated, and navigated with the keyboard.
- Clicking “16:9 test image one” lets the lightbox browse only the other two landscape images in that section.
- Below 768px, grids use at most two columns; below 480px, they use one column.
- Portrait images in “Four Columns with
contain” are fully visible with empty space and no cropping. - Five- and six-column grids retain their specified column count on wide screens, then collapse to two or one column according to the responsive rules.
If this article helped you, please share it with others!
Some information may be outdated