云策 WordPress 开发者社区

函数文档

get_header_image_tag()

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

概述

get_header_image_tag() 函数用于生成自定义头部图像的 HTML img 标签标记。它基于当前主题设置的头像图像，自动处理属性如 src、width、height、alt，并可选生成 srcset 和 sizes 属性以支持响应式图像。

关键要点

  • 函数返回一个 HTML img 元素字符串，如果未设置头部图像则返回空字符串。
  • 接受一个可选参数 $attr，用于覆盖默认图像属性，如 src、width、height、alt。
  • 自动从附件中获取替代文本（alt），如果附件 ID 可用。
  • 如果未提供 srcset 和 sizes，且附件 ID 存在，函数会使用 wp_calculate_image_srcset() 和 wp_calculate_image_sizes() 自动生成这些属性。
  • 集成了加载优化属性（如 loading、fetchpriority、decoding），可通过 $attr 参数覆盖或移除。
  • 提供两个过滤器钩子：get_header_image_tag_attributes 用于过滤属性数组，get_header_image_tag 用于过滤最终 HTML 输出。

代码示例

// 基本用法，输出头部图像标签
echo get_header_image_tag();

// 自定义属性，例如添加类名和覆盖宽度
$custom_attr = array(
    'class' => 'custom-header-img',
    'width' => 800
);
echo get_header_image_tag($custom_attr);

注意事项

  • 确保主题已启用自定义头部支持，否则函数可能返回空字符串。
  • 使用 $attr 参数时，注意属性值会被转义，但需确保传入的数据安全。
  • 过滤器钩子允许开发者灵活修改输出，适用于高级定制场景。
📄 原文内容

Creates image tag markup for a custom header image.

Parameters

$attrarrayoptional
Additional attributes for the image tag. Can be used to override the default attributes.

Default:array()

Return

string HTML image element markup or empty string on failure.

Source

function get_header_image_tag( $attr = array() ) {
	$header      = get_custom_header();
	$header->url = get_header_image();

	if ( ! $header->url ) {
		return '';
	}

	$width  = absint( $header->width );
	$height = absint( $header->height );
	$alt    = '';

	// Use alternative text assigned to the image, if available. Otherwise, leave it empty.
	if ( ! empty( $header->attachment_id ) ) {
		$image_alt = get_post_meta( $header->attachment_id, '_wp_attachment_image_alt', true );

		if ( is_string( $image_alt ) ) {
			$alt = $image_alt;
		}
	}

	$attr = wp_parse_args(
		$attr,
		array(
			'src'    => $header->url,
			'width'  => $width,
			'height' => $height,
			'alt'    => $alt,
		)
	);

	// Generate 'srcset' and 'sizes' if not already present.
	if ( empty( $attr['srcset'] ) && ! empty( $header->attachment_id ) ) {
		$image_meta = get_post_meta( $header->attachment_id, '_wp_attachment_metadata', true );
		$size_array = array( $width, $height );

		if ( is_array( $image_meta ) ) {
			$srcset = wp_calculate_image_srcset( $size_array, $header->url, $image_meta, $header->attachment_id );

			if ( ! empty( $attr['sizes'] ) ) {
				$sizes = $attr['sizes'];
			} else {
				$sizes = wp_calculate_image_sizes( $size_array, $header->url, $image_meta, $header->attachment_id );
			}

			if ( $srcset && $sizes ) {
				$attr['srcset'] = $srcset;
				$attr['sizes']  = $sizes;
			}
		}
	}

	$attr = array_merge(
		$attr,
		wp_get_loading_optimization_attributes( 'img', $attr, 'get_header_image_tag' )
	);

	/*
	 * If the default value of `lazy` for the `loading` attribute is overridden
	 * to omit the attribute for this image, ensure it is not included.
	 */
	if ( isset( $attr['loading'] ) && ! $attr['loading'] ) {
		unset( $attr['loading'] );
	}

	// If the `fetchpriority` attribute is overridden and set to false or an empty string.
	if ( isset( $attr['fetchpriority'] ) && ! $attr['fetchpriority'] ) {
		unset( $attr['fetchpriority'] );
	}

	// If the `decoding` attribute is overridden and set to false or an empty string.
	if ( isset( $attr['decoding'] ) && ! $attr['decoding'] ) {
		unset( $attr['decoding'] );
	}

	/**
	 * Filters the list of header image attributes.
	 *
	 * @since 5.9.0
	 *
	 * @param array  $attr   Array of the attributes for the image tag.
	 * @param object $header The custom header object returned by 'get_custom_header()'.
	 */
	$attr = apply_filters( 'get_header_image_tag_attributes', $attr, $header );

	$attr = array_map( 'esc_attr', $attr );
	$html = '<img';

	foreach ( $attr as $name => $value ) {
		$html .= ' ' . $name . '="' . $value . '"';
	}

	$html .= ' />';

	/**
	 * Filters the markup of header images.
	 *
	 * @since 4.4.0
	 *
	 * @param string $html   The HTML image tag markup being filtered.
	 * @param object $header The custom header object returned by 'get_custom_header()'.
	 * @param array  $attr   Array of the attributes for the image tag.
	 */
	return apply_filters( 'get_header_image_tag', $html, $header, $attr );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_header_image_tag’, string $html, object $header, array $attr )

Filters the markup of header images.

apply_filters( ‘get_header_image_tag_attributes’, array $attr, object $header )

Filters the list of header image attributes.

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

Gets loading optimization attributes.
wp_calculate_image_srcset()wp-includes/media.php

A helper function to calculate the image sources to include in a ‘srcset’ attribute.
wp_calculate_image_sizes()wp-includes/media.php

Creates a ‘sizes’ attribute value for an image.
get_custom_header()wp-includes/theme.php

Gets the header image data.
get_header_image()wp-includes/theme.php

Retrieves header image for custom header.
absint()wp-includes/load.php

Converts a value to non-negative integer.
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
get_post_meta()wp-includes/post.php

Retrieves a post meta field for the given post ID.

Show 4 moreShow less

Used by Description
get_custom_header_markup()wp-includes/theme.php

Retrieves the markup for a custom header.
the_header_image_tag()wp-includes/theme.php

Displays the image markup for a custom header image.

Changelog

Version Description
4.4.0 Introduced.