云策 WordPress 开发者社区

函数文档

get_custom_header()

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

概述

get_custom_header() 函数用于获取自定义头部图像的数据，返回一个包含图像URL、缩略图URL、宽度、高度等属性的对象。该函数处理随机头部图像和默认图像逻辑，确保返回完整数据。

关键要点

  • 函数返回一个对象，包含自定义头部图像的URL、缩略图URL、宽度、高度和视频支持等属性。
  • 支持随机头部图像，通过 is_random_header_image() 和 _get_random_header_data() 处理。
  • 当无自定义数据时，会检查主题是否支持默认图像，并尝试从 $_wp_default_headers 中匹配。
  • 返回对象通过 wp_parse_args() 合并默认值，确保数据完整性。
  • 相比 get_header_image()，get_custom_header() 返回的对象包含 attachment_id，便于获取不同尺寸图像。

代码示例

$custom_header = get_custom_header();
if ( ! empty( $custom_header->attachment_id ) ) {
    $image = wp_get_attachment_image_url( $custom_header->attachment_id, 'image-size' );
}
📄 原文内容

Gets the header image data.

Return

object

Source

function get_custom_header() {
	global $_wp_default_headers;

	if ( is_random_header_image() ) {
		$data = _get_random_header_data();
	} else {
		$data = get_theme_mod( 'header_image_data' );
		if ( ! $data && current_theme_supports( 'custom-header', 'default-image' ) ) {
			$directory_args        = array( get_template_directory_uri(), get_stylesheet_directory_uri() );
			$data                  = array();
			$data['url']           = vsprintf( get_theme_support( 'custom-header', 'default-image' ), $directory_args );
			$data['thumbnail_url'] = $data['url'];
			if ( ! empty( $_wp_default_headers ) ) {
				foreach ( (array) $_wp_default_headers as $default_header ) {
					$url = vsprintf( $default_header['url'], $directory_args );
					if ( $data['url'] === $url ) {
						$data                  = $default_header;
						$data['url']           = $url;
						$data['thumbnail_url'] = vsprintf( $data['thumbnail_url'], $directory_args );
						break;
					}
				}
			}
		}
	}

	$default = array(
		'url'           => '',
		'thumbnail_url' => '',
		'width'         => get_theme_support( 'custom-header', 'width' ),
		'height'        => get_theme_support( 'custom-header', 'height' ),
		'video'         => get_theme_support( 'custom-header', 'video' ),
	);
	return (object) wp_parse_args( $data, $default );
}

View all references View on Trac View on GitHub

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_data()wp-includes/theme.php

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

Retrieves theme modification value for the active theme.
get_template_directory_uri()wp-includes/theme.php

Retrieves template directory URI for the active theme.
get_stylesheet_directory_uri()wp-includes/theme.php

Retrieves stylesheet directory URI for the active theme.
current_theme_supports()wp-includes/theme.php

Checks a theme’s support for a given feature.
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.

Show 3 moreShow less

Used by Description
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.
Custom_Image_Header::step_1()wp-admin/includes/class-custom-image-header.php

Displays first step of custom header image page.

Changelog

Version Description
3.4.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    toby


    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

    If you want to get the custom header with a different image size use the function get_custom_header() instead of get_header_image() as the returned object has an attachment_id value.

    $custom_header = get_custom_header();
if ( ! empty( $custom_header->attachment_id ) ) {
	$image = wp_get_attachment_image_url( $custom_header->attachment_id, 'image-size' );
}