add_shortcode()
云策文档标注
概述
add_shortcode() 函数用于在 WordPress 中注册新的短代码，将短代码标签与回调函数关联。开发者需注意短代码标签的唯一性以避免冲突，并遵循正确的回调函数设计原则。
关键要点
- 函数参数：$tag（短代码标签，字符串，必填）和 $callback（回调函数，可调用，必填）。
- 回调函数接收三个参数：$atts（属性数组）、$content（短代码内容，可为空）和 $shortcode_tag（短代码标签）。
- 短代码标签必须唯一，重复时后加载者优先；属性名会自动转换为小写。
- 回调函数应返回替换文本，而非直接输出，以避免意外行为。
- 建议在 init 钩子中注册短代码，确保 WordPress 正确初始化。
代码示例
// 基本示例
add_shortcode( 'footag', 'wpdocs_footag_func' );
function wpdocs_footag_func( $atts ) {
return "foo = {$atts['foo']}";
}
// 使用 shortcode_atts 设置默认属性
add_shortcode( 'bartag', 'wpdocs_bartag_func' );
function wpdocs_bartag_func( $atts ) {
$atts = shortcode_atts( array(
'foo' => 'no foo',
'baz' => 'default baz'
), $atts, 'bartag' );
return "foo = {$atts['foo']}";
}
// 处理包含内容的短代码
add_shortcode( 'baztag', 'wpdocs_baztag_func' );
function wpdocs_baztag_func( $atts, $content = "" ) {
return "content = $content";
}
// 在类中定义短代码
add_shortcode( 'baztag', array( 'MyPlugin', 'wpdocs_baztag_func' ) );
class MyPlugin {
public static function wpdocs_baztag_func( $atts, $content = "" ) {
return "content = $content";
}
}注意事项
- 短代码标签不能包含空格或保留字符（如 & / [ ] =），否则会触发 _doing_it_wrong()。
- 如果未设置属性，$atts 可能为空字符串，需在回调函数中检查并转换为数组，或使用 shortcode_atts() 处理。
- 在管理界面中，短代码可能在编辑器中渲染，导致问题，可使用 is_admin() 避免在后台执行。
- 属性值保持原样，但属性名会转为小写，访问时需注意。
原文内容
Adds a new shortcode.
Description
Care should be taken through prefixing or other means to ensure that the shortcode tag being added is unique and will not conflict with other, already-added shortcode tags. In the event of a duplicated tag, the tag loaded last will take precedence.
Parameters
$tagstringrequired-
Shortcode tag to be searched in post content.
$callbackcallablerequired-
The callback function to run when the shortcode is found.
Every shortcode callback is passed three parameters by default, including an array of attributes ($atts), the shortcode content or null if not set ($content), and finally the shortcode tag itself ($shortcode_tag), in that order.
Source
function add_shortcode( $tag, $callback ) {
global $shortcode_tags;
if ( '' === trim( $tag ) ) {
_doing_it_wrong(
__FUNCTION__,
__( 'Invalid shortcode name: Empty name given.' ),
'4.4.0'
);
return;
}
if ( 0 !== preg_match( '@[<>&/[]x00-x20=]@', $tag ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: Shortcode name, 2: Space-separated list of reserved characters. */
__( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ),
$tag,
'& / < > [ ] ='
),
'4.4.0'
);
return;
}
$shortcode_tags[ $tag ] = $callback;
}
Changelog
| Version | Description |
|---|---|
| 2.5.0 | Introduced. |
Skip to note 10 content
Codex
Examples
Simplest example of a shortcode tag using the API:
[footag foo="bar"]add_shortcode( 'footag', 'wpdocs_footag_func' ); function wpdocs_footag_func( $atts ) { return "foo = {$atts['foo']}"; }Example with nice attribute defaults:
[bartag foo="bar"]add_shortcode( 'bartag', 'wpdocs_bartag_func' ); function wpdocs_bartag_func( $atts ) { $atts = shortcode_atts( array( 'foo' => 'no foo', 'baz' => 'default baz' ), $atts, 'bartag' ); return "foo = {$atts['foo']}"; }Example with enclosed content:
[baztag]content[/baztag]add_shortcode( 'baztag', 'wpdocs_baztag_func' ); function wpdocs_baztag_func( $atts, $content = "" ) { return "content = $content"; }If your plugin is designed as a class write as follows:
add_shortcode( 'baztag', array( 'MyPlugin', 'wpdocs_baztag_func' ) ); class MyPlugin { public static function wpdocs_baztag_func( $atts, $content = "" ) { return "content = $content"; } }Skip to note 11 content
Denis Žoljom
When adding `add_shortcode() ` function in a plugin, it’s good to add it in a function that is hooked to `init` hook. So that WordPress has time to initialize properly.
add_action( 'init', 'wpdocs_add_custom_shortcode' ); function wpdocs_add_custom_shortcode() { add_shortcode( 'footag', 'wpdocs_footag_func' ); }As described in the plugins handbook.
inithook. With this, other plugin can work with other functions about short code and result correctly. Example: plugin A add some short code about icon tag, my plug in B would like to override them so I may useremove_shortcode()and thenadd_shortcode().Skip to note 12 content
Ahmad Karim
Example of
add_shortcodefunction that usesget_template_partfunction to include a template.function wpdocs_the_shortcode_func( $atts ) { $attributes = shortcode_atts( array( 'title' => false, 'limit' => 4, ), $atts ); ob_start(); // include template with the arguments (The $args parameter was added in v5.5.0) get_template_part( 'template-parts/wpdocs-the-shortcode-template', null, $attributes ); return ob_get_clean(); } add_shortcode( 'wpdocs_the_shortcode', 'wpdocs_the_shortcode_func' );Skip to note 13 content
nasifshuvo123
For wppb plugin boilerplate I add code to define_public_hooks()
$this->loader->add_action( 'init', $plugin_public, 'register_shortcodes' );Then in public folder, in class_public file I added:
public function register_shortcodes(){ add_shortcode( 'sample-shortcode','shortcode_function' ); function shortcode_function( ) { return "Hello Shortcode"; } }Skip to note 14 content
Matthias Kittsteiner
Beware that the first argument passed to the callback is an empty string if no attributes are set in the shortcode. So a type declaration will fail:
“Fatal error: Uncaught Error: Argument 1 passed to shortcode_callback() must be of the type array, string given”
Use a check whether
$argumentsis not an array and if so, replace it with an empty array:function shortcode_callback( $attributes, string $content, string $shortcode ) { if ( ! is_array( $attributes ) ) { $attributes = []; } // do stuff }shortcode_atts()this will already be taken care of. If using PHP 8.0+, you can also declare the parameter asarray|string.function shortcode_callback( array|string $atts, string $content, string $shortcode_tag ) { $atts = shortcode_atts( array( 'attribute' => 'default_value' ), $atts ); // do stuff }shortcode_atts()this will already be taken care of. If using PHP 8.0+, you can also declare the parameter asarray|string.Skip to note 15 content
Xedin Unknown
⚠️⚠️
Currently, and for some time now, viewing a post with a shortcode in the editor caused the shortcode to get rendered. This is very unexpected behaviour described in an old issue. It can, for example, cause the post to become uneditable via the admin if there’s an error in the shortcode, such as some visitor-facing area variables or functions not being declared, etc.
To go around this, as mentioned in a comment, use the
is_admin()function to prevent computation on admin pages.echoinstead ofreturnin the callback. Maybe this was fixed in the past few months… or you were usingecholike me. Also, if you useechothe shortcode content will not appear where the shortcode was placed. So it is best toreturnthe output of the callback function.Skip to note 16 content
Patrick Johanneson
Notes (from the Codex — https://codex.wordpress.org/Function_Reference/add_shortcode#Notes)
Skip to note 17 content
SpeakOut! Steve
When passing values via the shortcode e.g.
[myshortcode FooBar="one" SomethingElse="two"]the keys in the array are transformed to lowercaseThe array passed to the callback function will be:
Array( foobar => "one", somethingelse=> "two" )Don’t be like me and spend hours trying to figure out why the values weren’t being passed.
Skip to note 18 content
Sabbir Mia
$atts: an associative array of attributes, you can access the associative array anywhere.
$content: the enclosed content (if the shortcode is used in its enclosing form)
/** * Appends a <a> tag with URL to the content. * * @param array $atts the shortcode attributes. * @param sring $content the editor enclosed content. * @return string */ function button_callback( $atts, $content ) { // It's a default value. $default = array( 'url' => '', ); // You will pass default value after that user define values. $button_attrs = shortcode_atts( $default, $atts ); return sprintf( '<a href="%s">%s</a>', $button_attrs['url'], do_shortcode( $content ) ); } add_shortcode( 'test-button', 'button_callback' );