简码API

简码API

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

简码API简化了支持属性的简码的创建：

API进行所有解析，避免为每个简码编写自定义正则表达式。添加帮助函数以设置并获取默认属性。API同时支持封闭简码和自闭（自动封闭）简码。

下面是一个通过属性创建简码的PHP简单实例，为大家提供快速入门通道：

// [bartag foo="foo-value"]
function bartag_func($atts) {
	extract(shortcode_atts(array(
		'foo' => 'no foo',
		'bar' => 'default bar',
	), $atts));

	return "foo = {$foo}";
}
add_shortcode('bartag', 'bartag_func');

以上实例生成一个”[bartag]”简码，该简码支持两个属性：[bartag foo=”something” bar=”something else”]。这是两个可选属性，若用户未选择，属性使用默认选项。

简码API概述

简码由处理函数编写。简码处理器与WordPress过滤器大致相同：两者都接收参数（属性）并返回结果（简码输出）。

add_shortcode()函数用于记录简码处理器。该函数使用两个参数：简码名称（文章正文中所用的字符串）以及处理函数名称。

简码处理函数可接收一到两个属性：属性数组$atts以及封闭文本$content（根据简码是否可用于封闭形式选择性使用该属性）。例如：

function my_shortcode_handler($atts, $content=null) {  
}  

调用API以记录简码处理器，操作如下：

add_shortcode('my-shortcode', 'my_shortcode_handler');  

显示 the_content时，简码API会对所有有记录的简码（如 “[my-shortcode]”）进行解析。如果存在属性和内容，简码还会将这些属性和内容逐一分开并进行解析， 最后将相应的简码处理函数传递给这些属性和内容。简码处理器返回（非响应）的字符串被插入文章正文，取代简码。

以下简码属性：

[my-shortcode foo="bar" baz="bing"]  

将被转换为以下关联数组并传递给处理函数，即$atts参数：

array( 'foo' => 'bar', 'baz' => 'bing')  

数组关键字为属性名称，数组值即相应的属性值。

属性

原始$atts数组中可能包含用户所指定的任意自由属性。API中的shortcode_atts()函数可帮助丢失属性设置默认值，并消除简码不可识别的属性。

shortcode_atts()函数类似于wp_parse_args()函数，但与wp_parse_args()仍有一些主要差异。shortcode_atts()函数的参数为：

shortcode_atts( $defaults_array, $atts );  

两个参数都是必需的。 $defaults_array 是一个关联数组，它规定了所识别出属性的名称和默认值。$atts是传递到简码处理器时的原始属性。 shortcode_atts()将返回一个正规的、包括 $defaults_array中所有关键字的数组， 若$atts数组存在， $atts返回的值将被填入$defaults_array。例如：

$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’ )。

在简码处理器重声明默认值以及解析属性时，建议使用代码方式为：

function my_shortcode_handler( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'attr_1' => 'attribute 1 default',
      'attr_2' => 'attribute 2 default',
      // ...etc
      ), $atts ) );
}

这样既可以解析属性，设置默认值，又可以删除所有不支持的属性，将结果存储（使用extract()）在以属性关键字 $attr_1, $attr_2命名的本地变量中，等等。 换言之， 默认值数组近似于本地变量声明列表。（在此情况下可安全使用extract()处理各种冲突而无须特别标识，这是因为shortcode_atts()将清除默认数组外所有关键字。）

输出

简码处理函数的返回值将被插入文章内容，代替原有简码宏的位置。记住使用“返回”，而非“响应”——所有“响应”内容都会输出到浏览器而不会出现在页面的相应位置上。

应用 wpautop与wptexturize 文章格式（关于2.5.0与2.5.1版本的不同之处，请留意下文中的“注意”）后，简码会被解析。这就意味着，简码HTML输出不能自动使用引用，也不能自动添加p标签以及br标签。如果用户希望预先设定简码输出格式，可以在从简码处理器返回输出结果时直接调用wpautop() 或 wptexturize()。

wpautop辨别简码语句并试图不包装独立成行的p标签以及br标签。若以这种方式使用简码，应确保用相应的block标签包装输出结果，如<p>或 <div>。

注意：在WordPress 2.5.0中，应用文章格式前就会解析简码，因此简码HTML输出有时会被p标签或br标签包裹。WordPress 2.5.1修正了这一缺陷。

封闭简码VS自动封闭简码

以上示例显示的都是自动封闭的代码宏，如 [my-shortcode]。API也支持 [my-shortcode]content[/my-shortcode]等封闭简码。

用简码宏关闭内容时，处理函数会接收另一个包含内容的参数。用户可能会用另一种方式来编写简码，因此程序需要能够同时允许大小写字母，通过设置处理函数的第二个参数默认值，可以实现这一功能：

function my_shortcode_handler( $atts, $content = null )  

is_null($content)可分辨自动封闭标签和封闭标签。

文章内容关闭后，函数输出结果将取代含有内容的完整简码宏。处理函数需要提供原始内容字符串的缺失情况以及加密情况，并在结果中加入缺失或加密的字符串。

以下是加密简码的简单示例：

function caption_shortcode( $atts, $content = null ) {
   return '<span class="caption">' . $content . '</span>';
}

add_shortcode('caption', 'caption_shortcode');  

使用以下方式时：

My Caption  

输出结果则是：

<span class="caption">My Caption</span>  

$content没有缺失也没有加密，因此用户可以加入原始HTML：

<a href="http://example.com/">My Caption</a>  

这将生成：

<span class="caption"><a href="http://example.com/">My Caption</a></span>  

这可能是有意识行为，也可能不是——若简码不允许在结果中输出原始HTML，可在返回结果前用缺失或过滤函数进行处理。

简码解析器不支持嵌套简码。这表示，如果简码处理器的$content参数含有其他简码，将不解析简码：

Caption: [my-shortcode]  

这会生成：

<span class="caption">Caption: [my-shortcode]</span>  

若封闭简码希望允许输出结果出现其他简码，处理函数可递归调用do_shortcode()：

function caption_shortcode( $atts, $content = null ) {
   return '<span class="caption">' . do_shortcode($content) . '</span>';
}

以上代码可保证封闭内容中的 “[my-shortcode]”宏被解析，且输出结果被标题span关闭：

<span class="caption">Caption: The result of my-shortcode's handler function</span>  

封闭简码支持属性的方式与自动封闭简码相同。以下是可支持“class”属性的caption_shortcode()示例：

function caption_shortcode( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'class' => 'caption',
      ), $atts ) );
 
   return '<span class="' . attribtue_escape($caption) . '">' . $content . '</span>';
}

My Caption  

<span class="headline">My Caption</span>  

其他功能简介

• 解析器支持xhtml样式的封闭简码，如”[my-shortcode /]”等，该功能可选
• 简码宏可能为属性值使用单个或双个引用，若属性值中没有空格，可以完全不使用引用。 [my-shortcode foo=’123′ bar=456] 等于 [my-shortcode foo=”123″ bar=”456″]。
• 考虑到原有简码的兼容性，属性名称会被忽略。若某属性没有名称，系统会将$atts数组中的一个位置数值型关键字作为属性名称。例如，[my-shortcode 123]会生成$atts = array( 0 => 123 )。位置属性与有名称的属性可能混杂在一起，若属性值中含有空格或其它明显字符，可以使用引用。
• 简码API有测试实例。测试中包括错误情况示例和异常语句，可在http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php试用测试实例。

函数引用

以下简码API函数可用：

function add_shortcode($tag, $func)  

记录新的简码处理函数。$tag是用户所编写的简码字符串（无括号），如”my-shortcode”。$func是处理函数的函数名称。

在一个已知简码中只能存在一个处理函数。用$tag名称再次调用add_shortcode()会改写原有处理函数。

function remove_shortcode($tag)  

删除已有简码的记录。$tag是用在add_shortcode()中的简码名称。

function remove_all_shortcodes()  

删除所有简码的记录：

function shortcode_atts($pairs, $atts)  

为了$pairs所指定的默认值，对属性原始数组$atts进行操作。 结果包括$pairs中每个关键字，并混合了$atts的返回值。任何存在于$atts但不存在于$pairs的关键字都将被忽略。

function do_shortcode($content)  

解析 $content字符串中所有已知简码宏。返回含有原始内容的字符串，并用处理函数的输出结果代替简码宏。

记录do_shortcode()时，将它作为 一个优先级为11的’the_content’默认过滤器。

局限

当简码处理函数递归调用do_shortcode()时，简码解析器才可正确处理嵌套简码宏：

[tag-a]
   [tab-b]
      [tag-c]
   [/tag-b]
[/tag-a]

递归调用的同时，如果使用简码宏来关闭另一个宏，解析器将不能成功解析：

[tag-a]
   [tag-a]
   [/tag-a]
[/tag-a]

这就是do_shortcode()所使用的上下文无关的正则表达式解析器的局限性——运行速度快，但不能计算嵌套级别，因此解析器不能正确匹配所有开放标签与相应的关闭标签。

外部资源

• Shortcode summary by Aaron D. Campbell ——介绍简码并给出若干使用实例
• WordPress Shortcode API Overview ——详细介绍使用简码的插件的用法，并给出示例
• Simple shortcode-powered BBCode plugin ——介绍一款简单插件，该插件通过简码获取BBcode支持。这是了解运行简码的好方法。

分类：中文手册