do_shortcode()

💡 云策文档标注

概述

do_shortcode() 是 WordPress 核心函数，用于在内容中搜索短代码并通过其钩子进行过滤处理。它确保短代码被正确解析和替换，支持嵌套短代码和 HTML 元素内的处理。

关键要点

函数签名：do_shortcode( $content, $ignore_html = false )，其中 $content 为必需参数，$ignore_html 可选，默认为 false。
当 $shortcode_tags 为空或内容中无短代码时，直接返回原内容，可能导致插件禁用后短代码仍显示。
内部使用正则表达式匹配注册的短代码标签，并调用 do_shortcodes_in_html_tags() 和 do_shortcode_tag() 进行处理。
支持通过 $ignore_html 参数跳过 HTML 元素内的短代码，避免破坏 HTML 结构。
函数处理嵌套短代码时，会临时添加 wp_get_attachment_image_context 过滤器以确保上下文正确。
返回过滤后的内容字符串，短代码被替换为对应输出。

代码示例

// 在 PHP 文件中使用短代码（文章编辑器外）
echo do_shortcode( '[gallery]' );
// 处理包含开闭标签的短代码
echo do_shortcode( '[iscorrect]' . $text_to_be_wrapped_in_shortcode . '[/iscorrect]' );
// 在文本小工具中启用短代码
add_filter( 'widget_text', 'do_shortcode' );
// 在页面模板中使用短代码
echo do_shortcode( '[contact-form-7 id="91" title="quote"]' );
// 将短代码输出存储到变量
$var = do_shortcode( '[gallery]' );
echo $var;

注意事项

使用短代码时需确保方括号正确，如 echo do_shortcode( ' [my_shortcode] ' )，仅名称无效。
插件禁用时，未定义的短代码标签可能导致内容未经过滤直接显示，需注意兼容性。
可通过过滤器（如 comment_text）扩展短代码支持到评论等区域。

📄 原文内容

Searches content for shortcodes and filter shortcodes through their hooks.

Description

If there are no shortcode tags defined, then the content will be returned without any filtering. This might cause issues when plugins are disabled but the shortcode will still show up in the post or content.

Parameters

$contentstringrequired: Content to search for shortcodes.
$ignore_htmlbooloptional: When true, shortcodes inside HTML elements will be skipped.

Default:false

Return

string Content with shortcodes filtered out.

More Information

If there are no shortcode tags defined, then the content will be returned without any filtering. This might cause issues if a plugin is disabled as its shortcode will still show up in the post or content.

Source

function do_shortcode( $content, $ignore_html = false ) {
	global $shortcode_tags;

	if ( ! str_contains( $content, '[' ) ) {
		return $content;
	}

	if ( empty( $shortcode_tags ) || ! is_array( $shortcode_tags ) ) {
		return $content;
	}

	// Find all registered tag names in $content.
	preg_match_all( '@[([^<>&/[]x00-x20=]++)@', $content, $matches );
	$tagnames = array_intersect( array_keys( $shortcode_tags ), $matches[1] );

	if ( empty( $tagnames ) ) {
		return $content;
	}

	// Ensure this context is only added once if shortcodes are nested.
	$has_filter   = has_filter( 'wp_get_attachment_image_context', '_filter_do_shortcode_context' );
	$filter_added = false;

	if ( ! $has_filter ) {
		$filter_added = add_filter( 'wp_get_attachment_image_context', '_filter_do_shortcode_context' );
	}

	$content = do_shortcodes_in_html_tags( $content, $ignore_html, $tagnames );

	$pattern = get_shortcode_regex( $tagnames );
	$content = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $content );

	// Always restore square braces so we don't break things like <!--[if IE ]>.
	$content = unescape_invalid_shortcodes( $content );

	// Only remove the filter if it was added in this scope.
	if ( $filter_added ) {
		remove_filter( 'wp_get_attachment_image_context', '_filter_do_shortcode_context' );
	}

	return $content;
}

View all references View on Trac View on GitHub

Uses	Description
do_shortcodes_in_html_tags()`wp-includes/shortcodes.php`	Searches only inside HTML elements for shortcodes and process them.
unescape_invalid_shortcodes()`wp-includes/shortcodes.php`	Removes placeholders added by do_shortcodes_in_html_tags() .
get_shortcode_regex()`wp-includes/shortcodes.php`	Retrieves the shortcode regular expression for searching.
has_filter()`wp-includes/plugin.php`	Checks if any filter has been registered for a hook.
add_filter()`wp-includes/plugin.php`	Adds a callback function to a filter hook.
remove_filter()`wp-includes/plugin.php`	Removes a callback function from a filter hook.

Show 2 more Show less

Used by	Description
get_the_block_template_html()`wp-includes/block-template.php`	Returns the markup for the current template.
apply_shortcodes()`wp-includes/shortcodes.php`	Searches content for shortcodes and filter shortcodes through their hooks.
wp_ajax_parse_embed()`wp-admin/includes/ajax-actions.php`	Applies Ajax handlers to a string.
wp_ajax_parse_media_shortcode()`wp-admin/includes/ajax-actions.php`
WP_Widget_Text::widget()`wp-includes/widgets/class-wp-widget-text.php`	Outputs the content for the current Text widget instance.
WP_Embed::run_shortcode()`wp-includes/class-wp-embed.php`	Processes the shortcode.
img_caption_shortcode()`wp-includes/media.php`	Builds the Caption shortcode output.

Show 2 more Show less

Changelog

Version	Description
2.5.0	Introduced.

User Contributed Notes

Skip to note 10 content

Codex

11 years ago

// Use shortcode in a PHP file (outside the post editor).
echo do_shortcode( '' );

// In case there is opening and closing shortcode.
echo do_shortcode( '[iscorrect]' . $text_to_be_wrapped_in_shortcode . '[/iscorrect]' );

// Enable the use of shortcodes in text widgets.
add_filter( 'widget_text', 'do_shortcode' );

// Use shortcodes in form like Landing Page Template.
echo do_shortcode( '[contact-form-7 id="91" title="quote"]' );

// Store the short code in a variable.
$var = do_shortcode( '' );
echo $var;

Skip to note 11 content

pansotdev

9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 41You must log in to vote on the helpfulness of this note
The most common use of the shortcode is the following
Log in to add feedback
Skip to note 12 content

Ken Dirschl

10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 22You must log in to vote on the helpfulness of this note

Square brackets are required to echo the shortcode, not just the name of the shortcode.

echo do_shortcode( ' [my_shortcode] ' );

This is not clear in the example.

Log in to add feedback

Skip to note 13 content

Ismail

10 years ago

Example

// Making your custom string parses shortcode
$string = do_shortcode( $string );
// If your string has a custom filter, add its tag name in an applicable add_filter function
add_filter( 'my_string_filter_hook_tag_name', 'do_shortcode' );

Skip to note 14 content

WP SITES

9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
Hook shortcode in single posts
```
add_action( 'loop_start', 'shortcode_before_entry' );

function shortcode_before_entry() {

    if ( ! is_singular( 'post' )  ) {
		return;
	}

    echo do_shortcode('[your_shortcode_handle]');
	
}
```
Log in to add feedback

Skip to note 15 content

damianc

8 years ago

To only allow specific shortcodes in comments:

add_filter('get_comment_text', function ($comment) {
    $finalComment = '';
    $allowed = ['snippet', 'quote'];
    $parts = preg_split('/([/?w+])/', $comment, null, PREG_SPLIT_DELIM_CAPTURE);

    for ($i = 0; $i < sizeof($parts); $i++) {
        if (preg_match('/[w+]/', $parts[$i])) {
            $shortcodeName = substr($parts[$i], 1, -1);
            if (in_array($shortcodeName, $allowed)) {
                $finalComment .= do_shortcode($parts[$i] . $parts[$i+1] . $parts[$i+2]);
                echo '++' . $parts[$i] . $parts[$i+1] . $parts[$i+2] . '++' . $i;
                $i += 2;
            } else {
               $finalComment .= $parts[$i];  
            }
        } else {
            $finalComment .= $parts[$i];
        }
    }
    return $finalComment;
});

Skip to note 16 content

Tuts Insider

4 years ago

An easy approach to defining and using shortcode.

function wpdocs_custom_shortcode ( $content = null ) {
	
	/*------Declare Variables------*/
	$part_1 = $part_2 = $part_3 = $part_4 = $part_5 = '';

	/*------Starting Portion------*/
	$part_1 .= '<div class="content-wrapper">';
	$part_2 .= '<h3 class="content-heading">Here is a heading</h3>';
	$part_3 .= '<div class="content-output">';

	/*------Ending Portion------*/
	$part_4 .= '</div>';
	$part_5 .= '</div>';
	
	/*------Return------*/
	return $part_1 . $part_2 . $part_3 . do_shortcode( $content ) . $part_4 . $part_5; 
}
/*------Register Shortcode------*/
add_shortcode( 'shortcode_name', 'wpdocs_custom_shortcode' );

Now you can use [shortcode_name]........ your content ........ [/shortcode_name] in your post editor.

Skip to note 17 content

Alvaro Torres

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
Sometimes could be really useful to have a shortcode inside another:
```
function wpdocs_concat_shortcodes() {
    $output = 'My new shortcode';

    // Add the old shortcode to the new one
    return do_shortcode( '[wpdocs_box]' ) . $output;
    
}
add_shortcode( 'wpdocs_both_shortcodes', 'wpdocs_concat_shortcodes' );
```
Log in to add feedback
Skip to note 18 content

damianc

8 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
To allow shortcodes in comments:
```
function shortcodify($comment) {
  return do_shortcode($comment);
}

add_filter('comment_text', shortcodify);
add_filter('get_comment_text', shortcodify);
```
Log in to add feedback

云策 WordPress 开发者社区

函数文档