Question

add_image_size( string $name,  int $width,  int $height,  bool|array $crop = false )

注册一个新的图片裁切尺寸。

---

description

生成的图像是否的裁剪取决于 $crop 的值：

1. 如果是false，也就是默认值，图片不会被裁切
2. 如果是一个类似 array( x_crop_position, y_crop_position ) 的数组：
   • x_crop_position 参数可选 ‘left’ ‘center’, or ‘right’.
   • y_crop_position 参数可选 ‘top’, ‘center’, or ‘bottom’。 将裁剪到指定区域内的指定尺寸。
3. 如果为 true，则使用中心位置将图像裁剪到指定的尺寸。

---

参数

$name

(string)
(Required)
图像大小标识符。

$width

(int)
(Required)
图片的宽度。

$height

(int)
(Required)
图片的高度

$crop

(bool|array)
(Optional)
是否将图像裁剪到指定的宽度和高度或调整大小。传递一个数组可以指定一个区域来裁切。默认值为 false。

---

源代码

File: wp-includes/media.php

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

---

更新日志

Version	description
2.9.0	Introduced.

---

更多信息

保留图像大小名称

‘thumb’, ‘thumbnail’, ‘medium’, ‘large’, ‘post-thumbnail’

图片大小名称 “thumb” & “thumbnail” 只是别名，它们完全相同。

但是，如果需要，您可以自己设置选项：

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

---

裁切模块

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.

---

其他

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. As mentioned before, use a value of 9999 to define the other dimension as the one to be considered when image resize is executed.

---

相关函数

Uses

• wp-includes/functions.php:absint()

---

Used By

• wp-includes/media.php:set_post_thumbnail_size()

---

User Contributed Notes

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

After you have add new sizes Wordpress has to regenerate the images.

Best plugin to do that: https://wordpress.org/plugins/regenerate-thumbnails/

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

相关函数

remove_image_size()
has_post_thumbnail()
the_post_thumbnail()
get_post_thumbnail_id()
get_the_post_thumbnail()
set_post_thumbnail_size()

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.

In addition to the Regenerate Thumbnails plugins, there’s also a WP-CLI command: wp media regenerate. See https://wp-cli.org/commands/media/regenerate/ or wp help regenerate media for details.

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

Just to second @Raja’s comment from august, the code sample has some entities that are not being converted.
=> should be => for the image_size_names_choose filter.

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

The cropping behavior coded as 2) in description, https://developer.wordpress.org/reference/functions/add_image_size/#description, is *not* currently supported. Please see the ticket at https://core.trac.wordpress.org/ticket/40370 for more information.