wp_style_add_data()

💡 云策文档标注

概述

wp_style_add_data() 函数用于向已注册的 CSS 样式表添加元数据，如 RTL 支持、条件加载等。它依赖于 WP_Styles 类，仅对已注册的样式表生效。

关键要点

函数作用：为样式表添加元数据，如 'rtl'、'suffix'、'alt'、'title'、'path' 等键值对。
前提条件：样式表必须已通过 wp_enqueue_style() 注册，否则函数无效。
参数说明：$handle 为样式表句柄，$key 为元数据键（如 'rtl'），$value 为对应值（如 true 或 'replace'）。
返回值：成功返回 true，失败返回 false。
相关函数：内部调用 wp_styles()->add_data()，与 WP_Styles::add_data() 和 wp_styles() 相关。

代码示例

// 添加条件注释加载 IE 特定样式表
wp_enqueue_style( 'twentyfifteen-ie', get_template_directory_uri() . '/css/ie.css' );
wp_style_add_data( 'twentyfifteen-ie', 'conditional', 'lt IE 9' );

// 添加 RTL 支持
wp_enqueue_style( 'wpdocs-style', get_stylesheet_uri() );
wp_style_add_data( 'wpdocs-style', 'rtl', true ); // 或 'replace' 以替换原样式

注意事项

必须在 wp_enqueue_style() 之后调用，确保样式表已注册。
对于 RTL 支持，需提供对应的 RTL 样式文件（如 style-rtl.css）。
从 WordPress 6.9.0 起，'conditional' 参数若存在，样式表将被忽略，需注意版本兼容性。

📄 原文内容

Adds metadata to a CSS stylesheet.

Description

Works only if the stylesheet has already been registered.

Possible values for $key and $value: ‘rtl’ bool|string To declare an RTL stylesheet.
‘suffix’ string Optional suffix, used in combination with RTL.
‘alt’ bool For rel=”alternate stylesheet”.
‘title’ string For preferred/alternate stylesheets.
‘path’ string The absolute path to a stylesheet. Stylesheet will load inline when ‘path’ is set.

Parameters

$handlestringrequired: Name of the stylesheet.
$keystringrequired: Name of data point for which we’re storing a value.
Accepts 'rtl' and 'suffix', 'alt', 'title' and 'path'.
$valuemixedrequired: String containing the CSS data to be added.

Return

bool True on success, false on failure.

Source

function wp_style_add_data( $handle, $key, $value ) {
	return wp_styles()->add_data( $handle, $key, $value );
}

View all references View on Trac View on GitHub

Uses	Description
WP_Styles::add_data()`wp-includes/class-wp-styles.php`	Overrides the add_data method from WP_Dependencies, to allow unsetting dependencies for conditional styles.
wp_styles()`wp-includes/functions.wp-styles.php`	Initializes $wp_styles if it has not been set.

Used by	Description
wp_enqueue_block_style()`wp-includes/script-loader.php`	Enqueues a stylesheet for a specific block.
register_block_style_handle()`wp-includes/blocks.php`	Finds a style handle for the block metadata field. It detects when a path to file was provided and registers the style under automatically generated handle name. It returns unprocessed style handle otherwise.

Changelog

Version	Description
6.9.0	`'conditional'` value changed. If the `'conditional'` parameter is present the stylesheet will be ignored.
5.8.0	Added `'path'` as an official value for $key. See wp_maybe_inline_styles().
3.6.0	Introduced.

User Contributed Notes

Skip to note 3 content

Aamer Shahzad

10 years ago

Enqueue IE-specific stylesheets with conditional comments

/**
 * Enqueue styles conditionally using <a href="https://developer.wordpress.org/reference/functions/wp_style_add_data/">wp_style_add_data()</a>.
 *
 * Example taken from the Twenty Fifteen theme and is used to load
 * stylesheets specifically for IE8 and below. IE10 and above does
 * not support conditional comments in standards mode.
 *
 * @link     <a href="https://msdn.microsoft.com/en-us/library/ms537512(v=vs.85).aspx" rel="nofollow ugc">https://msdn.microsoft.com/en-us/library/ms537512(v=vs.85).aspx</a>
 * @internal Called from 'wp_enqueue_scripts' action.
 */
function wpdocs_enqueue_scripts() {
	// Load the Internet Explorer specific stylesheet.
	wp_enqueue_style( 'twentyfifteen-ie', get_template_directory_uri() . '/css/ie.css', array( 'twentyfifteen-style' ), '20141010' );
	wp_style_add_data( 'twentyfifteen-ie', 'conditional', 'lt IE 9' );

	// Load the Internet Explorer 7 specific stylesheet.
	wp_enqueue_style( 'twentyfifteen-ie7', get_template_directory_uri() . '/css/ie7.css', array( 'twentyfifteen-style' ), '20141010' );
	wp_style_add_data( 'twentyfifteen-ie7', 'conditional', 'lt IE 8' );
}

add_action( 'wp_enqueue_scripts', 'wpdocs_enqueue_scripts' );

Skip to note 4 content

Masoud Golchin

3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
To add an RTL (right-to-left) version of the style when the site is displayed in an RTL language, you can do this:
```
// Hook into WordPress' enqueue scripts action.
add_action( 'wp_enqueue_scripts', function () {
	// Enqueue your stylesheet (style.css).
	wp_enqueue_style( 'wpdocs-style', get_stylesheet_uri() );
	// Use wp_style_add_data to indicate an RTL stylesheet is available.
	wp_style_add_data( 'wpdocs-style', 'rtl', true );
} );
```
But if you want to completely swap out the original style with an RTL one when the site is viewed in an RTL language:
```
// Hook into WordPress' enqueue scripts action.
add_action( 'wp_enqueue_scripts', function () {
	// Enqueue your stylesheet (style.css).
	wp_enqueue_style( 'wpdocs-style', get_stylesheet_uri() );
	// Use wp_style_add_data to replace the original stylesheet with the RTL version.
	wp_style_add_data( 'wpdocs-style', 'rtl', 'replace' );
} );
```
Important notes:
1. Be sure to use wp_style_add_data after wp_enqueue_style. This guarantees that the style you’re trying to modify has been properly registered.
2. Don’t forget to create style-rtl.css in the same location as your style.css. This ensures that the RTL style will be found and used when needed.
Log in to add feedback

云策 WordPress 开发者社区

函数文档