Changeset 61934 for trunk/src/wp-includes/media.php

Timestamp:

03/11/2026 06:19:53 AM (3 months ago)

Author:

westonruter

Message:

Media: Add optimization support for IMG tags with fetchpriority=low or fetchpriority=auto.

This updates wp_get_loading_optimization_attributes() and wp_maybe_add_fetchpriority_high_attr() to account for cases where an IMG has fetchpriority=low or fetchpriority=auto:

• IMG tags with fetchpriority=low are not lazy-loaded since they may be in a Navigation overlay, Details block, or Accordion Item block and need to be loaded the instant the user toggles the block.
• IMG tags with fetchpriority=auto do not increase the media count since they may be hidden in a viewport by block visibility settings.
• Blocks with conditional visibility (such as hidden on mobile or desktop) now automatically add fetchpriority="auto" to their contained IMG tags to prevent them from erroneously receiving fetchpriority=high or affecting the lazy-loading of subsequent images.
• An IMG with fetchpriority=auto which also surpasses the wp_min_priority_img_pixels threshold will prevent a subsequent image from getting fetchpriority=high.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11196
Includes backport of ​Gutenberg#76302.

See related Gutenberg issues:

• ​76181: Image in navigation overlay can get fetchpriority=high and degrade LCP metric for page.
• ​76268: Image in collapsed Details block may erroneously get fetchpriority=high even though hidden.
• ​76301: Block Visibility: IMG in viewport-conditional block may get fetchpriority=high even when not displayed.
• ​76335: Image in collapsed Accordion block may erroneously get fetchpriority=high even though hidden.

Follow-up to r56347, r56037.

Props westonruter, mukesh27, ramonopoly, wildworks.
See #58235.
Fixes #64823.

File:

• trunk/src/wp-includes/media.php (modified) (10 diffs)

trunk/src/wp-includes/media.php

@@ -5968 +5968 @@
  *
  * @since 6.3.0
+ * @since 7.0.0 Support `fetchpriority=low` and `fetchpriority=auto` so that `loading=lazy` is not added and the media count is not increased.
  *
  * @global WP_Query $wp_query WordPress Query object.
@@ -6068 +6069 @@
 
     // Logic to handle a `fetchpriority` attribute that is already provided.
-    if ( isset( $attr['fetchpriority'] ) && 'high' === $attr['fetchpriority'] ) {
+    $existing_fetchpriority = ( $attr['fetchpriority'] ?? null );
+    $is_low_fetchpriority   = ( 'low' === $existing_fetchpriority );
+    if ( 'high' === $existing_fetchpriority ) {
         /*
          * If the image was already determined to not be in the viewport (e.g.
@@ -6091 +6094 @@
             $maybe_in_viewport = true;
         }
+    } elseif ( $is_low_fetchpriority ) {
+        /*
+         * An IMG with fetchpriority=low is not initially displayed; it may be hidden in the Navigation Overlay,
+         * or it may be occluded in a non-initial carousel slide. Such images must not be lazy-loaded because the browser
+         * has no heuristic to know when to start loading them before the user needs to see them.
+         */
+        $maybe_in_viewport = false;
+
+        // Preserve fetchpriority=low.
+        $loading_attrs['fetchpriority'] = 'low';
+    } elseif ( 'auto' === $existing_fetchpriority ) {
+        /*
+         * When a block's visibility support identifies that the block is conditionally displayed based on the viewport
+         * size, then it adds `fetchpriority=auto` to the block's IMG tags. These images must not be fetched with high
+         * priority because they could be erroneously loaded in viewports which do not even display them. Contrarily,
+         * they must not get `fetchpriority=low` because they may in fact be displayed in the current viewport. So as
+         * a signal to indicate that an IMG may be in the viewport, `fetchpriority=auto` is added. This has the effect
+         * here of preventing the media count from being increased, so that images hidden with block visibility do not
+         * affect whether a following IMG gets `loading=lazy`. In particular, `loading=lazy` should still be omitted
+         * on an IMG following any number of initial IMGs with `fetchpriority=auto` since those initial images may not
+         * be displayed.
+         */
+
+        // Preserve fetchpriority=auto.
+        $loading_attrs['fetchpriority'] = 'auto';
     }
 
@@ -6141 +6169 @@
              */
             && did_action( 'get_header' ) && ! did_action( 'get_footer' )
-            ) {
+        ) {
             $maybe_in_viewport    = true;
             $maybe_increase_count = true;
@@ -6150 +6178 @@
      * If the element is in the viewport (`true`), potentially add
      * `fetchpriority` with a value of "high". Otherwise, i.e. if the element
-     * is not not in the viewport (`false`) or it is unknown (`null`), add
-     * `loading` with a value of "lazy".
+     * is not in the viewport (`false`) or it is unknown (`null`), add
+     * `loading` with a value of "lazy" if the element is not already being
+     * de-prioritized with `fetchpriority=low` due to occlusion in
+     * Navigation Overlay, non-initial carousel slides, or a collapsed Details block.
      */
     if ( $maybe_in_viewport ) {
         $loading_attrs = wp_maybe_add_fetchpriority_high_attr( $loading_attrs, $tag_name, $attr );
-    } else {
+    } elseif ( ! $is_low_fetchpriority ) {
         // Only add `loading="lazy"` if the feature is enabled.
         if ( wp_lazy_loading_enabled( $tag_name, $context ) ) {
@@ -6165 +6195 @@
      * If flag was set based on contextual logic above, increase the content
      * media count, either unconditionally, or based on whether the image size
-     * is larger than the threshold.
-     */
-    if ( $increase_count ) {
-        wp_increase_content_media_count();
-    } elseif ( $maybe_increase_count ) {
-        /** This filter is documented in wp-includes/media.php */
-        $wp_min_priority_img_pixels = apply_filters( 'wp_min_priority_img_pixels', 50000 );
-
-        if ( $wp_min_priority_img_pixels <= $attr['width'] * $attr['height'] ) {
+     * is larger than the threshold. This does not apply when the IMG has
+     * fetchpriority=auto because it may be conditionally displayed by viewport
+     * size.
+     */
+    if ( 'auto' !== $existing_fetchpriority ) {
+        if ( $increase_count ) {
             wp_increase_content_media_count();
+        } elseif ( $maybe_increase_count ) {
+            /** This filter is documented in wp-includes/media.php */
+            $wp_min_priority_img_pixels = apply_filters( 'wp_min_priority_img_pixels', 50000 );
+
+            if ( $wp_min_priority_img_pixels <= $attr['width'] * $attr['height'] ) {
+                wp_increase_content_media_count();
+            }
         }
     }
@@ -6246 +6280 @@
  *
  * @since 6.3.0
+ * @since 7.0.0 Support is added for IMG tags with `fetchpriority='low'` and `fetchpriority='auto'`.
  * @access private
  *
- * @param array  $loading_attrs Array of the loading optimization attributes for the element.
- * @param string $tag_name      The tag name.
- * @param array  $attr          Array of the attributes for the element.
- * @return array Updated loading optimization attributes for the element.
+ * @param array<string, string> $loading_attrs Array of the loading optimization attributes for the element.
+ * @param string                $tag_name      The tag name.
+ * @param array<string, mixed>  $attr          Array of the attributes for the element.
+ * @return array<string, string> Updated loading optimization attributes for the element.
  */
 function wp_maybe_add_fetchpriority_high_attr( $loading_attrs, $tag_name, $attr ) {
@@ -6259 +6294 @@
     }
 
-    if ( isset( $attr['fetchpriority'] ) ) {
+    $existing_fetchpriority = $attr['fetchpriority'] ?? null;
+    if ( null !== $existing_fetchpriority && 'auto' !== $existing_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.
+         * When an IMG has been explicitly marked with `fetchpriority=high`, then honor that this is the element that
+         * should have the priority. In contrast, the Navigation block may add `fetchpriority=low` to an IMG which
+         * appears in the Navigation Overlay; such images should never be considered candidates for
+         * `fetchpriority=high`. Lastly, block visibility may add `fetchpriority=auto` to an IMG when the block is
+         * conditionally displayed based on viewport size. Such an image is considered an LCP element candidate if it
+         * exceeds the threshold for the minimum number of square pixels.
          */
-        if ( 'high' === $attr['fetchpriority'] ) {
+        if ( 'high' === $existing_fetchpriority ) {
             $loading_attrs['fetchpriority'] = 'high';
             wp_high_priority_element_flag( false );
@@ -6293 +6331 @@
 
     if ( $wp_min_priority_img_pixels <= $attr['width'] * $attr['height'] ) {
-        $loading_attrs['fetchpriority'] = 'high';
+        if ( 'auto' !== $existing_fetchpriority ) {
+            $loading_attrs['fetchpriority'] = 'high';
+        }
         wp_high_priority_element_flag( false );
     }
@@ -6307 +6347 @@
  *
  * @param bool $value Optional. Used to change the static variable. Default null.
- * @return bool Returns true if high-priority element was marked already, otherwise false.
- */
-function wp_high_priority_element_flag( $value = null ) {
+ * @return bool Returns true if the high-priority element was not already marked.
+ */
+function wp_high_priority_element_flag( $value = null ): bool {
     static $high_priority_element = true;