云策 WordPress 开发者社区

函数文档

set_post_thumbnail_size()

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

概述

set_post_thumbnail_size() 函数用于注册文章缩略图的默认图像尺寸，通过调用 add_image_size() 实现。开发者需在主题的 functions.php 文件中启用 post-thumbnails 支持，并注意该函数不会自动调整现有特色图像。

关键要点

  • 函数注册文章缩略图的默认尺寸，参数包括宽度、高度和裁剪行为。
  • 裁剪参数 $crop 可为 false（缩放）、true（居中裁剪）或数组（指定裁剪位置）。
  • 使用前必须通过 add_theme_support('post-thumbnails') 启用特色图像功能。
  • 现有图像需使用 Regenerate Thumbnails 插件重新生成以适应新尺寸。
  • 函数内部调用 add_image_size('post-thumbnail', $width, $height, $crop)。

代码示例

function wpdocs_setup_theme() {
    add_theme_support('post-thumbnails');
    set_post_thumbnail_size(150, 150);
}
add_action('after_setup_theme', 'wpdocs_setup_theme');

注意事项

在 Gutenberg 编辑器环境中，此函数可能对文章编辑屏幕的缩略图显示无效，需测试兼容性。

📄 原文内容

Registers an image size for the post thumbnail.

Description

See also

Parameters

$widthintrequired
Image width in pixels.
$heightintrequired
Image height in pixels.
$cropbool|arrayoptional
Image cropping behavior. If false, the image will be scaled (default).
If true, image will be cropped to the specified dimensions using center positions.
If an array, the image will be cropped using the array to specify the crop location:

  • 0 string
    The x crop position. Accepts 'left', 'center', or 'right'.
  • 1 string
    The y crop position. Accepts 'top', 'center', or 'bottom'.

Default:false

More Information

  • To register additional image sizes for Featured Images use: add_image_size() .
  • To enable featured images, the current theme must include add_theme_support( 'post-thumbnails' ); in its functions.php file. See also Post Thumbnails.
  • This function will not resize your existing featured images. To regenerate existing images in the new size, use the Regenerate Thumbnails plugin.

Source

function set_post_thumbnail_size( $width = 0, $height = 0, $crop = false ) {
	add_image_size( 'post-thumbnail', $width, $height, $crop );
}

View all references View on Trac View on GitHub

Uses Description
add_image_size()wp-includes/media.php

Registers a new image size.

Changelog

Version Description
2.9.0 Introduced.

User Contributed Notes

  2. Skip to note 5 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Crop Mode
    Set the default Post Thumbnail 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 Post Thumbnail 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

    Set the default Post Thumbnail size by cropping the image from top left:

    set_post_thumbnail_size( 50, 50, array( 'top', 'left')  ); // 50 pixels wide by 50 pixels tall, crop from the top left corner

    Set the default Post Thumbnail size by cropping the image from the center:

    set_post_thumbnail_size( 50, 50, array( 'center', 'center')  ); // 50 pixels wide by 50 pixels tall, crop from the center

    Note:
    This function will not resize your existing featured images. To regenerate existing images in the new size, use the Regenerate Thumbnails plugin.

  3. Skip to note 6 content


    Gabor Lippert


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    I guess this just stopped working in the new Gutenberg editor environment. ¯_(ツ)_/¯

    At least with the below, totally standard usage, the function doesn’t have any effect on the way a post thumbnail gets displayed on a post edit screen.

    function wpdocs_mac_setup_theme() {
	add_theme_support( 'post-thumbnails' );
	set_post_thumbnail_size( 280, 153, false );
}
add_action( 'after_setup_theme', 'wpdocs_mac_setup_theme' );