2347 字
12 分钟
返回首页
图片网格：语法与完整示例
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 到 63桌面端每行的列数。无效取值会回退到 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")
:::

下面的效果使用了上面的三列横向语法。请对比卡片比例、列数，以及标题优先于 alt 文本作为图注的方式：

参数示例：第一张横向图片
横向图注 1
参数示例：第二张横向图片
横向图注 2
参数示例：第三张横向图片
横向图注 3

图注与 Alt 文本#

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

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

在同一行中，图注对齐每张卡片的底部。过长的图注换行不会导致其它图片浮动到不同高度。比例文字如 3:4 和 16:9 可直接写在正文、标题和 alt 文本中，无需转义。

本示例演示了默认 alt 文本图注、显式标题图注，以及较长图注的底部对齐：

这张图片没有标题，因此 alt 文本即为图注
这张图片没有标题，因此 alt 文本即为图注
带无障碍 alt 文本的第二张方形图片
此标题显示为图注
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://xiaobuhui.xyz/posts/image-grid-demo/
作者
xiaobuhui
发布于
2026-07-13
许可协议
CC BY-NC-SA 4.0

分享文章

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

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取

最后更新于 ，距今已过 92 天

部分内容可能已过时

MDX 与交互组件
Mermaid 图表集
Astro Svelte Tailwind CSS Stylus

© 2026 xiaobuhui. All Rights Reserved.RSSAtomSitemap

Powered by AstroShironeVersion1.0.0