编辑“WordPress选项API”

<span style="border:1px solid #000; text-align:center; float:right; padding:6px;"><strong>导航:</strong> [[WordPress进阶课题|上一页]] | {{Template:WordPress导航}}</span>
<div style="clear:both;"></div>
==简码API==
简码API（应用程序接口）是WordPress 2.5的新功能。简码API是一个简单的函数集，这些函数创建宏代码以供在文章内容中使用。下面是一个普通简码：

[gallery]  简码API简化了支持属性的简码的创建：
 [gallery id="123" size="medium"]  
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');  
显示[http://codex.wordpress.org/Template_Tags/the_content 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 ) );
 }
这样既可以解析属性，设置默认值，又可以删除所有不支持的属性，将结果存储（使用[http://cn.php.net/extract extract()]）在以属性关键字 $attr_1, $attr_2命名的本地变量中，等等。 换言之， 默认值数组近似于本地变量声明列表。（在此情况下可安全使用extract()处理各种冲突而无须特别标识，这是因为shortcode_atts()将清除默认数组外所有关键字。）

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

应用[http://codex.wordpress.org/Function_Reference/wpautop wpautop]与[http://codex.wordpress.org/Function_Reference/wptexturize 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');  
使用以下方式时：
 [caption]My Caption[/caption]  
输出结果则是：
 <span class="caption">My Caption</span>  
$content没有缺失也没有加密，因此用户可以加入原始HTML：
 [caption]<a href="http://example.com/ ">My Caption</a>[/caption]  
这将生成：
 <span class="caption"><a href="http://example.com/ ">My Caption</a></span>  
这可能是有意识行为，也可能不是——若简码不允许在结果中输出原始HTML，可在返回结果前用缺失或过滤函数进行处理。

简码解析器不支持嵌套简码。这表示，如果简码处理器的$content参数含有其他简码，将不解析简码：
 [caption]Caption: [my-shortcode][/caption]  
这会生成：
 <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>';
 }
 [caption class="headline"]My Caption[/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()所使用的上下文无关的正则表达式解析器的局限性——运行速度快，但不能计算嵌套级别，因此解析器不能正确匹配所有开放标签与相应的关闭标签。

==外部资源==
*[http://xavisys.com/wordpress-25-shortcodes/ Shortcode summary by Aaron D.   Campbell] ——介绍简码并给出若干使用实例   
*[http://planetozh.com/blog/2008/03/wordpress-25-shortcodes-api-overview/ WordPress   Shortcode API Overview] ——详细介绍使用简码的插件的用法，并给出示例   
*[http://wordpress.org/extend/plugins/bbcode/ Simple shortcode-powered   BBCode plugin ]——介绍一款简单插件，该插件通过简码获取BBcode支持。这是了解运行简码的好方法。

==相关条目==
*[[Drupal]] 
*[[OBLOG]] 
*[[X-Space]] 
*[[SaBlog-X]] 
*[[Bo-Blog]]

[[category:WordPress中文文档|A]]
[[category:WordPress网站开发|A]]