云策 WordPress 开发者社区

函数文档

add_image_size()

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

概述

add_image_size() 函数用于在 WordPress 中注册一个新的图像尺寸，允许开发者自定义图片裁剪和缩放行为。它通过参数控制宽度、高度和裁剪模式，并支持在主题或插件中灵活应用。

关键要点

  • 函数参数：$name（必需，图像尺寸标识符），$width（可选，宽度像素，默认0），$height（可选，高度像素，默认0），$crop（可选，裁剪行为，默认false表示缩放，true表示居中裁剪，数组可指定裁剪位置）。
  • 保留图像尺寸名称：WordPress 内置保留名称如 'thumb'、'thumbnail'、'medium'、'medium_large'、'large'、'post-thumbnail'，其中 'thumb' 和 'thumbnail' 是别名。
  • 裁剪模式示例：使用 false 进行比例缩放，true 进行硬裁剪，数组指定裁剪位置（如 array('left', 'top')）。
  • 使用自定义图像尺寸：可通过 the_post_thumbnail() 在特色图片中应用，使用 image_size_names_choose 钩子在管理后台显示，或通过 wp_get_attachment_image() 在模板中输出。
  • 注意事项：注册新尺寸后需重新生成缩略图（如使用 Regenerate Thumbnails 插件或 WP-CLI 命令）；add_theme_support('post-thumbnails') 必须在 add_image_size() 之前调用；避免使用保留名称；尺寸参数应明确设置，避免默认值0导致问题。

代码示例

// 在主题的 functions.php 中注册自定义图像尺寸
add_action( 'after_setup_theme', 'wpdocs_theme_setup' );
function wpdocs_theme_setup() {
    add_image_size( 'category-thumb', 300 ); // 宽度300像素，高度无限制
    add_image_size( 'homepage-thumb', 220, 180, true ); // 硬裁剪模式
    add_image_size( 'custom-size', 220, 220, array( 'left', 'top' ) ); // 指定裁剪位置
}

注意事项

  • 如果上传图像的尺寸与注册尺寸相同且 crop 为 true，可能不会生成新图像；删除已注册尺寸后，之前上传的图像文件可能不会自动删除。
  • 使用 update_option() 可以修改内置尺寸（如 'thumbnail_size_w'），但需谨慎调用以避免频繁数据库更新。
  • WordPress 5.3 新增了 '1536x1536' 和 '2048x2048' 图像尺寸。
📄 原文内容

Registers a new image size.

Parameters

$namestringrequired
Image size identifier.
$widthintoptional
Image width in pixels. Default 0.
$heightintoptional
Image height in pixels. Default 0.
$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

Reserved Image Size Names

These are the reserved image size names recognized by WordPress: ‘thumb’, ‘thumbnail’, ‘medium’, ‘medium_large’, ‘large’, and ‘post-thumbnail’.

The names “thumb” & “thumbnail” are just aliases- they are exactly the same.

For a detailed explanation and “why”, read further inside the image_downsize() article.

However, if needed, you can always set the options yourself:

update_option( 'thumbnail_size_w', 160 );
update_option( 'thumbnail_size_h', 160 );
update_option( 'thumbnail_crop', 1 );

Crop Mode

Set the image size by resizing the image proportionally (without distorting it): 

add_image_size( 'custom-size', 220, 180 ); // 220 pixels wide by 180 pixels tall, soft proportional crop mode

Set the image size by cropping the image (not showing part of it): 

add_image_size( 'custom-size', 220, 180, true ); // 220 pixels wide by 180 pixels tall, hard crop mode

Set the image size by cropping the image and defining a crop position: 

add_image_size( 'custom-size', 220, 220, array( 'left', 'top' ) ); // Hard crop left top

When setting a crop position, the first value in the array is the x axis crop position, the second is the y axis crop position.

  • x_crop_position accepts ‘left’ ‘center’, or ‘right’.
  • y_crop_position accepts ‘top’, ‘center’, or ‘bottom’.

By default, these values default to ‘center’ when using hard crop mode.

You can find examples of the various crop types here.

Using the New Image Sizes

Now that you’ve defined some custom image sizes, there are a variety of ways that you can use them.
For Featured Images

To use your custom image sizes for a post’s featured image, you can use the_post_thumbnail() in the appropriate theme template file…

Note: To enable featured images the current theme must include add_theme_support( ‘post-thumbnails’ ); in its functions.php file. See also Post Thumbnails.

if ( has_post_thumbnail() ) {
the_post_thumbnail( 'your-custom-size' );
}

For Media Library Images (Admin)

You can also make your custom sizes selectable from your WordPress admin. To do so, you have to use the image_size_names_choose hook to assign them a normal, human-readable name…

add_filter( 'image_size_names_choose', 'my_custom_sizes' );

function my_custom_sizes( $sizes ) {
return array_merge( $sizes, array(
'your-custom-size' => __( 'Your Custom Size Name' ),
) );
}

For General Media (PHP/Templates)

You can output images (by size) directly from the WordPress Media Library using PHP as well. To do this, simply use wp_get_attachment_image().

// Assuming your Media Library image has a post id of 42...
echo wp_get_attachment_image( 42, 'your-custom-size' );

Note: If you just want the image URL instead of a pre-built tag, you can use wp_get_attachment_image_src() instead.

Other Notes:

Using the ‘false’ setting will fail to produce a new image in the upload directory if one of the image dimensions of the uploaded image are equal to the new image size.

If a registered image size is removed from functions.php, then any image uploaded before that point and then deleted from the media library afterwards, does not have those auto-generated sizes deleted too. Only image sizes that exist in functions.php are deleted.

Although height and width are not required parameters, their default values (0) will lead to unwanted behavior, so bear in mind that you should always define them. Use a value of 9999 to define the other dimension as the one to be considered when image resize is executed.

Source

function add_image_size( $name, $width = 0, $height = 0, $crop = false ) {
	global $_wp_additional_image_sizes;

	$_wp_additional_image_sizes[ $name ] = array(
		'width'  => absint( $width ),
		'height' => absint( $height ),
		'crop'   => $crop,
	);
}

View all references View on Trac View on GitHub

Uses Description
absint()wp-includes/load.php

Converts a value to non-negative integer.
Used by Description
_wp_add_additional_image_sizes()wp-includes/media.php

Adds additional default image sub-sizes.
set_post_thumbnail_size()wp-includes/media.php

Registers an image size for the post thumbnail.

Changelog

Version Description
2.9.0 Introduced.

User Contributed Notes

  1. Skip to note 14 content


    Codex


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

    In a theme’s functions.php file. Always use the “after_setup_theme” action hook.

    add_action( 'after_setup_theme', 'wpdocs_theme_setup' );
function wpdocs_theme_setup() {
	add_image_size( 'category-thumb', 300 ); // 300 pixels wide (and unlimited height)
	add_image_size( 'homepage-thumb', 220, 180, true ); // (cropped)
}

  4. Skip to note 17 content


    rtpHarry


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

    The section “Reserved Image Size Names” hints at it but doesn’t explicitly point out that you can also customise the medium and large sizes via code by using these option names:

    medium_size_h: The medium size height.
    medium_size_w: The medium size width.
    large_size_h: The large size height.
    large_size_w: The large size width.

    So for example, to set the large height to 700px you would use this code:

       update_option( 'large_size_h', 700 );

  5. Skip to note 18 content


    pixeline


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

    Note that along thumbnail, medium, large, there is also a size built into wordpress that you can use : full to get the image at its original dimensions.

  7. Skip to note 20 content


    Ivijan-Stefan Stipic


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

    NOTE THIS:

    If add_image_size() still doesn’t work even after regenerating thumbnails, make sure that add_theme_support( 'post-thumbnails' ) is loaded before add_image_size()

    Example:

    function wpse_setup_theme() {
   add_theme_support( 'post-thumbnails' );
   add_image_size( 'team-thumb', 60, 60, true );
}

add_action( 'after_setup_theme', 'wpse_setup_theme' );

  8. Skip to note 21 content


    hongpong


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

    If you upload an image whose dimensions match the add_image_size() when crop is set to true, in the $meta object accessed by the wp_generate_attachment_metadata filter, that matching image size will not be available. Also, image sizes that have larger dimensions than an uploaded photo will not be available either.

    (Thus if you are using a technique to create something like a monochrome derivative image, you won’t be able to get it to work if the uploaded image is exactly the same size as the image size you’re using for your black and white version).

  9. Skip to note 22 content


    Marc Bernard


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

    Default settings for image size (see /wp-admin/includes/schema.php):

    <br />
    'thumbnail_size_w' => 150,<br />
    'thumbnail_size_h' => 150,<br />
    'medium_size_w' => 300,<br />
    'medium_size_h' => 300,<br />
    'medium_large_size_w' => 768,<br />
    'medium_large_size_h' => 0,<br />
    'large_size_w' => 1024,<br />
    'large_size_h' => 1024,<br />

    You can change these option values in WordPress > Admin > Settings > Media (/wp-admin/options-media.php).

    Use get_intermediate_image_sizes() to get the current settings for predefined as well as custom image sizes.

  10. Skip to note 23 content


    slingshotdesign


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

    Note that if you would like your custom image sizes to be available in the admin, for example when choosing an image size for the Media & Text block, use the filter: image_size_names_choose

    Example:

    add_filter( 'image_size_names_choose', 'my_custom_sizes' );
 
function my_custom_sizes( $sizes ) {
    return array_merge( $sizes, array(
        'square_medium' => __( 'Square Medium' ),
        'square_large' => __( 'Square Large' ),
    ) );
}

  12. Skip to note 25 content


    dejudicibus


    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

    Let us suppose that a master theme set in functions.php a size, let us say ‘a_size’. and that the functions.php in a child theme uses again this function to add the same size but with different value. It is not clear from this page if the old size is changed or the call is ignored or forbidden.