wp_img_tag_add_loading_attr()

💡 云策文档标注

概述

wp_img_tag_add_loading_attr() 是一个已弃用的 WordPress 函数，用于向 HTML img 标签添加 loading 属性，以控制图片的懒加载行为。该函数在 WordPress 6.3.0 中被 wp_img_tag_add_loading_optimization_attrs() 取代。

关键要点

函数 wp_img_tag_add_loading_attr() 已弃用，建议使用 wp_img_tag_add_loading_optimization_attrs() 替代。
该函数接受两个参数：$image（HTML img 标签字符串）和 $context（上下文字符串），返回添加了 loading 属性的 img 标签。
仅当 img 标签包含 src、width 和 height 属性时，才会添加 loading 属性。
通过过滤器 wp_img_tag_add_loading_attr 可以自定义 loading 属性的值，默认值为 'lazy'。

代码示例

add_filter( 'wp_img_tag_add_loading_attr', 'skip_lazy_load', 10, 3 );

function skip_lazy_load( $value, $image, $context ) {
    if ( 'the_content' === $context ) {
        if ( false !== strpos( $image, 'hero-image.png' ) ) {
            return false; // 设置为 false 以省略懒加载属性。
        }
    }
    return $value;
}

注意事项

该函数自 WordPress 6.3.0 起已弃用，新代码应避免使用。
loading 属性值只能是 'lazy' 或 'eager'，其他值会被强制设为 'lazy'。
相关函数包括 wp_get_loading_attr_default()、esc_attr()、_deprecated_function() 和 apply_filters()。

📄 原文内容

Adds loading attribute to an img HTML tag.

Description

Parameters

$imagestringrequired: The HTML img tag where the attribute should be added.
$contextstringrequired: Additional context to pass to the filters.

Return

string Converted img tag with loading attribute added.

Source

function wp_img_tag_add_loading_attr( $image, $context ) {
	_deprecated_function( __FUNCTION__, '6.3.0', 'wp_img_tag_add_loading_optimization_attrs()' );
	/*
	 * Get loading attribute value to use. This must occur before the conditional check below so that even images that
	 * are ineligible for being lazy-loaded are considered.
	 */
	$value = wp_get_loading_attr_default( $context );

	// Images should have source and dimension attributes for the `loading` attribute to be added.
	if ( ! str_contains( $image, ' src="' ) || ! str_contains( $image, ' width="' ) || ! str_contains( $image, ' height="' ) ) {
		return $image;
	}

	/** This filter is documented in wp-admin/includes/media.php */
	$value = apply_filters( 'wp_img_tag_add_loading_attr', $value, $image, $context );

	if ( $value ) {
		if ( ! in_array( $value, array( 'lazy', 'eager' ), true ) ) {
			$value = 'lazy';
		}

		return str_replace( '<img', '<img loading="' . esc_attr( $value ) . '"', $image );
	}

	return $image;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_img_tag_add_loading_attr’, string|bool $value, string $image, string $context ): Filters the loading attribute value to add to an image. Default lazy.

Uses	Description
wp_get_loading_attr_default()`wp-includes/deprecated.php`	Gets the default value to use for a `loading` attribute on an element.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
_deprecated_function()`wp-includes/functions.php`	Marks a function as deprecated and inform when it has been used.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 2 more Show less

Changelog

Version	Description
6.3.0	Deprecated. Use wp_img_tag_add_loading_optimization_attrs() instead.
5.5.0	Introduced.

User Contributed Notes

Skip to note 2 content

Lukasz

5 years ago

If you want to remove loading attribute from specific images.

add_filter( 'wp_img_tag_add_loading_attr', 'skip_lazy_load', 10, 3 );

function skip_lazy_load( $value, $image, $context ) {

if ( 'the_content' === $context ) {
	// Check if needle found <a href="https://www.php.net/manual/en/function.strpos.php" rel="nofollow ugc">https://www.php.net/manual/en/function.strpos.php</a>
	if ( false !== strpos( $image, 'hero-image.png' ) ) {
		return false; // Set to false so lazy loading attribute is omitted.
	}
}
return $value;
}

云策 WordPress 开发者社区

函数文档