当前浏览:首页 / WordPress函数 / add_shortcode()

add_shortcode( string $tag, callable $callback )

添加新的短代码

addmore...

shortcode 短码


描述

应注意通过前缀或其他方式确保添加的短代码标签是唯一的,并且不会与其他已添加的短码标签冲突。如果标签重复,则以最后加载的标签为准。


参数

$tag

(string)(必填) 要在文章内容中搜索的短码标签。

$callback

(callable)(必填) 找到短码时要运行的回调函数。默认情况下,每个短代码回调都会传递三个参数,包括一个属性数组($atts)、短码内容,如果未设置则为null($content),最后是短码标签本身($shortcode_tag)。


更多信息

短代码回调将传递三个参数:短代码属性、短代码内容(如果有)和短代码名称。

每个短代码只能有一个钩子。这意味着,如果另一个插件具有类似的短代码,它将覆盖您的短代码或者被您覆盖,这取决于插件的引入顺序。

在将短代码属性名称传递到处理程序函数之前,它们始终转换为小写。值未被触及。

请注意,由短码调用的函数不应产生任何类型的输出。短代码函数应返回用于替换短码的文本。直接生成输出将导致意外结果。这类似于过滤器函数的行为方式,因为它们不应在调用中产生意外的副作用,因为您无法控制从何时何地调用它们。



源码

查看源码 官方文档


更新日志

版本描述
2.5.0开始引入

使用示例

  • 示例1

    举例

    使用API的短代码标签的最简单示例:[footag foo="bar"]

    add_shortcode( 'footag', 'wpdocs_footag_func' );
    function wpdocs_footag_func( $atts ) {
    	return "foo = {$atts['foo']}";
    }
    

    具有良好属性默认值的示例:[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']}";
    }
    

    包含封闭内容的示例:[baztag]content[/baztag]

    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";
    	}
    }
    
  • 示例2

    在插件中添加`add_shortcode()`函数时,最好将其添加到一个连接到`init`钩子的函数中,以便WordPress有时间正确初始化。

    add_action( 'init', 'wpdocs_add_custom_shortcode' );
    
    function wpdocs_add_custom_shortcode() {
    	add_shortcode( 'footag', 'wpdocs_footag_func' );
    }
    

    插件手册中所述。

  • 示例3

    对于wppb插件样板,我将代码添加到define_public_hooks()
    $this->loader->add_action( 'init', $plugin_public, 'register_shortcodes' );

    然后在公用文件夹class_public文件中,我添加了:

    public function register_shortcodes(){
    
    		add_shortcode( 'sample-shortcode','shortcode_function'  );
    		function shortcode_function(  ) {
    			return "Hello Shortcode";
    		}
    	}
    
  • 示例4

    使用get_template_part函数包含模板的add_shortcode函数示例。

    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' );
  • 示例5

    注意,如果短代码中没有设置属性,则传递给回调的第一个参数是空字符串。因此类型声明将失败:

    “致命错误:未捕获错误:传递给shortcode_callback()的参数1必须是数组类型,给定字符串”

    使用检查$arguments是否是数组,如果不是,则用空数组替换它:

    function shortcode_callback( $attributes, string $content, string $shortcode ) {
    	if ( ! is_array( $attributes ) ) {
    		$attributes = [];
    	}
    	
    	// do stuff
    }
  • 示例6

    $atts: 属性的关联数组,你可以在任何地方访问该关联数组。
    $content: 封闭的内容(如果短码以其封闭的形式使用)

    /**
     * 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' );