云策 WordPress 开发者社区

函数文档

wp_maybe_add_fetchpriority_high_attr()

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

概述

wp_maybe_add_fetchpriority_high_attr() 函数用于决定是否为元素添加 fetchpriority='high' 属性，以优化加载性能。它主要针对图片元素，并考虑懒加载、像素阈值等条件。

关键要点

  • 函数检查标签名是否为 'img'，仅支持图片元素。
  • 如果元素已有 fetchpriority 属性，仅当值为 'high' 时更新 loading_attrs。
  • 懒加载（loading='lazy'）与 fetchpriority='high' 互斥，不能同时应用。
  • 使用 wp_high_priority_element_flag() 检查元素是否为高优先级候选。
  • 通过 wp_min_priority_img_pixels 过滤器可调整图片像素阈值，默认 50000 平方像素。
  • 函数返回更新后的 loading_attrs 数组。

代码示例

function wp_maybe_add_fetchpriority_high_attr( $loading_attrs, $tag_name, $attr ) {
    // For now, adding `fetchpriority="high"` is only supported for images.
    if ( 'img' !== $tag_name ) {
        return $loading_attrs;
    }

    if ( isset( $attr['fetchpriority'] ) ) {
        if ( 'high' === $attr['fetchpriority'] ) {
            $loading_attrs['fetchpriority'] = 'high';
            wp_high_priority_element_flag( false );
        }
        return $loading_attrs;
    }

    // Lazy-loading and `fetchpriority="high"` are mutually exclusive.
    if ( isset( $loading_attrs['loading'] ) && 'lazy' === $loading_attrs['loading'] ) {
        return $loading_attrs;
    }

    if ( ! wp_high_priority_element_flag() ) {
        return $loading_attrs;
    }

    $wp_min_priority_img_pixels = apply_filters( 'wp_min_priority_img_pixels', 50000 );
    // 像素阈值检查逻辑（原文未完整，此处省略）
    return $loading_attrs;
}

注意事项

  • 此函数自 WordPress 6.3.0 版本引入。
  • 主要用于 wp_get_loading_optimization_attributes() 函数中，以获取加载优化属性。
  • 开发者可通过 wp_min_priority_img_pixels 过滤器自定义图片像素阈值。
📄 原文内容

Determines whether to add fetchpriority='high' to loading attributes.

Parameters

$loading_attrsarrayrequired
Array of the loading optimization attributes for the element.
$tag_namestringrequired
The tag name.
$attrarrayrequired
Array of the attributes for the element.

Return

array Updated loading optimization attributes for the element.

Source

function wp_maybe_add_fetchpriority_high_attr( $loading_attrs, $tag_name, $attr ) {
	// For now, adding `fetchpriority="high"` is only supported for images.
	if ( 'img' !== $tag_name ) {
		return $loading_attrs;
	}

	if ( isset( $attr['fetchpriority'] ) ) {
		/*
		 * While any `fetchpriority` value could be set in `$loading_attrs`,
		 * for consistency we only do it for `fetchpriority="high"` since that
		 * is the only possible value that WordPress core would apply on its
		 * own.
		 */
		if ( 'high' === $attr['fetchpriority'] ) {
			$loading_attrs['fetchpriority'] = 'high';
			wp_high_priority_element_flag( false );
		}

		return $loading_attrs;
	}

	// Lazy-loading and `fetchpriority="high"` are mutually exclusive.
	if ( isset( $loading_attrs['loading'] ) && 'lazy' === $loading_attrs['loading'] ) {
		return $loading_attrs;
	}

	if ( ! wp_high_priority_element_flag() ) {
		return $loading_attrs;
	}

	/**
	 * Filters the minimum square-pixels threshold for an image to be eligible as the high-priority image.
	 *
	 * @since 6.3.0
	 *
	 * @param int $threshold Minimum square-pixels threshold. Default 50000.
	 */
	$wp_min_priority_img_pixels = apply_filters( 'wp_min_priority_img_pixels', 50000 );

	if ( $wp_min_priority_img_pixels <= $attr['width'] * $attr['height'] ) {
		$loading_attrs['fetchpriority'] = 'high';
		wp_high_priority_element_flag( false );
	}

	return $loading_attrs;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_min_priority_img_pixels’, int $threshold )

Filters the minimum square-pixels threshold for an image to be eligible as the high-priority image.

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

Accesses a flag that indicates if an element is a possible candidate for fetchpriority='high'.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
Used by Description
wp_get_loading_optimization_attributes()wp-includes/media.php

Gets loading optimization attributes.

Changelog

Version Description
6.3.0 Introduced.