2586 字
13 分钟
图片画廊网格：语法与完整示例
2026-07-13示例Markdown图库图片网格演示

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

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

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

最简语法#

直接在 :::grid 与结束标记 ::: 之间编写 Markdown 图片：

:::grid
![Image description](./image-1.webp)


![Image description](./image-2.webp)
:::

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

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

最简语法结果：第一张图片
最简语法结果：第一张图片
最简语法结果：第二张图片
最简语法结果：第二张图片

参数速览#

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

参数允许的值默认值用途
columns从 1 到 6 的整数3桌面端每行的列数。无效值会回退为 3。
aspect正的比值，例如 16/9、3/4 或 1/116/10展示用的卡片比例，而非原始图片比例。
fitcover、containcover图片适配模式。cover 裁剪填满；contain 保留完整图片，可能留出空白。

完整示例：

:::grid{columns="3" aspect="16/9" fit="cover"}
![First image](./image-1.webp "Optional caption")


![Second image](./image-2.webp "Optional caption")


![Third image](./image-3.webp "Optional caption")
:::

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

参数示例：第一张横向图片
横向说明文字 1
参数示例：第二张横向图片
横向说明文字 2
参数示例：第三张横向图片
横向说明文字 3

说明文字与替代文本#

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

![Text used for accessibility](./image.webp "Caption shown below the image")

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

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

这张图片没有标题，因此其替代文本就是说明文字
这张图片没有标题，因此其替代文本就是说明文字
第二张带无障碍替代文本的方形图片
这个标题会显示为说明文字
一张 3:4 海报的无障碍描述
这是一段较长的说明文字，用于检查每条说明文字换行时是否仍然与其卡片底部对齐

布局与裁剪#

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

  • 选择 cover：推荐的默认值。图片从中心裁剪以填满卡片，让画廊看起来整齐一致。
  • 选择 contain：完整显示原始图片，不做裁剪。当图片比例与卡片不同时，会露出主题背景；适合不可裁剪的图片。
  • 若要既保留完整图片又不出空白，可将 aspect 设置为接近原始图片的比例，或把图片单独放进一个网格。

下面的示例将同一组竖版图片放入 16/9 卡片，分别使用 cover 和 contain。前者会裁剪图片；后者保留完整图片并留出背景空间。

:::grid{columns="3" aspect="16/9" fit="cover"}
![Image description](./image-1.webp "Optional caption")


![Image description](./image-2.webp "Optional caption")
:::


:::grid{columns="3" aspect="16/9" fit="contain"}
![Image description](./image-1.webp "Optional caption")


![Image description](./image-2.webp "Optional caption")
:::
第一个 cover 结果
Cover：居中裁剪
第二个 cover 结果
Cover：填满卡片
第三个 cover 结果
Cover：更一致的布局
第一个 contain 结果
Contain：保留完整原图
第二个 contain 结果
Contain：可能出现空白
第三个 contain 结果
Contain：适合边缘细节

默认配置#

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

:::grid
![Image description](./image-1.webp)


![Image description](./image-2.webp)


![Image description](./image-3.webp)
:::
默认配置：竖版图片一
默认配置：竖版图片一
默认配置：竖版图片二
默认配置：竖版图片二
默认配置：竖版图片三
默认配置：竖版图片三

三列竖版：3:4#

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

:::grid{columns="3" aspect="3/4"}
![Portrait image description](./portrait-1.webp)


![Portrait image description](./portrait-2.webp)


![Portrait image description](./portrait-3.webp)
:::
3:4 测试图片一
竖版 1
3:4 测试图片二
竖版 2
3:4 测试图片三
竖版 3

三列横版：16:9#

这一组演示了三列布局下常见的视频封面比例。当横向图片接近卡片比例时，裁剪量极小。

:::grid{columns="3" aspect="16/9"}
![Landscape image description](./landscape-1.webp)


![Landscape image description](./landscape-2.webp)


![Landscape image description](./landscape-3.webp)
:::
16:9 测试图片一
16:9 测试图片一
16:9 测试图片二
16:9 测试图片二
16:9 测试图片三
16:9 测试图片三

两列方形：1:1#

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

:::grid{columns="2" aspect="1/1"}
![Square image description](./square-1.webp)


![Square image description](./square-2.webp)


![Square image description](./square-3.webp)
:::
1:1 测试图片一
1:1 测试图片一
1:1 测试图片二
1:1 测试图片二
1:1 测试图片三
1:1 测试图片三

带 contain 的四列布局#

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

:::grid{columns="4" aspect="16/9" fit="contain"}
![Image description](./image-1.webp)


![Image description](./image-2.webp)


![Image description](./image-3.webp)
:::
Contain：竖版图片一
Contain：竖版图片一
Contain：竖版图片二
Contain：竖版图片二
Contain：竖版图片三
Contain：竖版图片三

单列细节图#

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

:::grid{columns="1" aspect="16/9"}
![Image description](./detail.webp)
:::
单列测试图片
单列测试图片

稀疏的五列布局#

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

:::grid{columns="5" aspect="1/1"}
![Thumbnail description](./thumb-1.webp)


![Thumbnail description](./thumb-2.webp)


![Thumbnail description](./thumb-3.webp)
:::
五列测试图片一
五列测试图片一
五列测试图片二
五列测试图片二
五列测试图片三
五列测试图片三

六列混合图片#

六列是目前支持的最大值。混合横向与竖向图片可以验证 cover 裁剪、窄卡片上的说明文字以及紧凑的桌面布局。对于以可读性为先的文章内容，通常两到四列更合适。

:::grid{columns="6" aspect="1/1"}
![Image description](./image-1.webp)


![Image description](./image-2.webp)


![Image description](./image-3.webp)


![Image description](./image-4.webp)


![Image description](./image-5.webp)


![Image description](./image-6.webp)
:::
六列测试图片一
六列测试图片一
六列测试图片二
六列测试图片二
六列测试图片三
六列测试图片三
六列测试图片四
六列测试图片四
六列测试图片五
六列测试图片五
六列测试图片六
六列测试图片六

四列方形：1:1#

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

:::grid{columns="4" aspect="1/1"}
![Square image description](./square-1.webp)


![Square image description](./square-2.webp)


![Square image description](./square-3.webp)


![Square image description](./square-4.webp)
:::
方形图片一
方形图片一
方形图片二
方形图片二
方形图片三
方形图片三
方形图片四
方形图片四

六列横版：16:9#

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

:::grid{columns="6" aspect="16/9"}
![Landscape image description](./landscape-1.webp)


![Landscape image description](./landscape-2.webp)


![Landscape image description](./landscape-3.webp)


![Landscape image description](./landscape-4.webp)


![Landscape image description](./landscape-5.webp)


![Landscape image description](./landscape-6.webp)
:::
横向图片一
横向图片一
横向图片二
横向图片二
横向图片三
横向图片三
横向图片四
横向图片四
横向图片五
横向图片五
横向图片六
横向图片六

三列竖版：3:4#

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

:::grid{columns="3" aspect="3/4"}
![Portrait image description](./portrait-1.webp)


![Portrait image description](./portrait-2.webp)


![Portrait image description](./portrait-3.webp)


![Portrait image description](./portrait-4.webp)


![Portrait image description](./portrait-5.webp)


![Portrait image description](./portrait-6.webp)
:::
竖版图片一
竖版图片一
竖版图片二
竖版图片二
竖版图片三
竖版图片三
竖版图片四
竖版图片四
竖版图片五
竖版图片五
竖版图片六
竖版图片六

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

这些图片的边缘附近含有重要的文字或细节。cover 能保持网格整齐，但可能裁掉这些边缘；点击图片即可在灯箱中查看未裁剪的原图。对边缘敏感的图片请使用清晰的说明文字，或使用下面的 contain。

:::grid{columns="3" aspect="16/9" fit="cover"}
![Edge-critical content](./critical-1.webp "Open the lightbox to view the complete edge content")


![Edge-critical content](./critical-2.webp "Open the lightbox to view the complete edge content")


![Edge-critical content](./critical-3.webp "Open the lightbox to view the complete edge content")
:::
第一张边缘关键图片
打开灯箱查看完整的边缘内容
第二张边缘关键图片
打开灯箱查看完整的边缘内容
第三张边缘关键图片
打开灯箱查看完整的边缘内容

带 contain 的极端比例#

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

:::grid{columns="3" aspect="16/9" fit="contain"}
![Complete screenshot description](./wide-1.webp)


![Complete screenshot description](./wide-2.webp)


![Complete screenshot description](./wide-3.webp)
:::
极端比例图片一
极端比例图片一
极端比例图片二
极端比例图片二
极端比例图片三
极端比例图片三

透明图片#

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

:::grid{columns="1" aspect="16/9" fit="contain"}
![Transparent image description](./transparent.webp)
:::
透明背景测试图片
透明背景测试图片

灯箱导航#

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

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

检查清单#

  1. 每个网格中的图片尺寸一致，说明文字位于卡片下方。
  2. 悬停时图片会轻微放大；点击后可以缩放、旋转并使用键盘导航。
  3. 点击“16:9 测试图片一”时，灯箱只能浏览该小节中的另外两张横向图片。
  4. 低于 768px 时，网格最多使用两列；低于 480px 时使用一列。
  5. “带 contain 的四列布局”中的竖版图片完整可见，留有空白且未被裁剪。
  6. 五列和六列网格在宽屏上保持指定的列数，然后按响应式规则折叠为两列或一列。
图片画廊网格：语法与完整示例
https://shirone.mysqil.com/posts/image-grid-demo/
作者
Shirone
发布于
2026-07-13
许可协议
CC BY-NC-SA 4.0

分享文章

生成精美分享图或复制链接，与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取

MDX 集成与 M3E 原子组件
Mermaid 图表画廊