WordPress 函数:add_shortcode

添加一个新的 Shortcode(短代码)标签。

用法

<?php add_shortcode( $tag , $func ); ?>

参数

$tag
(string) (required) Shortcode 短代码名称。
Default: None

$func
(callable) (required) 短代码对应的 hook 函数,也就是找到 Shortcode 标签时候处理的函数。
Default: None

返回值

实例

下面的例子是我写的一个插件,无需输入 <li> 和 </li> HTML 标签,使用 Shortcode 快速输入列表:

[list type="order"]
item-a
item-b
item-c
[/list]

内容中的每一行为列表中的一个元素,并且有个 type 的属性,默认为 0,如果为“order”,则为有序列表:

function wpjam_list_shortcode_handler( $atts, $content='' ) {
    extract( shortcode_atts( array(
        'type' => '0'
    ), $atts ) );

    $lists = explode("\n", $content);

    $ouput = '';
    foreach($lists as $li){
        if(trim($li) != '') {
            $output .= "<li>{$li}</li>\n";            
        }
    }

    if($type=="order"){
        $output = "<ol>\n".$output."</ol>\n";
    }else{
        $output = "<ul>\n".$output."</ul>\n";
    }

    return $output;
}
add_shortcode( 'list', 'wpjam_list_shortcode_handler' );

如果插件设计成一个 class,可以通过下面的方式调用:

add_shortcode( 'list', array('MyPlugin', 'wpjam_list_shortcode_handler') );

注解

每个 Shortcode(短代码)只能有一个对应的 Hook 函数,这就意味着,如果另外一个插件,也有同样的短代码,就会覆盖你的短代码,或者你的覆盖它的,到底谁覆盖谁取决于你和他的插件那个后导入。

短代码的属性名字在传递给对应处理函数之前会被转换成小写,但是属性值将不会改动。

需要注意的是短代码的处理函数不应该直接输出,而应该返回文本用来替换短代码本身,如果直接输出将会导致不可预期的结果。短代码的处理函数和 WordPress 的 filter 函数的行为类似,都是不会直接输出,而是返回文本。

修改记录

Since: 2.5

源文件

wp-includes/shortcodes.php

点赞