big_image_size_threshold
云策文档标注
概述
big_image_size_threshold 是一个 WordPress 过滤器，用于控制“大图像”的缩放阈值。当上传的原始图像宽度或高度超过此阈值时，WordPress 会自动将其缩放至阈值大小，并作为最大可用尺寸。
关键要点
- 过滤器用于设置图像缩放的最大宽度和高度阈值，默认值为 2560 像素。
- 通过返回 false 可以完全禁用图像缩放功能。
- 过滤器接收参数包括阈值、图像尺寸数组、文件路径和附件 ID。
- PNG 图像默认被排除在缩放之外，以避免文件大小问题。
代码示例
// 完全禁用图像大小阈值
add_filter( 'big_image_size_threshold', '__return_false' );
// 将图像大小阈值增加到 4000px
function mynamespace_big_image_size_threshold( $threshold ) {
return 4000; // 新阈值
}
add_filter('big_image_size_threshold', 'mynamespace_big_image_size_threshold', 999, 1);注意事项
- 使用 __return_false 作为回调函数时，应将其作为字符串传递，因为 add_filter() 期望一个可调用对象。
- 在某些情况下，可能需要指定较低的优先级（如 100）以确保过滤器正确工作。
原文内容
Filters the “BIG image” threshold value.
Description
If the original image width or height is above the threshold, it will be scaled down. The threshold is used as max width and max height. The scaled down image will be used as the largest available size, including the _wp_attached_file post meta value.
Returning false from the filter callback will disable the scaling.
Parameters
$thresholdint-
The threshold value in pixels. Default 2560.
$imagesizearray-
Indexed array of the image width and height in pixels.
0intThe image width.1intThe image height.
$filestring-
Full path to the uploaded image file.
$attachment_idint-
Attachment post ID.
Source
$threshold = (int) apply_filters( 'big_image_size_threshold', 2560, $imagesize, $file, $attachment_id );
Changelog
| Version | Description |
|---|---|
| 5.3.0 | Introduced. |
Skip to note 3 content
squarecandy
Usage examples:
// completely disable image size threshold add_filter( 'big_image_size_threshold', '__return_false' ); // increase the image size threshold to 4000px function mynamespace_big_image_size_threshold( $threshold ) { return 4000; // new threshold } add_filter('big_image_size_threshold', 'mynamespace_big_image_size_threshold', 999, 1);__return_falseis a function name, andadd_filter()is a function that expects a callable (in this case, a function name) for the second parameter, so it is correct to provide__return_falseas a string.// Do not scale (large) PNG images. // May result in sub-sizes that have greater file size than the original. if ('image/png' !== $imagesize['mime']) { /* filter applied here */ }Skip to note 4 content
cazuma
// as of 2025, I had to specify lower priority for return false version to work
add_filter( 'big_image_size_threshold', '__return_false', 100, 1 );