shortcode_atts()
云策文档标注
概述
shortcode_atts() 函数用于合并用户定义的短代码属性与支持的属性列表，并填充默认值。它确保返回的属性仅包含在 $pairs 中定义的键，忽略不支持的属性，并支持通过过滤器进行自定义。
关键要点
- 函数接受三个参数：$pairs（支持的属性及其默认值数组）、$atts（用户定义的属性数组）和可选的 $shortcode（短代码名称）。
- 返回一个数组，包含合并后的属性，其中用户提供的值覆盖默认值，不支持的属性被移除。
- 如果提供了 $shortcode 参数，会触发 apply_filters("shortcode_atts_{$shortcode}") 钩子，允许对输出进行过滤。
- 属性键名区分大小写，但 WordPress 在解析短代码时会将用户属性键名转换为小写，因此建议在 $pairs 中使用小写键名以避免问题。
- 函数常用于短代码回调函数中，以安全处理用户输入。
代码示例
function wpdocs_bartag_func( $atts ) {
$atts = shortcode_atts(
array(
'foo' => 'no foo',
'bar' => 'default bar',
), $atts, 'bartag' );
return 'bartag: ' . esc_html( $atts['foo'] ) . ' ' . esc_html( $atts['bar'] );
}
add_shortcode( 'bartag', 'wpdocs_bartag_func' );注意事项
- 属性键名必须与 $pairs 中的键名完全匹配（包括大小写），否则用户提供的值可能被忽略，使用默认值。
- 可以使用 array_change_key_case() 将 $atts 键名转换为小写，以确保与 $pairs 匹配，提高兼容性。
- 通过 shortcode_atts_{$shortcode} 过滤器，可以为特定短代码动态添加或修改属性。
原文内容
Combines user attributes with known attributes and fill in defaults when needed.
Description
The pairs should be considered to be all of the attributes which are supported by the caller and given as a list. The returned attributes will only contain the attributes in the $pairs list.
If the $atts list has unsupported attributes, then they will be ignored and removed from the final returned list.
Parameters
$pairsarrayrequired-
Entire list of supported attributes and their defaults.
$attsarrayrequired-
User defined attributes in shortcode tag.
$shortcodestringoptional-
The name of the shortcode, provided for context to enable filtering
Source
function shortcode_atts( $pairs, $atts, $shortcode = '' ) {
$atts = (array) $atts;
$out = array();
foreach ( $pairs as $name => $default ) {
if ( array_key_exists( $name, $atts ) ) {
$out[ $name ] = $atts[ $name ];
} else {
$out[ $name ] = $default;
}
}
if ( $shortcode ) {
/**
* Filters shortcode attributes.
*
* If the third parameter of the shortcode_atts() function is present then this filter is available.
* The third parameter, $shortcode, is the name of the shortcode.
*
* @since 3.6.0
* @since 4.4.0 Added the `$shortcode` parameter.
*
* @param array $out The output array of shortcode attributes.
* @param array $pairs The supported attributes and their defaults.
* @param array $atts The user defined shortcode attributes.
* @param string $shortcode The shortcode name.
*/
$out = apply_filters( "shortcode_atts_{$shortcode}", $out, $pairs, $atts, $shortcode );
}
return $out;
}
Hooks
- apply_filters( “shortcode_atts_{$shortcode}”, array $out, array $pairs, array $atts, string $shortcode )
-
Filters shortcode attributes.
Changelog
| Version | Description |
|---|---|
| 2.5.0 | Introduced. |
Skip to note 6 content
Aaron T. Grogg
It might be really useful to note that attribute names must be all lowercase…
If your shortcode looks like this:
[shortcode attOne="foo" attTwo="bar"]The array passed to the callback function will look like this:
Array( attone => "foo", atttwo => "bar" )So, I guess you could use camelCase in the shortcode, just remember to expect those camelCase to be all lowercase in your
shortcode_atts…shortcode_atts()makes a case-sensitive comparison between the first argument (array of supported attributes and their defaults) and the second argument (array of user-defined attributes in shortcode tag). But the user-defined attributes are normalized to lowercase by WordPress before being passed to the shortcode callback function (seeshortcode_parse_atts()). So the case-sensitivity ofshortcode_atts()only becomes an issue if you define supported attributes using uppercase characters.Skip to note 7 content
Codex
Example
/** * Callback to register a bartag shortcode. * * @param array $atts Shortcode attributes. * @return string Shortcode output. function wpdocs_bartag_func( $atts ) { $atts = shortcode_atts( array( 'foo' => 'no foo', 'bar' => 'default bar', ), $atts, 'bartag' ); return 'bartag: ' . esc_html( $atts['foo'] ) . ' ' . esc_html( $atts['bar'] ); } add_shortcode( 'bartag', 'wpdocs_bartag_func' );[bartag foo=”koala” bar=”bears”] outputs the following:
bartag: koala bears
[bartag foo=”koala”] outputs the following:
bartag: koala default bar
This creates a “
[bartag]” shortcode that supports two attributes:[bartag foo="something" bar="something else"]. Both attributes are optional and will take on default options if they are not provided.Skip to note 8 content
crstauf
Clarification on Aaron’s note:
The case of the keys on the
$pairsmust match the keys on the$atts, or the value will be discarded.See these examples:
print_r( shortcode_atts( array( 'CAPITAL' => '1', 'fooBar' => '2', ), array( 'CAPITAL' => '3', 'fooBar' => '4', ) ) ); // Output: Array ( [CAPITAL] => 3 [fooBar] => 4 )print_r( shortcode_atts( array( 'CAPITAL' => '1', 'fooBar' => '2', ), array( 'capital' => '3', 'fooBar' => '4', ) ) ); // Output: Array ( [CAPITAL] => 1 [fooBar] => 4 )print_r( shortcode_atts( array( 'CAPITAL' => '1', 'fooBar' => '2', ), array( 'capital' => '3', 'foobar' => '4', ) ) ); // Output: Array ( [CAPITAL] => 1 [fooBar] => 2 )print_r( shortcode_atts( array( 'capital' => '1', 'fooBar' => '2', ), array( 'capital' => '3', 'foobar' => '4', ) ) ); // Output: Array ( [capital] => 3 [fooBar] => 2 )Skip to note 9 content
Tessa Watkins
To ensure this function works and allow for case insensitive attributes, I use
array_change_key_casein a one-liner like this/** * My Custom Shortcode * * @param array $atts Optional. An associative array of key/value attributes. Default is empty array. * @param string $content Optional. The content between the opening and closing shortcode tags. Default is an empty string. * @param string $tag Optional. The name of the shortcode, provided for context to enable filtering. Default is an empty string. * * @return string shortcode output */ function tw_custom_shortcode($atts = array(), $content = '', $tag = '') { $atts = shortcode_atts(array(), array_change_key_case((array)$atts, CASE_LOWER), $tag); //Do stuff, probably sanitize inputs $output = ''; return $output; } add_shortcode('tw_custom', 'tw_custom_shortcode');Skip to note 10 content
zitomerh
I had to hunt around to find all the pieces, I hope others find this helpful.
So, building on a previous example:
/** * How to use shortcode callback parms with shortcode_atts to make * callback code flexible and re-useable. * * This allows filters to be applied to a callback depending on which * shortcode called it. * * @param array $atts Shortcode attributes. * @param string $content Shortcode content. * @param string $tag The shortcode which invoked the callback * @return string Shortcode output. */ function my_callback_func( $atts, $content, $tag ) { $atts = shortcode_atts( array( 'foo' => '', 'bar' => '', ), $atts, $tag ); //do something here(trivial example) if ( !empty($zoo) ) { return $zoo; //where did $zoo come from? see below } else return $foo; } add_shortcode( 'myshortcode1', 'my_callback_func' ); add_shortcode( 'myshortcode2', 'my_callback_func' ); /* now make a filter that's applied ONLY when my_callback_func is invoked by myshortcode1 - this example adds param 'zoo' to myshortcode1 */ add_filter ('shortcode_atts_myshortcode1', 'add_zoo', 10, 3); function add_zoo ($out, $pairs, $atts ) { $out['zoo'] = ''; return $out; } // Now we can use [myshortcode1 foo='myfoo' zoo='myzoo'] output: myzoo // and [myshortcode2 foo='myfoo' zoo='myzoo'] output: myfoo