云策 WordPress 开发者社区

函数文档

wp_enqueue_global_styles()

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

概述

wp_enqueue_global_styles() 函数用于将 theme.json 中定义的全局样式加入队列。它根据主题类型（块主题或经典主题）和资源加载模式（按需或默认）决定样式输出位置，并处理自定义 CSS 的集成。

关键要点

  • 函数核心功能是加载 theme.json 中的全局样式，通过 wp_get_global_stylesheet() 获取样式表。
  • 输出位置取决于主题类型：块主题在头部输出，经典主题根据 wp_should_load_block_assets_on_demand() 决定头部或页脚输出。
  • 对于块主题，会集成 Customizer 的自定义 CSS，并在预览时添加里程碑注释以便实时预览。
  • 使用 wp_register_style()、wp_add_inline_style() 和 wp_enqueue_style() 注册并加入样式队列。
  • 通过 wp_add_global_styles_for_blocks() 为每个块添加内联样式。

代码示例

function wp_enqueue_global_styles() {
    $assets_on_demand = wp_should_load_block_assets_on_demand();
    $is_block_theme   = wp_is_block_theme();
    $is_classic_theme = ! $is_block_theme;

    if (
        ( $is_block_theme && doing_action( 'wp_footer' ) ) ||
        ( $is_classic_theme && doing_action( 'wp_footer' ) && ! $assets_on_demand ) ||
        ( $is_classic_theme && doing_action( 'wp_enqueue_scripts' ) && $assets_on_demand )
    ) {
        return;
    }

    add_filter( 'wp_theme_json_get_style_nodes', 'wp_filter_out_block_nodes' );
    $stylesheet = wp_get_global_stylesheet();

    if ( $is_block_theme ) {
        remove_action( 'wp_head', 'wp_custom_css_cb', 101 );
        $custom_css = trim( wp_get_custom_css() );
        if ( $custom_css || is_customize_preview() ) {
            if ( is_customize_preview() ) {
                $before_milestone = '/*BEGIN_CUSTOMIZER_CUSTOM_CSS*/';
                $after_milestone  = '/*END_CUSTOMIZER_CUSTOM_CSS*/';
                $custom_css       = str_replace( array( $before_milestone, $after_milestone ), '', $custom_css );
                $custom_css       = $before_milestone . "n" . $custom_css . "n" . $after_milestone;
            }
            $custom_css = "n" . $custom_css;
        }
        $stylesheet .= $custom_css;
        $stylesheet .= wp_get_global_stylesheet( array( 'custom-css' ) );
    }

    if ( empty( $stylesheet ) ) {
        return;
    }

    wp_register_style( 'global-styles', false );
    wp_add_inline_style( 'global-styles', $stylesheet );
    wp_enqueue_style( 'global-styles' );
    wp_add_global_styles_for_blocks();
}

注意事项

  • 函数在 WordPress 5.8.0 版本引入，是块主题和全局样式系统的关键部分。
  • 使用前需确保主题支持 theme.json，否则可能无法正确加载样式。
  • 在经典主题中，如果启用了按需加载资源，样式可能在 wp_enqueue_scripts 钩子中输出，需注意钩子执行时机。
  • 自定义 CSS 集成仅适用于块主题，经典主题需通过其他方式处理。
📄 原文内容

Enqueues the global styles defined via theme.json.

Source

function wp_enqueue_global_styles() {
	$assets_on_demand = wp_should_load_block_assets_on_demand();
	$is_block_theme   = wp_is_block_theme();
	$is_classic_theme = ! $is_block_theme;

	/*
	 * Global styles should be printed in the head for block themes, or for classic themes when loading assets on
	 * demand is disabled, which is the default.
	 * The footer should only be used for classic themes when loading assets on demand is enabled.
	 *
	 * See https://core.trac.wordpress.org/ticket/53494 and https://core.trac.wordpress.org/ticket/61965.
	 */
	if (
		( $is_block_theme && doing_action( 'wp_footer' ) ) ||
		( $is_classic_theme && doing_action( 'wp_footer' ) && ! $assets_on_demand ) ||
		( $is_classic_theme && doing_action( 'wp_enqueue_scripts' ) && $assets_on_demand )
	) {
		return;
	}

	/*
	 * If loading the CSS for each block separately, then load the theme.json CSS conditionally.
	 * This removes the CSS from the global-styles stylesheet and adds it to the inline CSS for each block.
	 * This filter must be registered before calling wp_get_global_stylesheet();
	 */
	add_filter( 'wp_theme_json_get_style_nodes', 'wp_filter_out_block_nodes' );

	$stylesheet = wp_get_global_stylesheet();

	if ( $is_block_theme ) {
		/*
		 * Dequeue the Customizer's custom CSS
		 * and add it before the global styles custom CSS.
		 */
		remove_action( 'wp_head', 'wp_custom_css_cb', 101 );

		/*
		 * Get the custom CSS from the Customizer and add it to the global stylesheet.
		 * Always do this in Customizer preview for the sake of live preview since it be empty.
		 */
		$custom_css = trim( wp_get_custom_css() );
		if ( $custom_css || is_customize_preview() ) {
			if ( is_customize_preview() ) {
				/*
				 * When in the Customizer preview, wrap the Custom CSS in milestone comments to allow customize-preview.js
				 * to locate the CSS to replace for live previewing. Make sure that the milestone comments are omitted from
				 * the stored Custom CSS if by chance someone tried to add them, which would be highly unlikely, but it
				 * would break live previewing.
				 */
				$before_milestone = '/*BEGIN_CUSTOMIZER_CUSTOM_CSS*/';
				$after_milestone  = '/*END_CUSTOMIZER_CUSTOM_CSS*/';
				$custom_css       = str_replace( array( $before_milestone, $after_milestone ), '', $custom_css );
				$custom_css       = $before_milestone . "n" . $custom_css . "n" . $after_milestone;
			}
			$custom_css = "n" . $custom_css;
		}
		$stylesheet .= $custom_css;

		// Add the global styles custom CSS at the end.
		$stylesheet .= wp_get_global_stylesheet( array( 'custom-css' ) );
	}

	if ( empty( $stylesheet ) ) {
		return;
	}

	wp_register_style( 'global-styles', false );
	wp_add_inline_style( 'global-styles', $stylesheet );
	wp_enqueue_style( 'global-styles' );

	// Add each block as an inline css.
	wp_add_global_styles_for_blocks();
}

View all references View on Trac View on GitHub

Uses Description
wp_should_load_block_assets_on_demand()wp-includes/script-loader.php

Checks whether block styles should be loaded only on-render.
wp_add_global_styles_for_blocks()wp-includes/global-styles-and-settings.php

Adds global style rules to the inline style for each block.
wp_get_global_stylesheet()wp-includes/global-styles-and-settings.php

Returns the stylesheet resulting of merging core, theme, and user data.
wp_is_block_theme()wp-includes/theme.php

Returns whether the active theme is a block-based theme or not.
wp_get_custom_css()wp-includes/theme.php

Fetches the saved Custom CSS content for rendering.
is_customize_preview()wp-includes/theme.php

Whether the site is being previewed in the Customizer.
wp_register_style()wp-includes/functions.wp-styles.php

Registers a CSS stylesheet.
wp_add_inline_style()wp-includes/functions.wp-styles.php

Adds extra CSS styles to a registered stylesheet.
wp_enqueue_style()wp-includes/functions.wp-styles.php

Enqueues a CSS stylesheet.
remove_action()wp-includes/plugin.php

Removes a callback function from an action hook.
doing_action()wp-includes/plugin.php

Returns whether or not an action hook is currently being processed.
add_filter()wp-includes/plugin.php

Adds a callback function to a filter hook.

Show 7 moreShow less

Changelog

Version Description
5.8.0 Introduced.