WordPress 图库短代码完全指南

发布于 作者:

在 WordPress 中发布图片合集，图库（Gallery）功能是直接的选择。它内置于系统之中，通过一个简单的短代码，就能把媒体库中的零散图片组织成整齐的网格展示。无论是摄影作品集、产品展示还是活动回顾，图库都能让内容一目了然。这篇文章会从基础的用法讲起，梳理每个参数的实际作用，并且提供可直接运行的代码示例。如果你是刚接触 WordPress 主题开发，文中的术语解释和注意事项能帮你绕开一些常见的坑。

什么是图库短代码

图库短代码是 WordPress 内置的一项功能，允许你在编辑器或模板文件中插入一个图片网格。它的核心是  这个标记。当你插入一段图库短代码，页面渲染时会被替换成一组带有缩略图和链接的 HTML 结构。

简单的写法是在编辑器中直接输入：

text






这段代码会拉取当前文章或页面“附件”中的所有图片。所谓“附件”，是指通过编辑器上传且关联到该文章的图片。如果你需要指定特定的图片，就必须通过图片的 ID 来明确告知系统。










如何获取图片 ID





在开始构建图库之前，先搞清楚图片 ID 怎么找。这一步经常让新手困惑。





进入后台的“媒体” -> “媒体库”，以列表视图浏览。点击任意一张图片的“编辑”链接，浏览器地址栏会显示类似这样的 URL：





text





https://你的域名/wp-admin/post.php?post=123&action=edit





其中 post=123 中的 123 就是这张图片的 ID。把多个 ID 用逗号分隔，就可以组合成自定义图库。





text















在模板文件中使用短代码





如果你在开发主题，需要在 PHP 模板中直接输出图库，可以使用 do_shortcode() 函数。这个函数会解析短代码并返回对应的 HTML。





php





<?php echo do_shortcode( '' ); ?>





若需要带上参数，直接拼接在短代码字符串里即可：





php





<?php echo do_shortcode( '' ); ?>










控制图片的排序方式





图库默认按 menu_order 排序，也就是你在“编辑文章”页面的图库选项卡中拖拽调整的顺序。通过 orderby 参数可以更改排序规则。





可用的排序值包括：





    

  • menu_order —— 默认，按自定义顺序
    • 




  • title —— 按图片标题字母排序
    • 




  • post_date —— 按上传时间排序
    • 




  • rand —— 随机打乱
    • 




  • ID —— 按图片 ID 排序
    • 






结合 order 参数（ASC 升序或 DESC 降序）可以精确控制显示顺序。例如，按 ID 降序排列：





text










在模板中调用时：





php





<?php echo do_shortcode( '' ); ?>










调整列数





columns 参数控制每行显示的图片数量，默认是 3 列。如果想让图片更紧凑或更舒展，可以直接修改这个值：





text










注意，列数设置并不总是精确生效，具体效果取决于主题样式表对图库类的定义。有些主题会通过 CSS 覆盖默认的列宽，终呈现可能略有差异。





模板调用方式：





php





<?php echo do_shortcode( '' ); ?>










指定图片来源





前面提到过 ids 参数可以精确选择图片。实际上还有另一种方式：通过 id 参数指定父级文章 ID，从而拉取该文章关联的所有附件。





text










这里的 123 是文章 ID，而非图片 ID。这种写法在需要复用某篇文章附件的场景下比较方便。










缩略图尺寸





size 参数控制缩略图的显示尺寸，有效值包括 thumbnail、medium、large、full，以及通过 add_image_size() 自定义的尺寸名称。默认是 thumbnail。





text










这些尺寸的具体像素值可以在“设置” -> “媒体”中调整。修改后，已生成的缩略图需要借助 Regenerate Thumbnails 这类插件重新生成才能生效。





模板调用示例：





php





<?php echo do_shortcode( '' ); ?>










自定义 HTML 标签





出于语义化或样式定制的需求，你可以修改图库外层、图片容器和标题容器的 HTML 标签：





    

  • itemtag —— 每个图片项的外层标签，默认 dl
    • 




  • icontag —— 图片图标（缩略图）的包裹标签，默认 dt
    • 




  • captiontag —— 图片说明文字的包裹标签，默认 dd
    • 






例如改成更现代的 div + span + p 结构：





text










这样做的好处是方便配合 CSS 框架进行样式定制。但修改之后，主题的样式表需要相应地调整选择器。










链接行为





link 参数决定点击缩略图后跳转到哪里：





    

  • file —— 直接链接到原始图片文件（通常用于查看大图）
    • 




  • none —— 不添加任何链接
    • 




  • 默认情况下链接到附件的独立页面（attachment page）
    • 






对于图片展示型站点，link="file" 是常用的选择：





text















包含与排除特定图片





当你需要从媒体库中挑选一部分图片展示，或者排除某些图片时，include 和 exclude 参数就派上了用场。





仅显示指定图片：





text










排除某些图片，其余全部显示：





text










注意：include 和 exclude 不能同时使用，系统会忽略后一个参数。










从文章内容中过滤短代码





在某些高级场景中，你可能需要在输出文章内容之前对短代码进行预处理。the_content 过滤器可以做到这一点：





php





<?php
$gallery_shortcode = '';
echo apply_filters( 'the_content', $gallery_shortcode );
?>





这段代码通常用于自定义循环中，其中 $post->post_parent 指向当前文章关联的父级 ID。实际开发中，更常见的是直接使用 the_content() 函数，它会自动应用所有过滤器。










总结





WordPress 自带的图库短代码虽然看似简单，但覆盖了从图片选取、排序、布局到链接行为的大部分日常需求。掌握 ids、columns、size、orderby、link 这几个核心参数，基本就能应对 80% 以上的场景。当你需要更复杂的展示效果（比如灯箱、瀑布流、懒加载），可以在此基础上结合 JavaScript 库进行增强，或者直接使用专门的图库插件。但无论如何，原生短代码始终是一个轻量、可靠且无需额外依赖的起点。





需要注意的是，图库的终样式高度依赖当前主题的 CSS 定义。如果你发现图库显示异常，首先检查主题的样式表是否对 .gallery、.gallery-item、.gallery-icon 等类进行了合理的样式声明。