图片画廊网格：语法与完整示例
:::grid 是博客的图片画廊容器指令。它将普通 Markdown 图片排列成宽高比一致的响应式网格，并自动启用灯箱查看。可用于文章配图、截图、作品集或小型相册。
同一画廊中的图片使用相同的卡片比例。默认采用居中裁剪来填满卡片，让每一行保持整齐；点击图片即可在灯箱中打开完整原图。每个画廊都有独立的灯箱分组，不会与文章中的其他图片混在一起。
本文既是功能文档，也是视觉测试页面。请在桌面、平板和手机宽度下查看示例，再点击任意图片验证灯箱分组。
最简语法
直接在 :::grid 与闭合的 ::: 之间编写 Markdown 图片：
:::grid
:::每张图片必须独占一个段落，图片之间用空行分隔。画廊中只放图片；段落、列表和代码块应放在容器外。
以下是最简语法的效果。不设置参数时，网格默认使用三列、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 保留完整图片，可能留下空白。 |
完整示例：
:::grid{columns="3" aspect="16/9" fit="cover"}
:::以下效果使用上述三列横图语法。可以比较卡片比例、列数，以及标题如何优先于替代文本用作图注：
图注与替代文本
图片的 alt 文本既用作无障碍替代文本，也用作默认图注。如果图片设置了可选标题，则改用标题作为图注：
同一行的图注会对齐到各卡片底部。一条图注换行，不会使其他图注出现高度错位。3:4、16:9 等比例可以直接写在正文、标题和替代文本中，无需转义。
此示例展示默认的替代文本图注、显式标题图注，以及较长图注的底部对齐效果：
布局与裁剪
桌面布局使用 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"}
:::
默认配置
不设置属性时，默认使用三列、16/10 比例和 cover 裁剪。以下三张竖图用于验证默认裁剪和图注。
:::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 图片仍单独处理，不会加入任何网格画廊。
检查清单
- 每个网格中的图片尺寸一致，图注位于卡片下方。
- 悬停时图片略微放大；点击后可以缩放、旋转，并通过键盘切换。
- 点击“16:9 测试图片一”后，灯箱只能浏览该区段中的另外两张横图。
- 宽度低于 768px 时，网格最多使用两列；低于 480px 时使用单列。
- “四列
contain布局”中的竖图完整可见，带有空白且未被裁剪。 - 五列和六列网格在宽屏上保持指定列数，再按响应式规则缩为两列或单列。
分享文章
生成精美分享图或复制链接，与更多人分享本文。
继续阅读
换条路线
从其他文章中稳定抽取
最后更新于 ，距今已过 111 天
部分内容可能已过时
评论