the_post_thumbnail()
云策文档标注
概述
the_post_thumbnail() 是 WordPress 中用于显示文章缩略图的函数，默认使用 'post-thumbnail' 图像尺寸，但可指定其他尺寸或自定义属性。开发者需注意其与 get_the_post_thumbnail() 的区别，并了解如何通过参数控制输出。
关键要点
- 函数默认使用 'post-thumbnail' 尺寸，这是主题支持后注册的特殊尺寸，不同于后台媒体设置中的 'thumbnail'。
- 参数 $size 可接受注册的图像尺寸名称（如 'thumbnail'、'medium'、'large'、'full'）或像素宽高数组。
- 参数 $attr 用于添加 HTML 属性，如 class、title、loading 等，可禁用延迟加载或设置响应式尺寸。
- 输出图像带有类名如 'wp-post-image' 和尺寸相关类（如 'attachment-thumbnail'），便于 CSS 样式化。
- 建议先使用 has_post_thumbnail() 检查缩略图是否存在，再调用此函数以避免错误。
- 相关函数包括 get_the_post_thumbnail()（返回 HTML 而非直接输出）、add_image_size() 和 set_post_thumbnail_size()。
代码示例
// 默认使用 'post-thumbnail' 尺寸
the_post_thumbnail();
// 指定尺寸
the_post_thumbnail('large');
the_post_thumbnail(array(100, 100));
// 添加自定义属性
the_post_thumbnail('post-thumbnail', array('class' => 'alignleft', 'loading' => false));
// 禁用延迟加载（WordPress 5.5+）
the_post_thumbnail('', array('loading' => ''));
// 链接缩略图到文章永久链接（示例）
if (has_post_thumbnail()) {
echo '<a href="' . get_permalink() . '">' . get_the_post_thumbnail() . '</a>';
}注意事项
- 确保主题已通过 add_theme_support('post-thumbnails') 启用缩略图支持。
- 使用 $attr 参数时，数组键值对将映射为 HTML 属性，注意属性名如 'loading' 可控制延迟加载行为。
- 硬裁剪尺寸（如 'thumbnail'）有固定宽高，可能影响响应式设计，可通过过滤器移除 width/height 属性。
- 明确指定图像尺寸有助于改善 CLS（累积布局偏移）分数，提升页面性能。
- 避免在同一主题中混用不同链接方式的示例，以防止冲突。
原文内容
Displays the post thumbnail.
Description
When a theme adds ‘post-thumbnail’ support, a special ‘post-thumbnail’ image size is registered, which differs from the ‘thumbnail’ image size managed via the Settings > Media screen.
When using the_post_thumbnail() or related functions, the ‘post-thumbnail’ image size is used by default, though a different size can be specified instead as needed.
See also
Parameters
$sizestring|int[]optional-
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default
'post-thumbnail'. $attrstring|arrayoptional-
Query string or array of attributes. Default empty.
Source
function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
echo get_the_post_thumbnail( null, $size, $attr );
}
Changelog
| Version | Description |
|---|---|
| 2.9.0 | Introduced. |
Skip to note 14 content
shramee
Post thumbnail sizes:
//Default WordPress the_post_thumbnail( 'thumbnail' ); // Thumbnail (150 x 150 hard cropped) the_post_thumbnail( 'medium' ); // Medium resolution (300 x 300 max height 300px) the_post_thumbnail( 'medium_large' ); // Medium Large (added in WP 4.4) resolution (768 x 0 infinite height) the_post_thumbnail( 'large' ); // Large resolution (1024 x 1024 max height 1024px) the_post_thumbnail( 'full' ); // Full resolution (original size uploaded) //With WooCommerce the_post_thumbnail( 'shop_thumbnail' ); // Shop thumbnail (180 x 180 hard cropped) the_post_thumbnail( 'shop_catalog' ); // Shop catalog (300 x 300 hard cropped) the_post_thumbnail( 'shop_single' ); // Shop single (600 x 600 hard cropped)Hard cropped sizes have fixed height and width
Skip to note 15 content
sheepysheep60
An example of the attr argument using an array can be seen below:
the_post_thumbnail('post-thumbnail', ['class' => 'img-responsive responsive--full', 'title' => 'Feature image']);Using the array’s keys and values to populate different attributes. You can use this to add classes to the post thumbnail.
the_post_thumbnail( 'post-thumbnail', array( 'class' => 'orbit-image', 'loading' => false ) );This will disable Lazy Loading where this post thumbnail is displayed Introduce in WordPress 5.5.Skip to note 16 content
Barbara Ford
Post Thumbnail Linking to the Post Permalink
Note: Don’t use these two examples together in the same Theme.
Example 1. To link Post Thumbnails to the Post Permalink in a specific loop, use the following within your Theme’s template files:
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> </a>Example 2. To link all Post Thumbnails on your website to the Post Permalink, put this in the current Theme’s functions.php file:
/** * Link all post thumbnails to the post permalink. * * @param string $html Post thumbnail HTML. * @param int $post_id Post ID. * @param int $post_image_id Post image ID. * @return string Filtered post image HTML. */ function wpdocs_post_image_html( $html, $post_id, $post_image_id ) { $html = '<a href="' . get_permalink( $post_id ) . '" alt="' . esc_attr( get_the_title( $post_id ) ) . '">' . $html . '</a>'; return $html; } add_filter( 'post_thumbnail_html', 'wpdocs_post_image_html', 10, 3 );Skip to note 17 content
Barbara Ford
Thumbnail Sizes
The default image sizes of WordPress are “thumbnail”, “medium”, “large” and “full” (the size of the image you uploaded). These image sizes can be configured in the WordPress Administration Media panel under Settings > Media. This is how you can use these default sizes with
the_post_thumbnail():the_post_thumbnail(); // without parameter -> 'post-thumbnail' the_post_thumbnail( 'thumbnail' ); // Thumbnail (default 150px x 150px max) the_post_thumbnail( 'medium' ); // Medium resolution (default 300px x 300px max) the_post_thumbnail( 'large' ); // Large resolution (default 640px x 640px max) the_post_thumbnail( 'full' ); // Full resolution (original size uploaded) the_post_thumbnail( array(100, 100) ); // Other resolutionsRegister new image sizes for Post Thumbnails with: add_image_size().
To set the default size for Post Thumbnails see: set_post_thumbnail_size().
Skip to note 18 content
jamesalton
If you’d like to remove the hardcoding of the ‘height’ and ‘width’ attributes on thumbnail images, which will often effect adaptive/responsive/fluid CSS stylesheets, you can add this snippet to your
functions.php,// remove width & height attributes from images // function remove_img_attr ($html) { return preg_replace('/(width|height)="d+"s/', "", $html); } add_filter( 'post_thumbnail_html', 'remove_img_attr' );Skip to note 19 content
jesperstender
If you are worried about the sizes attributes are too big for your usage, you can do something like this :
the_post_thumbnail( 'large', array( 'sizes' => '(max-width:320px) 145px, (max-width:425px) 220px, 500px' ) );The
'sizes'array consists of media queries, so the first parameter is your media query, and the second if what size-width image, should be rendered at that viewportsize. the last parameter is the default size if none of the given media-queries applies.Useful if you use a column-based grid, where you don’t want the image to be rendered 100vw on smaller viewports.
Skip to note 20 content
Barbara Ford
Styling Post Thumbnails
Post Thumbnails are given a class “wp-post-image” and also get a class depending on the size of the thumbnail being displayed. You can style the output with these CSS selectors:
img.wp-post-image img.attachment-thumbnail img.attachment-medium img.attachment-large img.attachment-fullYou can also give Post Thumbnails their own class.
Display the Post Thumbnail with a class “alignleft”:
the_post_thumbnail( 'thumbnail', array( 'class' => 'alignleft' ) );Skip to note 21 content
pablolopezmestre
$attr:$attr = array( 'src' => $src, 'class' => "your-css-class", 'alt' => "your alt text" );Skip to note 22 content
julianoe
Disable lazy-loading on post thumbnail
If you want to prevent WordPress from adding lazy-loading (default behavior since 5.5), use this line where your theme calls the thumbnail:
the_post_thumbnail( '', array( 'loading' => '' ) );Skip to note 23 content
smartyp
You can also explicitly set eager loading for thumbnails (if you don’t want to leave it to the browser to decide):-
the_post_thumbnail( '', array( 'loading' => 'eager' ) );Skip to note 24 content
Barbara Ford
Default Usage
// Check if the post has a Post Thumbnail assigned to it. if ( has_post_thumbnail() ) { the_post_thumbnail(); } the_content();Note: To return the Post Thumbnail for use in your PHP code instead of displaying it, use: get_the_post_thumbnail().
Skip to note 25 content
Anthony Hortin
See Also:
get_the_post_thumbnail()
Skip to note 26 content
Barbara Ford
Post Thumbnail Linking to Large Image Size
This example links to the “large” Post Thumbnail image size and must be used within The Loop.
if ( has_post_thumbnail() ) { $large_image_url = wp_get_attachment_image_src( get_post_thumbnail_id(), 'large' ); if ( ! empty( $large_image_url[0] ) ) { printf( '<a href="%1$s" alt="%2$s">%3$s</a>', esc_url( $large_image_url[0] ), esc_attr( get_the_title_attribute( 'echo=0' ) ), get_the_post_thumbnail() ); } }