短码
主题
短代码API
的商家API是创建WordPress的一组简单的函数短码用于文章和页面。例如，下面的短代码(在一篇文章或页面的主体)将添加一个图片库附加到该文章或页面:<代码>(画廊)
该API允许插件开发者创建特殊类型的内容(例如表单、内容生成器)，用户可以通过在页面文本中添加相应的短代码来附加到特定页面。
Shortcode API可以很容易地创建支持如下属性的Shortcode:
[gallery id="123" size="medium"]
该API处理所有棘手的解析，消除了为每个短代码编写自定义正则表达式的需要。帮助函数用于设置和获取默认属性。该API同时支持自关闭和封装短代码。
作为那些匆忙的人的快速入门，下面是创建短代码所需的PHP代码的一个最小示例:
// [foobar]函数wporg_foobar_func($atts){返回"foo和bar";} add_shortcode('foobar'， 'wporg_foobar_func');
这将创建<代码>(foobar)返回为:foo和bar的短代码
属性:
// [bartag foo="foo-value"]函数bartag_func($atts) {$a = shortcode_atts(数组('foo' => '东西'，'bar' => '其他东西'，)，$atts);返回"foo = {$a['foo']}";} add_shortcode('bartag'， 'bartag_func');
这将创建一个<代码>(bartag)支持两个属性的Shortcode:“foo”和“bar”。这两个属性都是可选的，并采用默认选项<代码>(foo = "东西"栏=“别的东西”]如果没有提供。短代码将返回为<代码>Foo = {Foo属性的值}．
历史
Shortcode API是在WordPress 2.5中引入的。
概述
短代码是通过提供一个处理函数来编写的。Shortcode处理程序与WordPress过滤器非常相似:它们接受参数(属性)并返回结果(Shortcode输出)。
短代码的名称应该是所有小写字母和使用所有字母，但数字和下划线也应该很好。小心使用连字符(破折号)，不使用它们会更好。
的<代码>add_shortcode函数用于注册一个简短代码处理程序。它接受两个参数:shortcode名称(在邮件主体中使用的字符串)和回调函数名称。
三个参数被传递给shortcode回调函数。您可以选择使用其中任何一个，包括不使用任何一个。
丙氨酸美元:属性的关联数组，如果没有给出属性，则为空字符串美元的内容:包含的内容(如果短代码以包含的形式使用)美元的标记: shortcode标签，用于共享回调函数
注册shortcode处理程序的API调用看起来像这样:
Add_shortcode ('wporgshortcode'， 'wporg_shortcode_handler');
当the_content， shortcode API将解析任何注册的短代码，如<代码>(myshortcode)，分离并解析属性和内容(如果有的话)，并将它们传递给相应的shortcode处理函数。任何字符串返回(没有响应)的短代码处理程序将插入到邮件主体取代短代码本身。
Shortcode属性是这样输入的:
[wporgshortcode foo =“酒吧”栏= "必应"]
这些属性将被转换成如下所示的关联数组，并传递给处理程序函数<代码>丙氨酸美元参数:
数组('foo' => 'bar'， 'bar' => 'bing')
数组键是属性名;数组值是对应的属性值。此外，零项(<代码>美元att [0])将保存匹配shortcode regex的字符串，但仅当它与回调名称不同时。
处理属性
原始的<代码>丙氨酸美元数组可以包含用户指定的任意属性。(此外，数组的zeroeth项可能包含regex识别的字符串;参见下面的说明。)
为了帮助为缺失的属性设置默认值，并消除短代码无法识别的任何属性，该API提供了一个shortcode_atts ()函数。
shortcode_atts ()类似于<代码>wp_parse_args函数，但有一些重要的区别。它的参数是:
Shortcode_atts ($defaults_array， $atts);
这两个参数都是必需的。<代码>defaults_array美元是一个关联数组，它指定可识别的属性名称及其默认值。<代码>丙氨酸美元是传递给短代码处理程序的原始属性数组。<代码>shortcode_atts ()将返回包含所有键的规范化数组<代码>defaults_array美元的值填充<代码>丙氨酸美元如果存在数组。例如:
$a = shortcode_atts(数组('title' => '我的标题'，'foo' => 123，)， $atts);
如果<代码>丙氨酸美元要包含<代码>数组('foo' => 456， 'bar' => 'something'),由此产生的<代码>美元一个将<代码>数组('title' => 'My title'， 'foo' => 456)．的价值<代码>$ att[“foo”]覆盖默认的123。<代码>$ att['标题']没有设置，所以使用默认的“我的标题”。在默认数组中没有' bar '项，因此它不包含在结果中。
在将属性名称传递给处理函数之前，它们总是被转换为小写。值是不变的。<代码>[myshortcode FOO =“酒吧”)生产<代码>丙氨酸美元＝array('foo' => 'BAR')．
在短代码处理程序中声明默认值和解析属性的建议代码习惯如下:
函数wporg_shortcode_handler($atts， $content = null) {$a = shortcode_atts(数组('attr_1' => '属性1默认'，'attr_2' => '属性2默认'，//…等)，$atts);｝
这将解析属性，设置默认值，消除任何不支持的属性，并将结果存储在名为<代码>美元一个将属性作为键<代码>美元(“attr_1”)，<代码>美元(“attr_2”)等等。换句话说，默认值数组近似于局部变量声明的列表。
重要的是-不要使用驼峰大小写或大写<代码>丙氨酸美元属性名称：
丙氨酸美元值是小写字母的在<代码>短码＿atts (array('attr_1' => 'attr_1 default'， //…等)，$atts)处理过程，所以你可能想只使用小写．
注意混淆正则表达式/回调名称引用:
属性数组的第0项(美元att [0])将包含匹配shortcode regex的字符串，但仅当它与回调名称不同时才会出现，否则将作为回调函数的第三个参数出现。
add_shortcode(“foo”、“foo”);//两个shortcode引用相同的回调add_shortcode('bar'，'foo');产生如下行为:[foo a='b'] ==>回调到:foo(array('a'=>'b')，NULL，"foo");(酒吧= ' c ') = = >回调:foo(数组(0 = > '酒吧',' ' = > ' c '), NULL, " ");
这是令人困惑的，也许反映了一个潜在的错误，但重载回调例程可以正确地确定使用什么shortcode调用它，通过检查回调的第三个参数和zeroeth属性。(有两个短代码引用相同的回调例程不是一个错误，这允许通用代码。)
输出
shortcode处理函数的返回值被插入到post内容输出中，以代替shortcode宏。记住使用返回而不是回显——任何回显的内容都会输出到浏览器，但它不会出现在页面的正确位置．
短代码随后被解析wpautop而且wptexturizePost格式化已应用。这意味着您的短代码输出HTML不会自动应用花引号、添加p和br标记等等。如果您确实希望您的短代码输出被格式化，您应该调用<代码>wpautop()或<代码>wptexturize()当您从短代码处理程序返回输出时直接。
Wpautop能够识别短代码语法，并且不会尝试在单独一行的短代码周围换行p或br标记。以这种方式使用的短代码应该确保输出被包装在适当的块标记中，例如<代码>
或<代码>
如果短代码产生很多HTML，那么<代码>ob_start可以用来捕获输出并将其转换为一个字符串，如下所示:
函数wporg_shortcode() {ob_start();?> <这里>…<？php返回ob_get_clean ();｝
包含短代码与自关闭短代码
上面的例子显示了自关闭短代码宏，例如<代码>(myshortcode)．API还支持封装短代码，例如<代码>(myshortcode)[/ myshortcode]内容．
如果使用一个shortcode宏来封装内容，它的handler函数将接收包含该内容的第二个参数。用户可能会以任何一种形式编写短代码，所以有必要通过为handler函数的第二个参数提供一个默认值来允许这两种情况:
函数wporg_shortcode_handler($atts， $content = null)
空(内容)可以用来区分自闭箱和封闭箱。
当包含内容时，包含其内容的完整短代码宏将被替换为函数输出。处理程序函数负责为原始内容字符串提供任何必要的转义或编码，并将其包含在输出中。
下面是一个包含简短代码的小例子:
函数wporg_caption_shortcode($atts， $content = null){返回''。美元的内容。“< / span >”;} add_shortcode('标题'，'wporg_caption_shortcode');
像这样使用:
[标题]我的标题[/标题)
输出将是:
< span class = "标题" >我的标题< / span >
自<代码>美元的内容包含在返回值中，没有任何转义或编码，用户可以包含原始HTML:
[标题]< a href = " http://example.com/ " >我的标题< / >[/标题)
这将产生:
这可能是也可能不是预期的行为——如果shortcode不允许在其输出中使用原始HTML，它应该在返回结果之前使用转义或过滤函数来处理它。
shortcode解析器对帖子内容使用一次传递。这意味着如果<代码>美元的内容shortcode处理器的参数包含另一个shortcode，它不会被解析:
[标题]标题:[myshortcode][/标题)
这将产生:
< span class = "标题" >标题:[myshortcode] < / span >
如果包含短代码的目的是在其输出中允许其他短代码，则处理程序函数可以调用do_shortcode ()递归地:
函数wporg_caption_shortcode($atts， $content = null){返回''。do_shortcode($内容)。“< / span >”;｝
在前面的示例中，这将确保<代码>(myshortcode)宏在包含的内容中被解析，它的输出由标题跨度括起来:
caption: myshortcode处理函数的结果
解析器不能按您希望的方式处理相同简短代码的封闭和非封闭形式的混合。例如，如果你有:
[/myshortcode示例='non- included ' /]
解析器不是将其视为由文本“非封闭内容”分隔的两个短代码，而是将其视为包含“非封闭内容”的单个短代码<代码>(myshortcode)封闭的内容”。
封闭短代码支持属性的方式与自关闭短代码相同。这里有一个例子<代码>caption_shortcode ()改进为支持' class '属性:
函数wporg_caption_shortcode($atts， $content = null) {$a = shortcode_atts(数组('class' => '标题'，)，$atts);返回'
(标题类= "标题"]我的标题(/标题)
< span class = "标题" >我标题< / span >
其他功能简介
- 解析器支持xhtml样式的关闭短代码，如<代码>(myshortcode /)，但这是可选的。
- Shortcode宏可以对属性值使用单引号或双引号，如果属性值不包含空格，则完全省略它们。<代码>[myshortcode foo = ' 123 '酒吧= 456)相当于<代码>[myshortcode foo = " 123 " bar = " 456 "]．注意，最后一个位置的属性值可能不会以斜杠结束，因为上面段落中的特性将使用这个斜杠。
- 为了向后兼容较早的专用短代码，可以省略属性名称。如果属性没有名称，则将在<代码>丙氨酸美元数组中。例如,<代码>[myshortcode 123]将会产生<代码>丙氨酸美元＝array(0 => 123)．位置属性可以与命名属性混合使用，如果值包含空格或其他重要字符，则可以使用引号。
- shortcode API有测试用例。这些测试包含了许多错误案例和不寻常语法的例子，可以在http://svn.automattic.com/wordpress-tests/trunk/tests/shortcode.php
函数引用
以下是Shortcode API函数:
函数add_shortcode($tag， $func)
注册一个新的短代码处理函数。<代码>美元的标记是由用户编写的短代码字符串(不带大括号)，例如" myshortcode "。$func是处理函数名。
对于给定的短代码，只能存在一个处理函数。调用<代码>add_shortcode()同样，使用相同的$标记名称将覆盖前面的处理程序。
函数remove_shortcode
注销现有的短代码。<代码>美元的标记短代码名称是否与中使用的相同<代码>add_shortcode()．
remove_all_shortcodes()函数
取消所有的商家。
函数shortcode_atts($pairs， $atts)
处理原始属性数组<代码>丙氨酸美元中指定的默认值集<代码>对美元．返回一个数组。结果将包含来自的每个键<代码>对美元，与来自的值合并<代码>丙氨酸美元．任何键<代码>丙氨酸美元$pair中不存在的将被忽略。
函数do_shortcode($content)
中的任何已知短代码宏<代码>美元的内容字符串。返回一个包含原始内容的字符串，其中短代码宏由其处理函数输出替换。
do_shortcode ()注册为' the_content '上的默认过滤器，优先级为11。
限制
嵌套的短码
shortcode解析器正确地处理嵌套的shortcode宏，只要它们的处理函数通过递归调用支持它do_shortcode ()：
[标签-a][标签-b][标签-c][/标签-b][/标签-a]
但是，如果使用一个shortcode宏来包含另一个同名宏，解析器将失败:
[标签-a][标签-a][/标签-a][/标签-a]
所使用的上下文无关的regexp解析器的一个限制<代码>do_shortcode ()-它非常快，但没有计算嵌套的级别，所以在这些情况下，它不能匹配每个开始标签和正确的结束标签。
在未来的WordPress版本中，插件可能需要有嵌套的shortcode语法，以确保雷竞技<代码>wptexturize()处理器不干扰内部代码。对于这种复杂的语法，建议使用no_texturize_shortcodes过滤器应该在外部标签上使用。在这里使用的示例中，应该将标签-a添加到短代码列表中，以避免纹理化。如果标记-a或标记-b的内容仍然需要纹理化，那么您可以调用<代码>wptexturize()在调用之前<代码>do_shortcode ()如上所述。
未登记的名字
一些插件作者选择了不注册短代码名称的策略，例如在父短代码的处理函数被调用之前禁用嵌套短代码。这可能会产生意想不到的后果，例如无法解析shortcode属性值。例如:
(标记单元= "北"][标签大小= " 24 "][tag-c color = "红色"][/标签][/标记]
从版本4.0.1开始，如果插件未能将标签-b和标签-c注册为有效的短代码，则<代码>wptexturize()处理器将在解析任何短代码之前输出以下文本:
(标记单元= "北"][标签大小= " 24 "][tag-c color = "红色"][/标签][/标记]
未注册短代码应该被认为是普通的纯文本，没有特殊的意义，使用未注册短代码的做法是不鼓励的。如果必须在短代码标记之间包含原始代码，至少考虑使用no_texturize_shortcodes防止a标签内容纹理化的过滤器:
Add_shortcode ('tag-a'， 'wporg_tag_a_handler');Add_filter ('no_texturize_shortcodes'， 'wporg_ignore_tag_a');函数wporg_ignore_tag_a($list) {$list[] = '标签-a';返回列表美元;｝
打开短码
在某些情况下，短代码解析器不能正确地处理闭合短代码和非闭合短代码的使用。例如，在本例中，解析器将只正确识别shortcode的第二个实例:
[标签][标签]内容[/标签]
然而，在这种情况下，解析器将识别两者:
[标签]内容[/标签][标签]
连字符
在你的短代码名称中使用连字符时要小心。在下面的例子中，WordPress可能会看到第二个和第一个相同的打开短代码(基本上WordPress看到的是连字符前的第一部分):
[标记][标记]
这完全取决于首先定义哪个短代码。如果你打算使用连字符，那么首先定义最短的短代码。
要避免这种情况，请使用下划线或不使用分隔符:
[tag] [tag_a] [tag] [tag]
如果短代码的第一部分不同，你可以使用连字符:
[标记][tagfoo-a]
重要的是:使用连字符可能有你可能没有意识到的含义;例如，如果其他安装的短代码也使用连字符，使用带有连字符的通用词可能会导致冲突(如果短代码在同一请求中一起使用):
// plugin-A [is-logged-in] // plugin-B [is-admin]
方括号
shortcode解析器不接受属性中的方括号。因此，以下将失败:
(标签属性= "[一些价值]")
被化妆品支架包围的标签还没有被完全支持wptexturize ()或其过滤器。这些代码可能会给出意想不到的结果:
[我在标题附近放了一些随机的文字。[标题]]
注意:这些限制可能会在未来的WordPress版本中改变，你应该测试绝对确定。
超文本标记语言
从3.9.3版本开始，HTML的使用仅限于shortcode属性。例如，此短代码将无法正常工作，因为它包含<代码>>性格:
[tag value1="35" value2="25" compare=">"]
4.0版本的设计是允许验证的HTML，所以这将会工作:
(标签描述= " < / b > " < b >问候)
针对HTML限制的建议解决方案是对所有用户输入使用HTML编码，然后在自定义短代码处理程序中添加HTML解码。计划了额外的API函数。
官方从未支持在短代码属性中完全使用HTML，而且在未来的版本中也不会扩展。
从版本4.2.3开始，在HTML中使用短代码也受到了类似的限制。例如，这个shortcode将无法正常工作，因为它嵌套在脚本属性中:
<一个onclick = "[标记]" >
对于动态属性，建议的解决方案是设计一个短代码，输出所有需要的HTML，而不仅仅是一个值。这样会更好:
[链接onclick = "标签")
还请注意，以下shortcode不再允许，因为不正确的属性引号:
<标题= "[标签attr = " id ") " >
把它解析为有效HTML的唯一方法是嵌套使用单引号和双引号:
<标题= "[标签attr = ' id '] " >
注册数
众所周知，当注册数百个短代码时，API会变得不稳定。插件作者应该创建只依赖少量短代码名称的解决方案。在未来的版本中，这个限制可能会改变。
正式的语法
WordPress短代码不像HTML那样使用特殊字符。方括号乍一看似乎很神奇，但它们并不是任何语言的真正组成部分。例如:
(画廊)
图库短代码被API解析为一个特殊的符号，因为它是一个注册短代码。另一方面，当一个短代码没有注册时，方括号会被忽略:
(randomthing)
随机符号及其方括号将被忽略，因为它们不是任何注册短代码的一部分。
在一个完美的世界里，任何<代码>(*)符号可以由API处理，但我们必须考虑以下挑战:方括号在HTML中是允许的，但并不总是短代码，角括号只在有限的情况下允许在短代码中，所有这些代码在输出之前必须通过多层自定义过滤器和解析器。由于这些语言兼容性问题，方括号并不是什么神奇的东西。
shortcode语法使用了以下通用部分:
(名称属性关闭)
任何HTML或短代码都可以放在这里。
转义的短代码是相同的，但有两个额外的括号:
[[名称属性关闭]]
[[name attributes]任何HTML或短代码都可以在这里。[/name]]
同样，短代码名称必须注册，否则所有四个示例都将被忽略。
的名字
短代码名称不能包含以下字符:
- 方括号内:<代码>[]
- 角括号:<代码><>
- &:<代码>＆
- 斜杠:<代码>/
- 空格:空格换行选项卡
- 打印字符:<代码>\ x00- - - - - -<代码>\ x20
建议还避免在短代码名称中使用引号。
属性
属性是可选的。短码名称和短码属性之间需要有空格。当使用多个属性时，每个属性必须用至少一个空格分隔。
每个属性都应该遵循以下格式之一:
attribute_name =“价值”
attribute_name =“价值”
attribute_name =值
“价值”
价值
属性名称是可选的，为了兼容所有平台，应该只包含以下字符:
- 大写和小写字母:<代码>无所不包的
无所不包的 - 数字:<代码>0 - 9
- 强调:<代码>＿
- 连字符:<代码>-
属性名中不允许有空格。在名称和之间可以使用可选空格<代码>＝的迹象。之间也可以使用可选空格<代码>＝符号和值。
应该注意的是，即使属性在编辑器中可以混合使用大小写，但在解析后它们始终是小写的。
属性值不能包含以下字符:
- 方括号内:<代码>[]
- 报价:<代码>＂，<代码>＇
未加引号的值也不能包含空格。
HTML字符<代码><而且<代码>>在属性中只有有限的支持。
在shortcode属性中转义特殊字符的推荐方法是HTML编码。最重要的是，出现在shortcode属性中的任何用户输入都必须转义或去掉特殊字符。
请注意，允许在单引号值中使用双引号，反之亦然，但在处理用户输入时不建议这样做。
以下字符如果没有在属性值中转义，将被自动剥离并转换为空格:
- 不中断空间:<代码>\ xC2 \ xA0
- 任意空间:<代码>\ xE2 \ x80 \ x8B
自闭
自关闭标记是一个向前斜杠，是可选的。标记前的空格是可选的。标记后面不允许有空格。
(例子/)
自关闭标记纯粹是修饰性的，除了迫使shortcode解析器忽略它后面的任何关闭标记外，没有任何作用。
封装类型短代码不能使用自关闭标记。
逃离
WordPress尝试插入花引号之间<代码>(名字)而且<代码>(/名称)标签。它将像处理其他内容一样处理该内容。在4.0.1中，未注册的短代码也被“纹理化”了，这可能会给出意想不到的花引号:
(randomthing param =“测试”)
一个更好的例子是:
<代码> [randomthing param =“测试”]> < /代码
的<代码><代码>元素总是避免使用花引号。
注册的短代码还在里面处理<代码><代码>元素。要转义在网站上显示的注册短代码，语法如下:
[[标题参数= "测试"]]
将输出:
(标题参数=“测试”)
的<代码><代码>元素在这种情况下是可选的。
对于包含短代码，请使用以下语法:
[[标题]我的标题[/标题]]
外部资源
- WordPress短码生成器
- 添加短代码- WordPress代码片段生成器一个代码片段生成器和完整的文档，关于如何添加代码到WordPress网站。
- 短代码摘要由Aaron D. Campbell-解释短代码并给出示例，包括如何将短代码合并到一个元框中，使用js将它们发送给编辑器。
- 创新的WordPress短代码在行动一个WordPress插件，向你展示如何有效地使用短代码来改变你的帖子内容设计。
- WordPress Shortcode API概述-解释使用短代码插件的用法和示例。
- 简单的短代码支持的BBCode插件-一个简单的插件，通过shortcode添加对BBCode的支持。一个很好的方式来查看短代码的行动。