云策 WordPress 开发者社区

钩子文档

image_resize_dimensions

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

概述

image_resize_dimensions 过滤器用于在计算图像调整尺寸时进行干预，允许开发者覆盖 WordPress 的默认图像调整行为。通过返回非 null 值，可以短路 image_resize_dimensions() 函数，直接返回自定义尺寸数组。

关键要点

  • 过滤器名称：image_resize_dimensions，用于过滤图像缩略图和替代尺寸的计算过程。
  • 参数：包括原始宽度、高度、目标宽度、高度以及裁剪选项，支持数组指定裁剪位置。
  • 返回值：必须返回与 imagecopyresampled() 参数匹配的数组，或 false 表示不调整，或 null 回退到默认行为。
  • 用途：自 WordPress 3.4 引入，常用于自定义图像裁剪逻辑，如改变裁剪位置。

代码示例

add_filter( 'image_resize_dimensions', 'custom_image_resize_dimensions', 10, 6 );

function custom_image_resize_dimensions( $payload, $orig_w, $orig_h, $dest_w, $dest_h, $crop ){

    // 条件判断是否覆盖默认行为
    if( false )
        return $payload;

    if ( $crop ) {
        // 裁剪逻辑：计算新尺寸和裁剪区域，示例中设置裁剪从顶部开始
        $aspect_ratio = $orig_w / $orig_h;
        $new_w = min($dest_w, $orig_w);
        $new_h = min($dest_h, $orig_h);

        if ( !$new_w ) {
            $new_w = intval($new_h * $aspect_ratio);
        }

        if ( !$new_h ) {
            $new_h = intval($new_w / $aspect_ratio);
        }

        $size_ratio = max($new_w / $orig_w, $new_h / $orig_h);

        $crop_w = round($new_w / $size_ratio);
        $crop_h = round($new_h / $size_ratio);

        $s_x = floor( ($orig_w - $crop_w) / 2 );
        $s_y = 0; // 从顶部裁剪，而非默认中心
    } else {
        // 不裁剪，仅调整尺寸
        $crop_w = $orig_w;
        $crop_h = $orig_h;

        $s_x = 0;
        $s_y = 0;

        list( $new_w, $new_h ) = wp_constrain_dimensions( $orig_w, $orig_h, $dest_w, $dest_h );
    }

    // 如果新尺寸大于或等于原始尺寸，则不调整
    if ( $new_w >= $orig_w && $new_h >= $orig_h )
        return false;

    // 返回 imagecopyresampled() 参数数组
    return array( 0, 0, (int) $s_x, (int) $s_y, (int) $new_w, (int) $new_h, (int) $crop_w, (int) $crop_h );

}

注意事项

  • 过滤器函数必须正确处理所有参数，并返回指定格式的值以避免错误。
  • 在自定义逻辑中，应添加条件判断来决定是否覆盖默认行为，如示例中的 if(false) 部分。
  • 返回的数组需严格匹配 imagecopyresampled() 的参数顺序：dst_x, dst_y, src_x, src_y, dst_w, dst_h, src_w, src_h。
📄 原文内容

Filters whether to preempt calculating the image resize dimensions.

Description

Returning a non-null value from the filter will effectively short-circuit image_resize_dimensions() , returning that value instead.

Parameters

$nullnull|mixed
Whether to preempt output of the resize dimensions.
$orig_wint
Original width in pixels.
$orig_hint
Original height in pixels.
$dest_wint
New width in pixels.
$dest_hint
New height in pixels.
$cropbool|array
Whether to crop image to specified width and height or resize.
An array can specify positioning of the crop area. Default false.

More Information

  • Since version 3.4, the image_resize_dimensions filter is used to filter the thumbnail and alternative sizes dimensions of image assets during resizing operations. This enables the override of WordPress default behavior on image resizing, including the thumbnail cropping.
  • Note that the filter function must return an array matching the parameters to imagecopyresampled(), or false if the resizing is impossible, or should not occur, or null to fallback to WordPress default behavior.

Source

$output = apply_filters( 'image_resize_dimensions', null, $orig_w, $orig_h, $dest_w, $dest_h, $crop );

View all references View on Trac View on GitHub

Used by Description
image_resize_dimensions()wp-includes/media.php

Retrieves calculated resize dimensions for use in WP_Image_Editor.

Changelog

Version Description
3.4.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Steven Lin


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

    Example migrated from Codex:

    This example filters the image resizing dimensions to force WordPress to crop thumbnails by keeping the top of the image, instead of the default center.

    add_filter( 'image_resize_dimensions', 'custom_image_resize_dimensions', 10, 6 );

function custom_image_resize_dimensions( $payload, $orig_w, $orig_h, $dest_w, $dest_h, $crop ){

	// Change this to a conditional that decides whether you 
	// want to override the defaults for this image or not.
	if( false )
		return $payload;

	if ( $crop ) {
		// crop the largest possible portion of the original image that we can size to $dest_w x $dest_h
		$aspect_ratio = $orig_w / $orig_h;
		$new_w = min($dest_w, $orig_w);
		$new_h = min($dest_h, $orig_h);

		if ( !$new_w ) {
			$new_w = intval($new_h * $aspect_ratio);
		}

		if ( !$new_h ) {
			$new_h = intval($new_w / $aspect_ratio);
		}

		$size_ratio = max($new_w / $orig_w, $new_h / $orig_h);

		$crop_w = round($new_w / $size_ratio);
		$crop_h = round($new_h / $size_ratio);

		$s_x = floor( ($orig_w - $crop_w) / 2 );
		$s_y = 0; // [[ formerly ]] ==> floor( ($orig_h - $crop_h) / 2 );
	} else {
		// don't crop, just resize using $dest_w x $dest_h as a maximum bounding box
		$crop_w = $orig_w;
		$crop_h = $orig_h;

		$s_x = 0;
		$s_y = 0;

		list( $new_w, $new_h ) = wp_constrain_dimensions( $orig_w, $orig_h, $dest_w, $dest_h );
	}

	// if the resulting image would be the same size or larger we don't want to resize it
	if ( $new_w >= $orig_w && $new_h >= $orig_h )
		return false;

	// the return array matches the parameters to imagecopyresampled()
	// int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h
	return array( 0, 0, (int) $s_x, (int) $s_y, (int) $new_w, (int) $new_h, (int) $crop_w, (int) $crop_h );

}