wp_constrain_dimensions()
云策文档标注
概述
wp_constrain_dimensions() 函数用于计算图像在约束最大宽度和高度后的新尺寸，适用于图像缩放场景。它基于当前尺寸和最大限制，通过比例计算确保图像不超出指定范围，并处理边缘情况如最小尺寸和舍入问题。
关键要点
- 函数接受当前宽度、高度以及可选的最大宽度和高度参数，返回一个包含新宽度和高度的数组。
- 如果最大宽度或高度未设置（为0），则不约束对应维度，直接返回原尺寸。
- 通过计算宽度和高度比例，选择较小或较大比例以避免溢出，确保新尺寸在约束范围内。
- 处理舍入问题：当新尺寸比最大限制小1像素时，自动向上取整至最大限制。
- 提供 wp_constrain_dimensions 过滤器，允许开发者自定义约束后的尺寸。
代码示例
function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) {
// 核心逻辑：计算比例并返回新尺寸
if ( ! $max_width && ! $max_height ) {
return array( $current_width, $current_height );
}
// ... 比例计算和约束处理 ...
return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height );
}注意事项
- 函数确保新尺寸至少为1像素，避免因过小尺寸导致零值。
- 递归调用时，约束结果应保持一致，函数通过舍入调整来优化这一点。
- 自WordPress 2.5.0版本引入，是图像处理相关函数的基础组件。
原文内容
Calculates the new dimensions for a down-sampled image.
Description
If either width or height are empty, no constraint is applied on that dimension.
Parameters
$current_widthintrequired-
Current width of the image.
$current_heightintrequired-
Current height of the image.
$max_widthintoptional-
Max width in pixels to constrain to. Default 0.
$max_heightintoptional-
Max height in pixels to constrain to. Default 0.
Source
function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) {
if ( ! $max_width && ! $max_height ) {
return array( $current_width, $current_height );
}
$width_ratio = 1.0;
$height_ratio = 1.0;
$did_width = false;
$did_height = false;
if ( $max_width > 0 && $current_width > 0 && $current_width > $max_width ) {
$width_ratio = $max_width / $current_width;
$did_width = true;
}
if ( $max_height > 0 && $current_height > 0 && $current_height > $max_height ) {
$height_ratio = $max_height / $current_height;
$did_height = true;
}
// Calculate the larger/smaller ratios.
$smaller_ratio = min( $width_ratio, $height_ratio );
$larger_ratio = max( $width_ratio, $height_ratio );
if ( (int) round( $current_width * $larger_ratio ) > $max_width || (int) round( $current_height * $larger_ratio ) > $max_height ) {
// The larger ratio is too big. It would result in an overflow.
$ratio = $smaller_ratio;
} else {
// The larger ratio fits, and is likely to be a more "snug" fit.
$ratio = $larger_ratio;
}
// Very small dimensions may result in 0, 1 should be the minimum.
$w = max( 1, (int) round( $current_width * $ratio ) );
$h = max( 1, (int) round( $current_height * $ratio ) );
/*
* Sometimes, due to rounding, we'll end up with a result like this:
* 465x700 in a 177x177 box is 117x176... a pixel short.
* We also have issues with recursive calls resulting in an ever-changing result.
* Constraining to the result of a constraint should yield the original result.
* Thus we look for dimensions that are one pixel shy of the max value and bump them up.
*/
// Note: $did_width means it is possible $smaller_ratio == $width_ratio.
if ( $did_width && $w === $max_width - 1 ) {
$w = $max_width; // Round it up.
}
// Note: $did_height means it is possible $smaller_ratio == $height_ratio.
if ( $did_height && $h === $max_height - 1 ) {
$h = $max_height; // Round it up.
}
/**
* Filters dimensions to constrain down-sampled images to.
*
* @since 4.1.0
*
* @param int[] $dimensions {
* An array of width and height values.
*
* @type int $0 The width in pixels.
* @type int $1 The height in pixels.
* }
* @param int $current_width The current width of the image.
* @param int $current_height The current height of the image.
* @param int $max_width The maximum width permitted.
* @param int $max_height The maximum height permitted.
*/
return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height );
}
Hooks
- apply_filters( ‘wp_constrain_dimensions’, int[] $dimensions, int $current_width, int $current_height, int $max_width, int $max_height )
-
Filters dimensions to constrain down-sampled images to.
Changelog
| Version | Description |
|---|---|
| 2.5.0 | Introduced. |