云策 WordPress 开发者社区

主题开发文档

特色图像与文章缩略图

查看官方原文 ↗
💡 云策文档标注

概述

特色图像（也称为文章缩略图）是代表文章、页面或自定义文章类型的图像。主题开发可以通过声明支持、设置尺寸和样式化来灵活输出特色图像。

关键要点

  • 特色图像需在主题的 functions.php 文件中使用 add_theme_support('post-thumbnails') 启用支持。
  • 核心函数包括 has_post_thumbnail() 检查图像、the_post_thumbnail() 显示图像、get_the_post_thumbnail() 获取图像等。
  • WordPress 提供默认图像尺寸（如缩略图、中等、大尺寸），并支持通过 add_image_size() 和 set_post_thumbnail_size() 自定义尺寸。
  • 特色图像可通过 CSS 类（如 wp-post-image）进行样式化，并可使用参数添加自定义类。
  • 示例代码展示了如何检查、显示、链接特色图像，以及如何返回图像用于 PHP 代码。

代码示例

// 启用特色图像支持
add_theme_support('post-thumbnails');

// 设置默认特色图像尺寸
set_post_thumbnail_size(150, 150, true);

// 添加自定义图像尺寸
add_image_size('category-thumb', 300, 9999);

// 检查并显示特色图像
if (has_post_thumbnail()) {
    the_post_thumbnail();
}

// 链接特色图像到文章永久链接
if (has_post_thumbnail()) {
    echo '<a href="' . get_permalink() . '">';
    the_post_thumbnail();
    echo '</a>';
}

注意事项

  • 特色图像支持需在主题中明确声明，否则编辑界面不会显示相关选项。
  • 自定义图像尺寸时，注意参数顺序（宽度、高度）和裁剪模式。
  • 在链接特色图像时，避免在同一主题中同时使用多个链接示例，以免冲突。
  • 使用 get_the_post_thumbnail() 可返回图像 HTML 用于变量存储，而非直接输出。
📄 原文内容

Featured images (also sometimes called Post Thumbnails) are images that represent an individual Post, Page, or Custom Post Type. When you create your Theme, you can output the featured image in a number of different ways, on your archive page, in your header, or above a post, for example.

Enabling Support for Featured Image

Themes must declare support for the Featured Image function before the Featured Image interface will appear on the Edit screen. Support is declared by putting the following in your theme’s functions.php file:

add_theme_support( 'post-thumbnails' );
To enable Featured Image only for specific post types, see add_theme_support()

Setting a Featured Image

Once you add support for Featured Images, the Featured Image meta box will be visible on the appropriate content item’s Edit screens. If a user is unable to see it, they can enable it in their screen options.

By default, the Featured Image meta box is displayed in the sidebar of the Edit Post and Edit Page screens.

devhbook-featured_image

Function Reference

<a title="Register a new image size" href="https://developer.wordpress.org/reference/functions/add_image_size/">add_image_size()</a> – Register a new image size.
<a title="Registers an image size for the post thumbnail" href="https://developer.wordpress.org/reference/functions/set_post_thumbnail_size/">set_post_thumbnail_size()</a> – Registers an image size for the post thumbnail.

<a title="Check if post has an image attached" href="https://developer.wordpress.org/reference/functions/has_post_thumbnail/">has_post_thumbnail()</a> – Check if post has an image attached.
<a title="Display Post Thumbnail" href="https://developer.wordpress.org/reference/functions/the_post_thumbnail/">the_post_thumbnail()</a> – Display Post Thumbnail.

<a title="Retrieve Post Thumbnail" href="https://developer.wordpress.org/reference/functions/get_the_post_thumbnail/">get_the_post_thumbnail()</a> – Retrieve Post Thumbnail.
<a title="Retrieve Post Thumbnail ID" href="https://developer.wordpress.org/reference/functions/get_post_thumbnail_id/">get_post_thumbnail_id()</a> – Retrieve Post Thumbnail ID.

Image Sizes

The default image sizes of WordPress are “Thumbnail”, “Medium”, “Large” and “Full Size” (the original size of the image you uploaded). These image sizes can be configured in the WordPress Administration Media panel under >Settings > Media. You can also define your own image size by passing an array with your image dimensions:

the_post_thumbnail(); // Without parameter ->; 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( 'medium_large' ); // Medium-large resolution (default 768px x no height limit max)
the_post_thumbnail( 'large' ); // Large resolution (default 1024px x 1024px max)
the_post_thumbnail( 'full' ); // Original image resolution (unmodified)
the_post_thumbnail( array( 100, 100 ) ); // Other resolutions (height, width)

Add Custom Featured Image Sizes

In addition to defining image sizes individually using

the_post_thumbnail( array(  ,  ) );

you can create custom featured image sizes in your theme’s functions file that can then be called in your theme’s template files.

add_image_size( 'category-thumb', 300, 9999 ); // 300 pixels wide (and unlimited height)

Here is an example of how to create custom Featured Image sizes in your theme’s functions.php file.

if ( function_exists( 'add_theme_support' ) ) {
    add_theme_support( 'post-thumbnails' );
    set_post_thumbnail_size( 150, 150, true ); // default Featured Image dimensions (cropped)

    // additional image sizes
    // delete the next line if you do not need additional image sizes
    add_image_size( 'category-thumb', 300, 9999 ); // 300 pixels wide (and unlimited height)
}

Set the Featured Image Output Size

To be used in the current Theme’s functions.php file.
You can use set_post_thumbnail_size() to set the default Featured Image size by resizing the image proportionally (that is, without distorting it):

set_post_thumbnail_size( 50, 50 ); // 50 pixels wide by 50 pixels tall, resize mode

Set the default Featured Image size by cropping the image (either from the sides, or from the top and bottom):

set_post_thumbnail_size( 50, 50, true ); // 50 pixels wide by 50 pixels tall, crop mode

Styling Featured Images

Featured Images are given a class “wp-post-image”. They 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 Featured Images their own classes by using the attribute parameter in the_post_thumbnail().
Display the Featured Image with a class “alignleft”:

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

Examples

Default Usage

// check if the post or page has a Featured Image assigned to it.
if ( has_post_thumbnail() ) {
    the_post_thumbnail();
}
To return the Featured Image for use in your PHP code instead of displaying it, use: get_the_post_thumbnail()
// check for a Featured Image and then assign it to a PHP variable for later use
if ( has_post_thumbnail() ) {
    $featured_image = get_the_post_thumbnail();
}

Linking to Post Permalink or Larger Image

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(); ?>" alt="<?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:

add_filter( 'post_thumbnail_html', 'my_post_image_html', 10, 3 );
function my_post_image_html( $html, $post_id, $post_image_id ) {

  $html = '<a href="' . get_permalink( $post_id ) . '">' . $html . '</a>';
  return $html;

}

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');
    echo '<a href="' . $large_image_url[0] . '">';
    the_post_thumbnail('thumbnail');
    echo '</a>';
}

Source File

External Resources