云策 WordPress 开发者社区

函数文档

wp_site_icon()

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

概述

wp_site_icon() 函数用于在 WordPress 网站中输出站点图标的 meta 标签，支持多种尺寸，并允许通过过滤器进行自定义扩展。

关键要点

  • 函数检查是否有站点图标或是否在自定义预览中，若无则直接返回。
  • 生成 32x32、192x192、180x180 和 270x270 像素尺寸的图标 meta 标签，使用 get_site_icon_url() 获取 URL。
  • 在自定义预览模式下，若 32x32 图标不存在，会使用默认的 /favicon.ico 路径。
  • 通过 site_icon_meta_tags 过滤器允许插件添加或修改 meta 标签。
  • 输出前会过滤掉空标签，确保只显示有效的 meta 标签。

代码示例

function wp_site_icon() {
    if ( ! has_site_icon() && ! is_customize_preview() ) {
        return;
    }

    $meta_tags = array();
    $icon_32   = get_site_icon_url( 32 );
    if ( empty( $icon_32 ) && is_customize_preview() ) {
        $icon_32 = '/favicon.ico';
    }
    if ( $icon_32 ) {
        $meta_tags[] = sprintf( '', esc_url( $icon_32 ) );
    }
    // 其他尺寸类似处理
    $meta_tags = apply_filters( 'site_icon_meta_tags', $meta_tags );
    $meta_tags = array_filter( $meta_tags );

    foreach ( $meta_tags as $meta_tag ) {
        echo "$meta_tagn";
    }
}

注意事项

  • 函数依赖于 has_site_icon() 和 get_site_icon_url() 来检查和处理图标。
  • 在自定义预览中，即使没有设置图标，也会显示默认图标以确保预览功能正常。
  • 使用 esc_url() 确保 URL 安全，防止 XSS 攻击。
📄 原文内容

Displays site icon meta tags.

Source

function wp_site_icon() {
	if ( ! has_site_icon() && ! is_customize_preview() ) {
		return;
	}

	$meta_tags = array();
	$icon_32   = get_site_icon_url( 32 );
	if ( empty( $icon_32 ) && is_customize_preview() ) {
		$icon_32 = '/favicon.ico'; // Serve default favicon URL in customizer so element can be updated for preview.
	}
	if ( $icon_32 ) {
		$meta_tags[] = sprintf( '<link rel="icon" href="%s" sizes="32x32" />', esc_url( $icon_32 ) );
	}
	$icon_192 = get_site_icon_url( 192 );
	if ( $icon_192 ) {
		$meta_tags[] = sprintf( '<link rel="icon" href="%s" sizes="192x192" />', esc_url( $icon_192 ) );
	}
	$icon_180 = get_site_icon_url( 180 );
	if ( $icon_180 ) {
		$meta_tags[] = sprintf( '<link rel="apple-touch-icon" href="%s" />', esc_url( $icon_180 ) );
	}
	$icon_270 = get_site_icon_url( 270 );
	if ( $icon_270 ) {
		$meta_tags[] = sprintf( '<meta name="msapplication-TileImage" content="%s" />', esc_url( $icon_270 ) );
	}

	/**
	 * Filters the site icon meta tags, so plugins can add their own.
	 *
	 * @since 4.3.0
	 *
	 * @param string[] $meta_tags Array of Site Icon meta tags.
	 */
	$meta_tags = apply_filters( 'site_icon_meta_tags', $meta_tags );
	$meta_tags = array_filter( $meta_tags );

	foreach ( $meta_tags as $meta_tag ) {
		echo "$meta_tagn";
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘site_icon_meta_tags’, string[] $meta_tags )

Filters the site icon meta tags, so plugins can add their own.

Uses Description
has_site_icon()wp-includes/general-template.php

Determines whether the site has a Site Icon.
get_site_icon_url()wp-includes/general-template.php

Returns the Site Icon URL.
is_customize_preview()wp-includes/theme.php

Whether the site is being previewed in the Customizer.
esc_url()wp-includes/formatting.php

Checks and cleans a URL.
apply_filters()wp-includes/plugin.php

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

Show 2 moreShow less

Changelog

Version Description
4.3.0 Introduced.