当前浏览:首页 / WordPress函数 / add_image_size()

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

注册新的图像尺寸

addmore...

imagemore...

size


参数

$name

(string) (必填) 图像尺寸标识符。

$width

(int) (可选) 图像宽度(像素)。默认值为0。

$height

(int) (可选) 图像高度(像素)。默认值为0。

$crop

(bool|array) (可选) 图像裁剪行为。如果为false,将缩放图像(默认),如果为true,将使用中心位置将图像裁剪到指定尺寸。如果是数组,则将使用数组来指定裁剪位置来裁剪图像。数组值的格式必须为:array( x_crop_position, y_crop_position ),其中:

  • x_crop_position 接受:'left', 'center', 或 'right'
  • y_crop_position 接受:'top', 'center', 或 'bottom'

默认值: false


说明

保留的图像尺寸名称

这些是WordPress识别的保留图像尺寸名称:“thumb”、“thumbnail”、“medium”、“medium_large”、“large”和“post thumbnail”。

名称“thumb”和“thumbnail”只是不同别名 - 它们完全相同。

有关详细解释和“原因”,请进一步阅读image_downsize()文章。

但是,如果需要,您始终可以自己设置选项:

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

裁剪模式

通过按比例调整图像大小(不失真)来设置图像尺寸:

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

通过裁剪图像(不显示图像的一部分)来设置图像尺寸:

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

通过裁剪图像并定义裁剪位置来设置图像尺寸:

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

设置裁剪位置时,数组中的第一个值是x轴裁剪位置,第二个值是y轴裁剪位置

  • x_crop_position 接受:'left', 'center', 或 'right'
  • y_crop_position 接受:'top', 'center', 或 'bottom'

默认情况下,使用硬裁剪模式时,这些值默认为“center”。


使用新的图像尺寸

现在,您已经定义了一些自定义图像尺寸,有多种方法可以使用它们
用于特色图片

要为文章的特色图像使用自定义图像尺寸,可以在相应的主题模板文件中使用the_post_thumbnail()

注意:要启用特色图像,当前主题的functions.php文件必须包含add_theme_support( ‘post-thumbnails’ );  另请参见文章缩略图。

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

用于媒体库图像(管理界面)

您还可以从WordPress管理界面处选择自定义尺寸。为此,您必须使用image_size_names_choose钩子为它们指定一个正常的、人类可读的名称…

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

一般媒体(PHP/模板)

您也可以使用PHP直接从WordPress媒体库输出图像(按尺寸)。为此,只需使用wp_get_attachment_image()

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

注意:如果您只需要图像URL而不是预构建的标签,可以使用wp_get_attachment_image_src()


其他注意事项

如果上传图片的其中一个尺寸等于新图片的尺寸,使用'false'设置将无法在上传目录中生成新图片。

如果一个注册的图片尺寸从 functions.php 中被删除,那么在这之前上传的任何图片,在之后从媒体库中删除时,这些自动生成的尺寸也不会被删除。只有存在于functions.php中的图片尺寸会被删除。

虽然高度和宽度不是必须的参数,但它们的默认值(0)会导致不必要的行为,所以请记住,你应该总是定义它们。使用9999的值来定义另一个尺寸,作为执行图像调整时要考虑的尺寸。



源码

查看源码 官方文档


更新日志

版本描述
2.9.0开始引入

使用示例

  • 示例1

    在主题的functions.php文件中。始终使用“after_setup_theme”动作钩子。

    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)
    }
    
  • 示例2

    除了重新生成缩略图插件外,还有一个WP-CLI命令:wp media regenerate。详见https://developer.wordpress.org/cli/commands/media/regenerate/wp help regenerate media

  • 示例3

    添加新尺寸后,Wordpress必须重新生成图像。

    最好的插件:https://wordpress.org/plugins/regenerate-thumbnails/

  • 示例4

    “保留的图像尺寸名称”一节对此进行了提示,但没有明确指出您也可以通过代码使用这些选项名称来定制中大尺寸:

    medium_size_h:中等大小的高度
    medium_size_w:中等尺寸宽度
    large_size_h:大尺寸高度
    large_size_w:大尺寸宽度。

    例如,要将 large 高度设置为700px,您可以使用以下代码:

       update_option( 'large_size_h', 700 );
    
  • 示例5
  • 示例6

    请注意,除了thumbnailmediumlarge,wordpress中还内置了一个尺寸,您可以使用full以获得原始尺寸的图像。

  • 示例7

    如果裁剪设置为true,上传的图片尺寸与add_image_size()相匹配,则在wp_generate_attachment_metadata过滤器访问的$meta对象中,该匹配的图片尺寸将不可用。另外,尺寸大于上传照片的图像尺寸也将不可用。

    (因此,如果您使用一种技术来创建类似单色衍生图像的内容,那么如果上传的图像大小与您用于黑白版本的图像大小完全相同,您将无法使其起效)。

  • 示例8

    图像大小的默认设置(请参阅/wp admin/includes/schema.php):

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

    您可以在WordPress > 管理 > 设置 > 媒体 中更改这些选项值(/wp admin/options Media.php)。

    使用get_intermediate_image_sizes()获取预定义和自定义图像尺寸的当前设置。

  • 示例9

    请注意:

    如果在重新生成缩略图后add_image_size()仍然不起效,请确保在add_image_size()之前加载add_theme_support( 'post-thumbnails' )

    例子:

    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' );
  • 示例10

    请注意,如果您希望您的自定义图像尺寸在管理界面中可用,例如在为媒体选择图像尺寸时,使用过滤器:image_size_names_choose

    例子:

    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' ),
        ) );
    }
    
  • 示例11

    让我们假设一个主题在 functions.php 中设置了一个尺寸,比方说'a_size',然后其子主题的 functions.php 再次使用这个函数来添加相同的尺寸,但数值不同。从这个页面上看,并不清楚旧的尺寸是否被改变,还是调用被忽略或被禁止了。

  • 示例12

    从WordPress 5.3开始,增加了两种额外的图片尺寸:
    1536×1536
    2048×2048
    这些也是他们的名字
    有关其他信息,查看 wp-includes/media.php