云策 WordPress 开发者社区

钩子文档

wp_get_attachment_image_attributes

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

概述

wp_get_attachment_image_attributes 是一个 WordPress 过滤器，用于修改附件图像的 HTML 属性数组。它允许开发者自定义图像标记的属性，如 src、class、alt 等，常用于添加自定义数据属性或调整样式类。

关键要点

  • 过滤器名称：wp_get_attachment_image_attributes，用于过滤图像属性数组。
  • 参数：$attr（属性数组，键为属性名）、$attachment（WP_Post 附件对象）、$size（图像尺寸）。
  • 属性数组包含 src、class、alt、srcset、sizes、loading、decoding、fetchpriority 等键，支持自定义扩展。
  • 该过滤器在 wp_get_attachment_image() 函数内部调用，影响所有使用该函数的图像输出。
  • 注意事项：有用户反馈此过滤器可能仅对特色图像生效，需在实际使用中验证。

代码示例

add_filter( 'wp_get_attachment_image_attributes', 'wpdocs_filter_gallery_img_atts', 10, 2 );
function wpdocs_filter_gallery_img_atts( $atts, $attachment ) {
    if ( $full_size = wp_get_attachment_image_src( $attachment->ID, 'full' ) ) {
        if ( ! empty( $full_size[0] ) ) {
            $atts['data-full'] = $full_size[0];
        }
    }
    return $atts;
}

注意事项

  • 使用 array_key_exists() 而非 isset() 检查数组键，以确保能处理 NULL 值。
  • 过滤器可能不适用于所有附件图像场景，建议测试确认其触发条件。
📄 原文内容

Filters the list of attachment image attributes.

Parameters

$attrstring[]
Array of attribute values for the image markup, keyed by attribute name.
See wp_get_attachment_image() .

More Arguments from wp_get_attachment_image( … $attr )

Attributes for the image markup.

  • src string
    Image attachment URL.
  • class string
    CSS class name or space-separated list of classes.
    Default attachment-$size_class size-$size_class, where $size_class is the image size being requested.
  • alt string
    Image description for the alt attribute.
  • srcset string
    The 'srcset' attribute value.
  • sizes string
    The 'sizes' attribute value.
  • loading string|false
    The 'loading' attribute value. Passing a value of false will result in the attribute being omitted for the image.
    Default determined by wp_get_loading_optimization_attributes().
  • decoding string
    The 'decoding' attribute value. Possible values are 'async' (default), 'sync', or 'auto'. Passing false or an empty string will result in the attribute being omitted.
  • fetchpriority string
    The 'fetchpriority' attribute value, whether high, low, or auto.
    Default determined by wp_get_loading_optimization_attributes().

$attachmentWP_Post
Image attachment post.
$sizestring|int[]
Requested image size. Can be any registered image size name, or an array of width and height values in pixels (in that order).

Source

$attr = apply_filters( 'wp_get_attachment_image_attributes', $attr, $attachment, $size );

View all references View on Trac View on GitHub

Used by Description
wp_get_attachment_image()wp-includes/media.php

Gets an HTML img element representing an image attachment.

Changelog

Version Description
6.8.2 The $attr array includes width and height attributes.
2.8.0 Introduced.

User Contributed Notes

  2. Skip to note 6 content


    Drew Jaynes


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

    Add a data attribute to each tag in a gallery
    Note: this filter runs inside wp_get_attachment_image(), which means your attribute will be added for all uses of the function.

    /**
 * Filter attributes for the current gallery image tag to add a 'data-full'
 * data attribute.
 *
 * @param array   $atts       Gallery image tag attributes.
 * @param WP_Post $attachment WP_Post object for the attachment.
 * @return array (maybe) filtered gallery image tag attributes.
 */
function wpdocs_filter_gallery_img_atts( $atts, $attachment ) {
	if ( $full_size = wp_get_attachment_image_src( $attachment->ID, 'full' ) ) {
		if ( ! empty( $full_size[0] ) ) {
			$atts['data-full'] = $full_size[0];
		}
	}
	return $atts;
}
add_filter( 'wp_get_attachment_image_attributes', 'wpdocs_filter_gallery_img_atts', 10, 2 );

  4. Skip to note 8 content


    akkis


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

    You can add custom data attributes to image elements by adding this snippet on theme’s function.php:

        /**
     * Add custom data attribute to every image element
     */
    add_filter( 'wp_get_attachment_image_attributes', 'add_custom_image_data_attributes', 10, 3 );
    function add_custom_image_data_attributes( $attr, $attachment, $size ) {
        
        // Ensure that the <img> doesn't have the data attribute already
        if ( ! array_key_exists( 'data-custom', $attr ) ) {
            $attr['data-custom'] = 'dummy text';
        }

        return $attr;
    }

    Also, note that I use array_key_exists() PHP function instead of isset() because isset() does not return TRUE for array keys that correspond to a NULL value, while array_key_exists() does as of PHP Manual (http://php.net/manual/en/function.array-key-exists.php).