【转载】WordPress中的简码机制

http://cn.yflying.com/2010/07/wordpress%E4%B8%AD%E7%9A%84%E7%AE%80%E7%A0%81%E6%9C%BA%E5%88%B6/

简码API（应用程序接口）是WordPress >=2.5的新功能。简码API是一个简单的函数集，这些函数创建宏代码以供在文章内容中使用。
简码示例

下面示例中的每一行都是一个简码，分别展示了简码的各种不同的形式。
1
2
3
4
5
6
[mycode]
[mycode foo="bar" id="123" color="red" something="data"]
[mycode]Some Content[/mycode]
[mycode]<p><a href="http://example.com/">HTML Content</a></p>[/mycode]
[mycode]Content [another-shotcode] more content[/mycode]
[mycode foo="bar" id="123"]Some Content[/mycode]
简码API/函数

以下简码API函数可用：
add_shortcode($tag, $func)，注册新的简码。$tag是用户所编写的简码字符串（无括号），如”my-shortcode”。$func是处理函数的函数名称。在一个已知简码中只能存在一个处理函数。用$tag名称再次调用add_shortcode()会改写原有处理函数。
remove_shortcode($tag)，注销该简码。$tag是用在add_shortcode()中的简码名称。
remove_all_shortcodes()，注销所有的简码。
shortcode_atts($pairs, $atts)，对简码的属性进行解析，$pairs指定了一组关键字和默认值，$atts是需要进行解析的参数。 结果包括$pairs中每个关键字，并混合了$atts的返回值。任何存在于$atts但不存在于$pairs的关键字都将被忽略。
do_shortcode($content)，解析 $content字符串中所有已知简码宏。返回含有原始内容的字符串，并用处理函数的输出结果代替简码宏。do_shortcode()是’the_content’上一个优先级为11的默认过滤器：add_filter(‘the_content’, ‘do_shortcode’, 11); // From shortcodes.php。
简码API对所有简码进行解析，避免为每个简码编写自定义的正则表达式。并且如果存在属性和内容，简码还会将这些属性和内容逐一进行解析， 最后将这些属性和内容传递给相应的简码处理函数。简码处理器返回的字符串被插入文章正文，取代简码。
API同时支持封闭简码和自闭（自动封闭）简码，其他功能还包括：
解析器支持xhtml样式的封闭简码，如”[my-shortcode /]“等，该功能可选。
简码宏可能为属性值使用单个或双个引用，若属性值中没有空格，可以完全不使用引用。 [my-shortcode foo='123' bar=456] 等于 [my-shortcode foo="123" bar="456"]。
考虑到原有简码的兼容性，属性名称会被忽略。若某属性没有名称，系统会将$atts数组中的一个位置数值型关键字作为属性名称。例如，[my-shortcode 123]会生成$atts = array( 0 => 123 )。位置属性与有名称的属性可能混杂在一起，若属性值中含有空格或其它明显字符，可以使用引用。
简码API有测试实例。测试中包括错误情况示例和异常语句，可在此试用测试实例。
动手编写简码

实现一个简码主要包括两个部分：a)实现简码处理函数；b)将简码添加到记录。如下：
1
2
3
4
5
6
7
8
9
function my_shortcode_handler( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'attr_1' => 'attribute 1 default',
      'attr_2' => 'attribute 2 default',
      // ...etc
      ), $atts ) );
    return "<h2>Attributes</h2>" . print_r($attr, true) . "<h2>content</h2>" . $content;
}
add_shortcode('my-shortcode', 'my_shortcode_handler');
这样在显示the_content时，会触发”the_content”钩子上的filter，相应此简码处理函数也会被调用。
属性

原始$atts数组中可能包含用户所指定的任意自由属性。API中的shortcode_atts()函数可为丢失属性设置默认值，并消除简码不可识别的属性。shortcode_atts()函数类似于wp_parse_args()函数，但与wp_parse_args()仍有一些主要差异。shortcode_atts()函数的参数为：
1
shortcode_atts( $defaults_array, $atts );
两个参数都是必需的。 $defaults_array 是一个关联数组，它规定了所识别出属性的名称和默认值。$atts是传递到简码处理器时的原始属性。 shortcode_atts()将返回一个正规的、包括 $defaults_array中所有关键字的数组， 若$atts数组存在， $atts返回的值将被填入$defaults_array。例如：
1
2
3
4
$a = shortcode_atts( array(
   'title' => 'My Title'
   'foo' => 123,
   ), $atts );
如果$atts 中要包括数组( ‘foo’ => 456, ‘bar’ => ‘something’ )， 原有结果$a将会变为数组( ‘title’ => ‘My Title’, ‘foo’ => 456 )。$atts['foo']的值改写了默认值123。由于未设置$atts['title']，’My Title’ 将被作为默认值。默认数组中没有“bar”选项，因此返回的结果中也没有这个选项。
将属性名称传递到处理函数前，需要将名称转换为小写字母。属性值无需改变。 [my-shortcode FOO="BAR"]将会生成$atts = array( ‘foo’ => ‘BAR’ )。属性结果将存储（使用extract()）在以属性关键字 $attr_1, $attr_2命名的本地变量中。 换言之， 默认值数组近似于本地变量声明列表。（在此情况下可安全使用extract()处理各种冲突而无须特别标识，这是因为shortcode_atts()将清除默认数组外所有关键字。）
输出

简码处理函数的返回值将被插入文章内容，代替原有简码宏的位置。
应用 wpautop与wptexturize 文章格式后，简码会被解析。这就意味着，简码HTML输出不能自动使用引用，也不能自动添加p标签以及br标签。如果用户希望预先设定简码输出格式，可以在从简码处理器返回输出结果时直接调用wpautop() 或 wptexturize()。
wpautop辨别简码语句并试图不包装独立成行的p标签以及br标签。若以这种方式使用简码，应确保用相应的block标签包装输出结果。
嵌套处理

简码API默认是不会处理嵌套简码，处于内层的简码会被当作外层简码的普通内容来处理。但是，如果你想是自己的简码支持嵌套，可以通过递归调用do_shortcode()实现，示例如下：
1
2
3
4
5
6
7
8
9
function my_shortcode_handler( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'attr_1' => 'attribute 1 default',
      'attr_2' => 'attribute 2 default',
      // ...etc
      ), $atts ) );
    return "<h2>Attributes</h2>" . print_r($attr, true) . "<h2>content</h2>" . do_shortcode($content);
}
add_shortcode('my-shortcode', 'my_shortcode_handler');
局限

当简码处理函数递归调用do_shortcode()时，简码解析器才可正确处理嵌套简码宏：
1
2
3
4
5
[tag-a]
   [tab-b]
      [tag-c]
   [/tag-b]
[/tag-a]
递归调用的同时，如果使用简码宏来关闭另一个宏，解析器将不能成功解析：
1
2
3
4
[tag-a]
   [tag-a]
   [/tag-a]
[/tag-a]
这就是do_shortcode()所使用的上下文无关的正则表达式解析器的局限性——运行速度快，但不能计算嵌套级别，因此解析器不能正确匹配所有开放标签与相应的关闭标签。