get_custom_logo()
云策文档标注
概述
get_custom_logo() 函数用于返回自定义徽标的 HTML 标记，通常链接到首页，除非主题支持在首页移除链接。它支持多站点环境，并提供了过滤器和主题支持选项。
关键要点
- 函数返回自定义徽标的 HTML 字符串，基于主题设置和当前页面条件动态生成。
- 支持可选参数 $blog_id，用于在多站点中指定博客 ID，默认使用当前博客。
- 通过 get_theme_support('custom-logo', 'unlink-homepage-logo') 检查主题是否支持在首页移除徽标链接。
- 在首页且未分页时，若支持移除链接，则徽标不链接；否则链接到首页，并可能添加 aria-current 属性。
- 包含两个过滤器：get_custom_logo_image_attributes 用于修改图像属性，get_custom_logo 用于修改输出 HTML。
- 在自定义化预览模式下，即使未设置徽标，也会输出占位符 HTML。
代码示例
// 获取自定义徽标 URL 的示例
$custom_logo_id = get_theme_mod( 'custom_logo' );
$image = wp_get_attachment_image_src( $custom_logo_id, 'full' );
echo $image[0];注意事项
- 函数依赖于 has_custom_logo() 检查徽标是否存在，使用前应确保主题已启用自定义徽标功能。
- 在多站点环境中切换博客时，需注意 switch_to_blog() 和 restore_current_blog() 的调用，以避免副作用。
- 徽标的 alt 属性处理：若主题支持移除链接且为首页，则设为空字符串；否则从附件元数据或站点标题获取。
- 相关函数包括 the_custom_logo() 用于直接输出，以及多个查询和主题函数用于条件判断。
原文内容
Returns a custom logo, linked to home unless the theme supports removing the link on the home page.
Parameters
$blog_idintoptional-
ID of the blog in question. Default is the ID of the current blog.
Source
function get_custom_logo( $blog_id = 0 ) {
$html = '';
$switched_blog = false;
if ( is_multisite() && ! empty( $blog_id ) && get_current_blog_id() !== (int) $blog_id ) {
switch_to_blog( $blog_id );
$switched_blog = true;
}
// We have a logo. Logo is go.
if ( has_custom_logo() ) {
$custom_logo_id = get_theme_mod( 'custom_logo' );
$custom_logo_attr = array(
'class' => 'custom-logo',
'loading' => false,
);
$unlink_homepage_logo = (bool) get_theme_support( 'custom-logo', 'unlink-homepage-logo' );
if ( $unlink_homepage_logo && is_front_page() && ! is_paged() ) {
/*
* If on the home page, set the logo alt attribute to an empty string,
* as the image is decorative and doesn't need its purpose to be described.
*/
$custom_logo_attr['alt'] = '';
} else {
/*
* If the logo alt attribute is empty, get the site title and explicitly pass it
* to the attributes used by wp_get_attachment_image().
*/
$image_alt = get_post_meta( $custom_logo_id, '_wp_attachment_image_alt', true );
if ( empty( $image_alt ) ) {
$custom_logo_attr['alt'] = get_bloginfo( 'name', 'display' );
}
}
/**
* Filters the list of custom logo image attributes.
*
* @since 5.5.0
*
* @param array $custom_logo_attr Custom logo image attributes.
* @param int $custom_logo_id Custom logo attachment ID.
* @param int $blog_id ID of the blog to get the custom logo for.
*/
$custom_logo_attr = apply_filters( 'get_custom_logo_image_attributes', $custom_logo_attr, $custom_logo_id, $blog_id );
/*
* If the alt attribute is not empty, there's no need to explicitly pass it
* because wp_get_attachment_image() already adds the alt attribute.
*/
$image = wp_get_attachment_image( $custom_logo_id, 'full', false, $custom_logo_attr );
// Check that we have a proper HTML img element.
if ( $image ) {
if ( $unlink_homepage_logo && is_front_page() && ! is_paged() ) {
// If on the home page, don't link the logo to home.
$html = sprintf(
'<span class="custom-logo-link">%1$s</span>',
$image
);
} else {
$aria_current = ! is_paged() && ( is_front_page() || is_home() && ( (int) get_option( 'page_for_posts' ) !== get_queried_object_id() ) ) ? ' aria-current="page"' : '';
$html = sprintf(
'<a href="%1$s" class="custom-logo-link" rel="home"%2$s>%3$s</a>',
esc_url( home_url( '/' ) ),
$aria_current,
$image
);
}
}
} elseif ( is_customize_preview() ) {
// If no logo is set but we're in the Customizer, leave a placeholder (needed for the live preview).
$html = sprintf(
'<a href="%1$s" class="custom-logo-link" style="display:none;"><img class="custom-logo" alt="" /></a>',
esc_url( home_url( '/' ) )
);
}
if ( $switched_blog ) {
restore_current_blog();
}
/**
* Filters the custom logo output.
*
* @since 4.5.0
* @since 4.6.0 Added the `$blog_id` parameter.
*
* @param string $html Custom logo HTML output.
* @param int $blog_id ID of the blog to get the custom logo for.
*/
return apply_filters( 'get_custom_logo', $html, $blog_id );
}
Hooks
- apply_filters( ‘get_custom_logo’, string $html, int $blog_id )
-
Filters the custom logo output.
- apply_filters( ‘get_custom_logo_image_attributes’, array $custom_logo_attr, int $custom_logo_id, int $blog_id )
-
Filters the list of custom logo image attributes.
Skip to note 4 content
Rami Yushuvaev
To get the URL of the custom logo image:
$custom_logo_id = get_theme_mod( 'custom_logo' ); $image = wp_get_attachment_image_src( $custom_logo_id , 'full' ); echo $image[0];Skip to note 5 content
Anthony Hortin
See Also
the_custom_logo()
has_custom_logo()
Skip to note 6 content
Matthias Kittsteiner
An alternative way to get the URL of the custom logo image:
echo esc_url( wp_get_attachment_url( get_theme_mod( 'custom_logo' ) ) );