云策 WordPress 开发者社区

函数文档

wp_lazy_loading_enabled()

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

概述

wp_lazy_loading_enabled() 函数用于判断是否在指定标签和上下文中添加 loading 属性，以控制懒加载行为。它默认对 'img' 和 'iframe' 标签启用，并通过过滤器提供自定义选项。

关键要点

  • 函数返回布尔值，指示是否添加 loading 属性，参数包括标签名和上下文。
  • 默认情况下，对 'img' 和 'iframe' 标签返回 true（从 WordPress 5.7.0 起 iframe 也默认启用）。
  • 可通过 wp_lazy_loading_enabled 过滤器全局调整懒加载启用状态。
  • 相关函数如 wp_get_loading_optimization_attributes() 和 wp_img_tag_add_loading_optimization_attrs() 依赖此函数。

代码示例

// 禁用所有懒加载
add_filter( 'wp_lazy_loading_enabled', '__return_false' );

// 针对特定附件调整 loading 属性
$attr['loading'] = false;
return wp_get_attachment_image( $attachment_id, $size, $icon, $attr );

// 使用过滤器移除特定 MIME 类型的 loading 属性
add_filter( 'wp_get_attachment_image_attributes', function( $attr, $attachment, $size ) {
    if ( $attachment->post_mime_type === 'image/svg+xml' ) {
        unset( $attr['loading'] );
    }
    return $attr;
} );

注意事项

  • 过滤器 wp_lazy_loading_enabled 是主要自定义方式，但可能不便于针对特定附件或 MIME 类型精细控制。
  • 对于特定附件，可通过 wp_get_attachment_image 函数或 wp_get_attachment_image_attributes 过滤器管理 loading 属性。
  • 内容过滤器如 the_content 会调用 wp_filter_content_tags，可使用 wp_img_tag_add_loading_attr 过滤器逐标签调整。
📄 原文内容

Determines whether to add the loading attribute to the specified tag in the specified context.

Parameters

$tag_namestringrequired
The tag name.
$contextstringrequired
Additional context, like the current filter name or the function name from where this was called.

Return

bool Whether to add the attribute.

Source

function wp_lazy_loading_enabled( $tag_name, $context ) {
	/*
	 * By default add to all 'img' and 'iframe' tags.
	 * See https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-loading
	 * See https://html.spec.whatwg.org/multipage/iframe-embed-object.html#attr-iframe-loading
	 */
	$default = ( 'img' === $tag_name || 'iframe' === $tag_name );

	/**
	 * Filters whether to add the `loading` attribute to the specified tag in the specified context.
	 *
	 * @since 5.5.0
	 *
	 * @param bool   $default  Default value.
	 * @param string $tag_name The tag name.
	 * @param string $context  Additional context, like the current filter name
	 *                         or the function name from where this was called.
	 */
	return (bool) apply_filters( 'wp_lazy_loading_enabled', $default, $tag_name, $context );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_lazy_loading_enabled’, bool $default, string $tag_name, string $context )

Filters whether to add the loading attribute to the specified tag in the specified context.

Uses Description
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.
wp_img_tag_add_loading_optimization_attrs()wp-includes/media.php

Adds optimization attributes to an img HTML tag.
wp_filter_content_tags()wp-includes/media.php

Filters specific tags in post content and modifies their markup.
WP_Widget_RSS::widget()wp-includes/widgets/class-wp-widget-rss.php

Outputs the content for the current RSS widget instance.
wp_admin_bar_my_sites_menu()wp-includes/admin-bar.php

Adds the “My Sites/[Site Name]” menu and all submenus.

Changelog

Version Description
5.7.0 Now returns true by default for iframe tags.
5.5.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    shaunjeffrey


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    wp_lazy_loading_enabled returns true for all tags, which is every time this function is called by default. Hooking into the wp_lazy_loading_enabled filter is the primary way of enabling or disabling this feature, however it does not readily allow this to be enabled or disabled for specific attachments or mime-types.

    add_filter( 'wp_lazy_loading_enabled', '__return_false' );

    1. To change how this feature works for specific attachments, the ‘loading’ attribute can be supplied to the wp_get_attachment_image function, or you can modify or remove the attribute using the wp_get_attachment_image_attributes filter.

    $attr['loading'] = false;
return wp_get_attachment_image( $attachment_id, $size, $icon, $attr );

    Or

    add_filter( 'wp_get_attachment_image_attributes', function( $attr, $attachment, $size ) {
	if ( $attachment->post_mime_type === 'image/svg+xml' ) {
		unset( $attr['loading'] );
	}
	return $attr;
} );

    2. To change how this works for specific avatars, you can either redefine the get_avatar function, supply the ‘loading’ attribute within the ‘extra_attr’ argument, or replace the HTML using the get_avatar filter.

    3. the_content, the_excerpt and widget_text_filters will call the wp_filter_content_tags filter on the content, which will also add the ‘loading’ attribute to image tags. To adjust this, the wp_img_tag_add_loading_attr filter can be used to manage the ‘loading’ attribute on a tag by tag basis.