云策 WordPress 开发者社区

函数文档

wp_calculate_image_sizes()

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

概述

wp_calculate_image_sizes() 函数用于为图像生成 'sizes' 属性值，支持通过图像尺寸名称或像素数组指定尺寸，并可通过过滤器自定义输出。

关键要点

  • 函数接受 $size 参数，可以是注册的图像尺寸名称或宽度和高度的像素数组
  • 当使用图像尺寸名称时，需要提供 $image_meta 或 $attachment_id 以获取元数据
  • 返回一个用于 'sizes' 属性的字符串或 false（如果宽度无效）
  • 输出可通过 'wp_calculate_image_sizes' 过滤器进行修改

代码示例

function wp_calculate_image_sizes( $size, $image_src = null, $image_meta = null, $attachment_id = 0 ) {
    $width = 0;

    if ( is_array( $size ) ) {
        $width = absint( $size[0] );
    } elseif ( is_string( $size ) ) {
        if ( ! $image_meta && $attachment_id ) {
            $image_meta = wp_get_attachment_metadata( $attachment_id );
        }

        if ( is_array( $image_meta ) ) {
            $size_array = _wp_get_image_size_from_meta( $size, $image_meta );
            if ( $size_array ) {
                $width = absint( $size_array[0] );
            }
        }
    }

    if ( ! $width ) {
        return false;
    }

    $sizes = sprintf( '(max-width: %1$dpx) 100vw, %1$dpx', $width );

    return apply_filters( 'wp_calculate_image_sizes', $sizes, $size, $image_src, $image_meta, $attachment_id );
}

注意事项

  • 函数在 WordPress 4.4.0 版本中引入
  • 相关函数包括 _wp_get_image_size_from_meta()、wp_get_attachment_metadata() 等
  • 被 get_header_image_tag()、wp_image_add_srcset_and_sizes() 等函数调用
📄 原文内容

Creates a ‘sizes’ attribute value for an image.

Parameters

$sizestring|int[]required
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order).
$image_srcstring|nulloptional
The URL to the image file.

Default:null

$image_metaarray|nulloptional
The image meta data as returned by ‘wp_get_attachment_metadata() ‘.

Default:null

$attachment_idintoptional
Image attachment ID. Either $image_meta or $attachment_id is needed when using the image size name as argument for $size. Default 0.

Return

string|false A valid source size value for use in a 'sizes' attribute or false.

Source

function wp_calculate_image_sizes( $size, $image_src = null, $image_meta = null, $attachment_id = 0 ) {
	$width = 0;

	if ( is_array( $size ) ) {
		$width = absint( $size[0] );
	} elseif ( is_string( $size ) ) {
		if ( ! $image_meta && $attachment_id ) {
			$image_meta = wp_get_attachment_metadata( $attachment_id );
		}

		if ( is_array( $image_meta ) ) {
			$size_array = _wp_get_image_size_from_meta( $size, $image_meta );
			if ( $size_array ) {
				$width = absint( $size_array[0] );
			}
		}
	}

	if ( ! $width ) {
		return false;
	}

	// Setup the default 'sizes' attribute.
	$sizes = sprintf( '(max-width: %1$dpx) 100vw, %1$dpx', $width );

	/**
	 * Filters the output of 'wp_calculate_image_sizes()'.
	 *
	 * @since 4.4.0
	 *
	 * @param string       $sizes         A source size value for use in a 'sizes' attribute.
	 * @param string|int[] $size          Requested image size. Can be any registered image size name, or
	 *                                    an array of width and height values in pixels (in that order).
	 * @param string|null  $image_src     The URL to the image file or null.
	 * @param array|null   $image_meta    The image meta data as returned by wp_get_attachment_metadata() or null.
	 * @param int          $attachment_id Image attachment ID of the original image or 0.
	 */
	return apply_filters( 'wp_calculate_image_sizes', $sizes, $size, $image_src, $image_meta, $attachment_id );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_calculate_image_sizes’, string $sizes, string|int[] $size, string|null $image_src, array|null $image_meta, int $attachment_id )

Filters the output of ‘wp_calculate_image_sizes() ’.

Uses Description
_wp_get_image_size_from_meta()wp-includes/media.php

Gets the image size as array from its meta data.
wp_get_attachment_metadata()wp-includes/post.php

Retrieves attachment metadata for attachment ID.
absint()wp-includes/load.php

Converts a value to non-negative integer.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 2 moreShow less

Used by Description
get_header_image_tag()wp-includes/theme.php

Creates image tag markup for a custom header image.
wp_image_add_srcset_and_sizes()wp-includes/media.php

Adds ‘srcset’ and ‘sizes’ attributes to an existing ‘img’ element.
wp_get_attachment_image_sizes()wp-includes/media.php

Retrieves the value for an image attachment’s ‘sizes’ attribute.
wp_get_attachment_image()wp-includes/media.php

Gets an HTML img element representing an image attachment.

Changelog

Version Description
4.4.0 Introduced.