云策 WordPress 开发者社区

函数文档

get_header_image()

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

概述

get_header_image() 函数用于检索自定义标题图像，返回处理后的 URL 字符串或 false。它支持随机图像选择和过滤器应用，确保 URL 的安全性和格式正确。

关键要点

  • 函数返回字符串（标题图像 URL）或 false（如果未设置或设置为 'remove-header'）。
  • 通过 get_theme_mod() 获取主题修改值，支持默认图像和随机图像功能。
  • 应用 get_header_image 过滤器，允许开发者修改返回的 URL。
  • 使用 sanitize_url() 和 set_url_scheme() 对 URL 进行清理和格式化。
  • 相关函数包括 get_header_image_tag()、has_header_image() 和 header_image()，用于更高级的标题图像处理。

代码示例

<img src="<?php echo get_header_image(); ?>" alt="" />

注意事项

  • 在 WordPress 4.4 及以上版本，建议优先使用 get_header_image_tag() 函数，它返回包含 srcset 属性的 <img> 标签，支持响应式图像。
  • 可以使用 the_custom_header_markup() 替代手动构建图像标记，以简化代码。
📄 原文内容

Retrieves header image for custom header.

Return

string|false

Source

function get_header_image() {
	$url = get_theme_mod( 'header_image', get_theme_support( 'custom-header', 'default-image' ) );

	if ( 'remove-header' === $url ) {
		return false;
	}

	if ( is_random_header_image() ) {
		$url = get_random_header_image();
	}

	/**
	 * Filters the header image URL.
	 *
	 * @since 6.1.0
	 *
	 * @param string $url Header image URL.
	 */
	$url = apply_filters( 'get_header_image', $url );

	if ( ! is_string( $url ) ) {
		return false;
	}

	$url = trim( $url );
	return sanitize_url( set_url_scheme( $url ) );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_header_image’, string $url )

Filters the header image URL.

Uses Description
get_theme_support()wp-includes/theme.php

Gets the theme support arguments passed when registering that support.
is_random_header_image()wp-includes/theme.php

Checks if random header image is in use.
get_random_header_image()wp-includes/theme.php

Gets random header image URL from registered images in theme.
get_theme_mod()wp-includes/theme.php

Retrieves theme modification value for the active theme.
set_url_scheme()wp-includes/link-template.php

Sets the scheme for a URL.
sanitize_url()wp-includes/formatting.php

Sanitizes a URL for database or redirect usage.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 2 moreShow less

Used by Description
get_media_states()wp-admin/includes/template.php

Retrieves an array of media states from an attachment.
get_header_video_settings()wp-includes/theme.php

Retrieves header video settings.
get_header_image_tag()wp-includes/theme.php

Creates image tag markup for a custom header image.
has_header_image()wp-includes/theme.php

Checks whether a header image is set or not.
Custom_Image_Header::step_1()wp-admin/includes/class-custom-image-header.php

Displays first step of custom header image page.
_delete_attachment_theme_mod()wp-includes/theme.php

Checks an attachment being deleted to see if it’s a header or background image.
header_image()wp-includes/theme.php

Displays header image URL.

Show 2 moreShow less

Changelog

Version Description
2.1.0 Introduced.

User Contributed Notes