概述

wp_get_missing_image_subsizes() 函数用于比较附件元数据中保存的现有图像子尺寸与当前注册的图像子尺寸，返回缺失的子尺寸信息。它主要用于检测图像附件是否需要生成新的子尺寸，例如在媒体设置更改后。

关键要点

• 函数接收一个附件 ID 作为参数，返回一个关联数组，键为缺失的图像尺寸名称，值为子尺寸信息数组。
• 函数会跳过那些比原始图像尺寸更大的注册子尺寸，确保只处理可生成的尺寸。
• 内部使用 wp_get_registered_image_subsizes() 获取注册尺寸，wp_get_attachment_metadata() 获取元数据，并通过 image_resize_dimensions() 验证尺寸可行性。
• 提供了一个过滤器 wp_get_missing_image_subsizes，允许开发者修改返回的缺失尺寸数组。

代码示例

function wp_get_missing_image_subsizes( $attachment_id ) {
    if ( ! wp_attachment_is_image( $attachment_id ) ) {
        return array();
    }

    $registered_sizes = wp_get_registered_image_subsizes();
    $image_meta       = wp_get_attachment_metadata( $attachment_id );

    // Meta error?
    if ( empty( $image_meta ) ) {
        return $registered_sizes;
    }

    // Use the originally uploaded image dimensions as full_width and full_height.
    if ( ! empty( $image_meta['original_image'] ) ) {
        $image_file = wp_get_original_image_path( $attachment_id );
        $imagesize  = wp_getimagesize( $image_file );
    }

    if ( ! empty( $imagesize ) ) {
        $full_width  = $imagesize[0];
        $full_height = $imagesize[1];
    } else {
        $full_width  = (int) $image_meta['width'];
        $full_height = (int) $image_meta['height'];
    }

    $possible_sizes = array();

    // Skip registered sizes that are too large for the uploaded image.
    foreach ( $registered_sizes as $size_name => $size_data ) {
        if ( image_resize_dimensions( $full_width, $full_height, $size_data['width'], $size_data['height'], $size_data['crop'] ) ) {
            $possible_sizes[ $size_name ] = $size_data;
        }
    }

    if ( empty( $image_meta['sizes'] ) ) {
        $image_meta['sizes'] = array();
    }

    /*
     * Remove sizes that already exist. Only checks for matching "size names".
     * It is possible that the dimensions for a particular size name have changed.
     * For example the user has changed the values on the Settings -> Media screen.
     * However we keep the old sub-sizes with the previous dimensions
     * as the image may have been used in an older post.
     */
    $missing_sizes = array_diff_key( $possible_sizes, $image_meta['sizes'] );

    /**
     * Filters the array of missing image sub-sizes for an uploaded image.
     *
     * @since 5.3.0
     *
     * @param array[] $missing_sizes Associative array of arrays of image sub-size information for
     *                               missing image sizes, keyed by image size name.
     * @param array   $image_meta    The image meta data.
     * @param int     $attachment_id The image attachment post ID.
     */
    return apply_filters( 'wp_get_missing_image_subsizes', $missing_sizes, $image_meta, $attachment_id );
}

注意事项

• 函数仅检查尺寸名称是否匹配，不验证尺寸维度是否一致，因为旧尺寸可能仍被使用。
• 如果附件元数据为空，函数会返回所有注册的尺寸，这可能表示需要重新生成子尺寸。
• 引入于 WordPress 5.3.0 版本，常用于 wp_update_image_subsizes() 和 REST API 控制器中。