Question

the_post_thumbnail( string|array $size = 'post-thumbnail',  string|array $attr = '' )

Display 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 相关函数 functions, the ‘post-thumbnail’ image size is used by default, though a different size can be specified instead as needed.

---

参数

$size

(string|array) (Optional) Image size to use. Accepts any valid image size, or an array of width and height values in pixels (in that order).

Default value: 'post-thumbnail'

$attr

(string|array) (Optional) Query string or array of attributes.

Default value: ''

---

源代码

File: wp-includes/post-thumbnail-template.php

function the_post_thumbnail( $size = 'post-thumbnail', $attr = '' ) {
	echo get_the_post_thumbnail( null, $size, $attr );
}

---

更新日志

Version	description
2.9.0	Introduced.

---

More Information

Usage

the_post_thumbnail( $size, $attr );

---

相关函数

Uses

• wp-includes/post-thumbnail-template.php: get_the_post_thumbnail()

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 16You must log in to vote on the helpfulness of this note Contributed by 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

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.

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:

<?php if ( has_post_thumbnail() ) : ?>
	<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
		<?php the_post_thumbnail(); ?>
	</a>
<?php endif; ?>

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 );

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-full

You can also give Post Thumbnails their own class.
Display the Post Thumbnail with a class “alignleft”:

the_post_thumbnail( 'thumbnail', array( 'class' => 'alignleft' ) ); 

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().

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 resolutions

Register new image sizes for Post Thumbnails with: add_image_size().
To set the default size for Post Thumbnails see: set_post_thumbnail_size().

$attr:

$attr = array(
    'src'   => $src,
    'class' => "your-css-class",
    'alt'   => "your alt text"
);

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()
		);
	}
}

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' );

See Also:
get_the_post_thumbnail()