语言文字:
英语•意大利•日本語
葡萄牙人做巴西•Русский•(添加您的语言)
短代码API
这个短代码API是创建WordPress的一组简单函数短代码用于帖子和页面。例如，以下短代码（在文章或页面的正文中）将添加附加到该文章或页面上的图像的照片库：[图库]
API使插件开发人员能够创建特殊类型的内容（例如表单、内容生成器），用户可以通过在页面文本中添加相应的短代码来将其附加到某些页面。
短代码API使创建支持以下属性的短代码变得容易：
[画廊id=“123”size=“中等”]
该API处理所有复杂的解析，无需为每个短代码编写自定义正则表达式。包含用于设置和获取默认属性的帮助器函数。API支持自闭和封闭短代码。
作为一个快速入门，这里有一个创建短代码所需的PHP代码的最小示例：
//[foobar]函数foobar_func（$atts）{return“foo和bar”；}add_shortcode（“foobar”，“foobar_func”）；
这将创建返回为：foo和bar的[foobar]短代码
使用属性：
//[bartag foo=“foo-value”]函数bartag_func（$atts）{$a=shortcode_atts（数组(“foo”=>“something”，“bar”=>“其他内容”，)，$atts）；return“foo={$a['foo']}”；}add_shortcode（“bartag”，“bartag_func”）；
这将创建一个支持两个属性的“[bartag]”快捷代码：[“foo”和“bar”]。这两个属性都是可选的，如果没有提供，它们将采用默认选项[foo=“something”bar=“someother”]。短代码将返回foo={foo属性}的值。
概述
短代码是通过提供处理程序函数编写的。短代码处理程序与WordPress过滤器大致相似：它们接受参数（属性）并返回结果（短代码输出）。
短代码名称应全部小写，并使用所有字母，但数字和下划线也应适用。小心使用连字符（破折号），你最好不要使用它们。
这个添加短代码函数用于注册短代码处理程序。它有两个参数：短代码名（post正文中使用的字符串）和回调函数名。
三个参数被传递给短代码回调函数。您可以选择使用任意数量的选项，其中不包括任何选项。
- 美元atts-属性的关联数组，如果没有给定属性，则为空字符串
- $内容-封闭的内容（如果以封闭形式使用短代码）
- $标签-短代码标记，用于共享回调函数
注册短代码处理程序的API调用如下所示：
add_shortcode（'myshortcode'，'my_shortcode_handler'）；
何时_内容显示时，短代码API将解析任何注册的短代码，如“[myshortcode]”，分离并解析属性和内容（如果有），并将其传递给相应的短代码处理程序函数。任何字符串返回短代码处理程序将插入到post正文中，以代替短代码本身。
短代码属性的输入方式如下：
[myshortcode foo=“bar”bar=“bing”]
这些属性将转换为如下关联数组，并作为其美元atts参数：
数组（'foo'=>'bar'，'bar'=>'bing'）
数组键是属性名称；数组值是相应的属性值。此外，零条目($atts[0])将保存与短代码正则表达式匹配的字符串，但仅限于与回调名称不同的情况。请参阅下面关于属性的讨论。
处理属性
生的美元atts数组可以包括用户指定的任何任意属性。（此外，数组的第零项可能包含正则表达式识别的字符串；请参阅下面的注释。）
为了帮助设置缺少属性的默认值，并消除短代码无法识别的任何属性，API提供了shortcode_atts（）函数。
短代码_附件（）类似于wp_parse_args功能，但有一些重要的区别。其参数为：
shortcode_atts（$defaults_array，$atts）；
这两个参数都是必需的。$defaults_array是一个关联数组，用于指定已识别的属性名称及其默认值。$atts（单位：美元）是传递到短代码处理程序中的原始属性数组。短代码_附件（）将返回一个规范化数组，其中包含$defaults_array，用中的值填充美元atts数组（如果存在）。例如：
$a=shortcode_atts（数组('title'=>'My title'，“foo”=>123，)，$atts）；
如果美元atts将包含数组（“foo”=>456，“bar”=>“something”），结果美元将是数组（'title'=>'My title'，'foo'=>456）。的值$atts['fo']美元覆盖默认值123。$atts[标题]未设置，因此使用默认的“我的标题”。默认数组中没有“bar”项，因此它不包含在结果中。
属性名在传递到处理程序函数之前总是转换为小写。值未被修改。[myshortcode FOO=“BAR”]生产$atts=数组（'foo'=>'BAR'）.
在短代码处理程序中声明默认值和解析属性的建议代码习惯用法如下：
函数my_shortcode_handler（$atts，$content=null）{$a=shortcode_atts（数组(“attr_1”=>“属性1默认值”，“attr_2”=>“属性2默认值”，// ...等)，$atts）；}
这将解析属性，设置默认值，消除任何不支持的属性，并将结果存储在名为美元以属性为关键点-$a[属性1'],$a['attr_2']换句话说，默认值数组近似于局部变量声明列表。
- 重要提示-请勿使用camelCase或UPPER-CASE美元atts属性名称
- 美元atts值为小写在期间shortcode_atts（数组（'attr_1'=>'attr_default'，//…etc），$atts）处理，因此您可能希望只使用小写.
- 关于混淆正则表达式/回调名称引用的注意事项
- 属性数组的第零项($atts[0])将包含与短代码正则表达式匹配的字符串，但仅当该字符串与回调名称不同时，回调名称才会显示为回调函数的第三个参数。
- （从2.9.2开始，似乎始终显示为第三个参数。）
add_shortcode（'foo'，'foo]）；//引用同一回调的两个短代码add_shortcode（'bar'，'oo'）；产生此行为：[foo a='b']=>回调到：foo（数组（'a'=>'b'），NULL，“foo”）；[bar a='c']==>回调到：foo（数组（0=>'bar'，'a'=>'c'），NULL，“”）；
这很令人困惑，可能反映了一个潜在的错误，但重载回调例程可以通过检查回调的第三个参数和zeroeth属性来正确确定调用它的短代码。（两个短代码引用同一个回调例程并不是错误，这允许使用通用代码。）
输出
将短代码处理程序函数的返回值插入到post内容输出中，以代替短代码宏。记住使用return而不是echo-任何被回显的内容都会输出到浏览器，但不会出现在页面上的正确位置.
短代码在以下时间后解析wpauto公司和wp织物化已应用帖子格式。这意味着您的短代码输出HTML不会自动应用花引号、添加p和br标记等。如果您确实希望格式化短代码输出，则应在从短代码处理程序返回输出时直接调用wpauto（）或wptexturezation（）。
wpauto识别短代码语法，并将尝试不将p或br标记包装在单独存在于一行上的短代码周围。以这种方式使用的短代码应确保输出包装在适当的块标记中，例如<p>或<div>。
如果短代码生成大量HTML，则可以使用ob_start捕获输出并将其转换为字符串，如下所示：-
函数my_shortcode（）{ob_start（）；？><HTML><此处>…<？php程序返回ob_get_clean（）；}
封闭与自闭短代码
以上示例显示了自动关闭的短代码宏，如[myshortcode]。该API还支持封闭短代码，如[myshortcode]content[/myshortcode]。
如果使用短代码宏来包含内容，则其处理程序函数将接收包含该内容的第二个参数。用户可能会以任何一种形式编写短代码，因此有必要通过为处理程序函数的第二个参数提供默认值来考虑这两种情况：
函数my_shortcode_handler（$atts，$content=null）
空（$content）可用于区分自动关闭和封闭案例。
当包含内容时，包含其内容的完整短代码宏将替换为函数输出。处理程序函数负责提供原始内容字符串的任何必要转义或编码，并将其包含在输出中。
下面是一个简单的封闭短代码示例：
函数caption_shortcode（$atts，$content=null）{return'<span class=“caption”>'$内容。'</span>'；}add_shortcode（'caption'，'caption_shortcode'）；
这样使用时：
[caption]我的字幕[/caption]
输出将是：
我的字幕</span>
由于$content包含在返回值中，没有任何转义或编码，因此用户可以包含原始HTML：
[标题]<a href=“http://example.com/“>我的字幕
这将产生：
<span class=“caption”><a href=“http://example.com/“>我的字幕</a></span>
这可能是有意的行为，也可能不是有意的行为——如果短代码不允许在其输出中使用原始HTML，则应在返回结果之前使用转义或过滤函数来处理它。
短代码解析器对帖子内容使用单次传递。这意味着，如果短代码处理程序的$content参数包含另一个短代码，则不会对其进行解析：
[caption]标题：[myshortcode][/caption]
这将产生：
标题：[myshortcode]</span>
如果封闭的短代码旨在允许其输出中有其他短代码，则处理程序函数可以调用do_shortcode（）递归地：
函数标题_短代码（$atts，$content=null）{return'<span class=“caption”>'。do_shortcode（$content）。”</span>'；}
在前面的示例中，这将确保解析所附内容中的“[myshortcode]”宏，并且其输出由标题span括起来：
caption：myshortcode的handler函数的结果</span>
解析器不会像您希望的那样处理相同短代码的封闭形式和非封闭形式的混合。例如，如果您有：
[myshortcode example='non-enclosuling'/]非封闭内容[myshort code]封闭内容[/myshortcode]
解析器将其视为包含“非封闭内容[myshortcode]封闭内容”的单个短代码，而不是被视为由文本“非封闭的内容”分隔的两个短代码。
封闭短代码支持属性的方式与自闭短代码相同。以下是为支持“class”属性而改进的caption_shortcode（）示例：
函数caption_shortcode（$atts，$content=null）{$a=shortcode_atts（数组(“class”=>“caption”，)，$atts）；return'<span class=“'.esc_attr（$a['class']）.'”>'$内容。'</span>'；}
[caption class=“headline”]我的字幕[/caption]
我的字幕</span>
简要介绍其他功能
- 解析器支持xhtml风格的关闭短代码，如“[myshortcode/]”，但这是可选的。
- 短代码宏可以对属性值使用单引号或双引号，如果属性值不包含空格，则可以完全省略它们。[myshortcode foo='123'bar=456]等同于[myshort code foo=“123”bar=“456”]。请注意，最后一个位置的属性值可能不会以正斜杠结尾，因为上面段落中的功能将使用该斜杠。
- 为了向后兼容旧的ad-hoc短代码，可以省略属性名称。如果属性没有名称，它将在$atts数组中被赋予位置数字键。例如，[myshortcode 123]将生成$atts=array（0=>123）。位置属性可以与命名属性混合，如果值包含空格或其他有效字符，则可以使用引号。
功能参考
以下短代码API函数可用：
函数add_shortcode（$tag，$func）
注册新的短代码处理程序函数$tag是用户编写的短代码字符串（不带大括号），例如“myshortcode”$func是处理程序函数名。
对于给定的短代码，只能存在一个处理程序函数。再次使用相同的$标记名调用add_shortcode（）将覆盖前面的处理程序。
函数remove_shortcode（$tag）
取消注册现有短代码$tag是add_shortcode（）中使用的短代码名称。
函数remove_all_shortcodes（）
取消注册所有短代码。
函数shortcode_atts（$pairs，$atts）
根据$pairs中指定的默认值集处理属性$atts的原始数组。返回数组。结果将包含$pairs中的每个密钥，并与$atts中的值合并。$atts中不存在于$对中的任何密钥都将被忽略。
函数do_shortcode（$content）
分析$content字符串中的任何已知短代码宏。返回包含原始内容的字符串，短代码宏被其处理程序函数的输出替换。
do_shortcode（）注册为“the_content”上的默认过滤器，优先级为11。
限制
嵌套短代码
短代码解析器正确处理嵌套的短代码宏，前提是它们的处理函数通过递归调用来支持它do_shortcode（）:
[标签a][标记-b][标签-c][/tag-b][/tag-a]
但是，如果使用短代码宏来括起另一个同名宏，则解析器将失败：
[标签a][标签a][/tag-a][/tag-a]
这是对使用的无上下文regexp解析器的限制do_shortcode（）-它速度很快，但不计算嵌套级别，因此在这些情况下，它无法将每个开始标记与其正确的结束标记进行匹配。
在WordPress的未来版本中，可能需要具有嵌套短代码语法的插件来确保wptextureze（）处理器不会干扰内部代码。对于如此复杂的语法，建议无纹理_短代码应该在外部标签上使用过滤器。在这里使用的示例中，应将标记a添加到快捷代码列表中，以避免纹理化。如果tag-a或tag-b的内容仍然需要进行纹理处理，则可以调用wptexture（）在呼叫之前do_shortcode（）如上所述。
未注册的名称
一些插件作者选择了不注册短代码名称的策略，例如，在父短代码的处理程序函数被调用之前禁用嵌套的短代码。这可能会产生意想不到的后果，例如无法解析短代码属性值。例如：
[tag-a单元=“北”][tag-b size=“24”][tag-c color=“red”][/tag-b][/tag-a]
从4.0.1版开始，如果插件无法将tag-b和tag-c注册为有效的短代码，wptexturezation（）处理器将在解析任何短代码之前输出以下文本：
[tag-a单元=“北”][标签-b大小=”；24”！][标签-c颜色=”；红色”；][/tag-b][/tag-a]
未注册的短代码应被视为没有特殊含义的普通纯文本，不鼓励使用未注册短代码。如果必须在短代码标记之间包含原始代码，至少可以考虑使用无文本化短代码过滤器，以防止tag-a内容物的组织化：
add_shortcode（'tag-a'，'my_tag_a_handler'）；add_filter（'no_textureza_shortcodes'，'ignore_tag_a'）；函数ignore_tag_a（$list）{$list[]='tag-a'；return$list；}
未关闭的短代码
在某些情况下，短代码解析器无法正确处理闭合和未闭合短代码的使用。例如，在这种情况下，解析器只会正确识别短代码的第二个实例：
[标签][标签]内容[/tag]
然而，在这种情况下，解析器将同时识别：
[标签]内容[/标签][标签]
连字符
注：下面描述的包含连字符（'-'）的短代码的行为仍然适用于WordPress 3+。这可能是由于do_shortcode（）或get_shortcode_regex（）中的错误造成的。
在短代码名称中使用连字符时要小心。在下面的例子中，WordPress可能会看到第二个开头的短代码与第一个相当（基本上WordPres会看到连字符前的第一部分）：
[标签][标签a]
这完全取决于首先定义哪个短代码。如果要使用连字符，请先定义最短的短代码。
要避免这种情况，请使用下划线或不使用分隔符：
[标签][标签a][标签][塔加]
如果短代码的第一部分彼此不同，可以使用连字符：
[标签][标签-a]
重要提示：使用连字符可能会产生您可能不知道的影响；例如，如果其他已安装的短代码也使用连字符，则使用带连字符的通用单词可能会导致冲突（如果短代码在同一请求中一起使用）：
//插件-A[插入]//插件-B[系统管理员]
方括号
短代码分析器不接受属性中的方括号。因此，以下操作将失败：
[tag attribute=“[Some value]”]
wptexturezation（）或其过滤器还不完全支持由示意括号包围的标签。这些代码可能会产生意外结果：
[我将随机文本放在标题附近。[标题]]
注：这些限制可能会在WordPress的未来版本中发生变化，您应该进行测试以确保万无一失。
HTML格式
从版本3.9.3开始，HTML的使用仅限于短代码属性。例如，此短代码将无法正常工作，因为它包含“>”字符：
[tag value1=“35”value2=“25”compare=“>”]
4.0版的设计是为了允许经过验证的HTML，因此这将起作用：
[tag description=“问候语”]
HTML限制的建议解决方法是对所有用户输入使用HTML编码，然后在自定义短代码处理程序中添加HTML解码。计划额外的API功能。
官方从未正式支持在短代码属性中完全使用HTML，并且在未来的版本中也不会对此进行扩展。
从4.2.3版开始，在HTML中使用短代码也受到了类似的限制。例如，此短代码将无法正常工作，因为它嵌套在脚本属性中：
<a onclick=“[tag]”>
对于动态属性，建议的解决方法是设计一个短代码，输出所有需要的HTML，而不仅仅是单个值。这样效果会更好：
[link onclick=“tag”]
还要注意，由于属性引用不正确，不再允许使用以下缩写：
<a title=“[tag attr=”id“]”>
将其解析为有效HTML的唯一方法是以嵌套方式使用单引号和双引号：
<a title=“[tag attr='id']”>
注册计数
众所周知，当注册数百个短代码时，API会变得不稳定。插件作者应该创建只依赖少量短代码名称的解决方案。此限制在未来版本中可能会更改。
形式语法
WordPress的短代码不像HTML那样使用特殊字符。方括号乍一看似乎很神奇，但它们并不是任何语言的真正组成部分。例如：
[图库]
库短代码被API解析为一个特殊符号，因为它是一个注册的短代码。另一方面，如果未注册短代码，则忽略方括号：
[随机事件]
随机符号及其方括号被忽略，因为它们不是任何注册的短代码的一部分。
在理想的情况下，API可以处理任何[*]符号，但我们必须考虑以下挑战：在HTML中允许使用方括号，并不总是短代码，只有在有限的情况下才允许在短代码中使用角括号，所有这些代码在输出之前都必须经过多层可定制的过滤器和解析器。由于这些语言兼容性问题，方括号不可能是神奇的。
短代码语法使用以下通用部分：
[名称属性关闭]
[name attributes]此处可以显示任何HTML或短代码。[/姓名]
转义的短代码是相同的，但正好有两个额外的大括号：
[[name attributes close]]
[[name attributes]此处可以显示任何HTML或短代码。[/姓名]]
同样，必须注册短代码名称，否则将忽略所有四个示例。
姓名
短代码名称不得包含以下字符：
- 方括号：[]
- 角撑：<>
- 与符号：&
- 正斜杠：/
- 空白：空格换行选项卡
- 非打印字符：\x00-\x20
还建议避免在短代码名称中使用引号：
属性
属性是可选的。短代码名称和短代码属性之间需要一个空格。当使用多个属性时，每个属性必须用至少一个空格隔开。
每个属性应符合以下格式之一：
attribute_name=“值”
attribute_name=“值”
attribute_name=值
“价值”
价值
属性名称是可选的，应仅包含以下字符，以便跨所有平台兼容：
- 大小写字母：A-Z A-Z
- 数字：0-9
- 下芯：_
- 连字符：-（4.3.0版之前不允许）
属性名称中不允许使用空格。名称和=号之间可以使用可选空格。=号和值之间也可以使用可选的空格。
应该注意的是，即使属性可以在编辑器中与大小写混合使用，它们在解析后也总是小写的。
属性值不得包含以下字符：
未引用的值也不能包含空格。
HTML字符<和>在属性中的支持有限。
在短代码属性中转义特殊字符的推荐方法是HTML编码。最重要的是，出现在短代码属性中的任何用户输入都必须转义或去掉特殊字符。
请注意，单引号内允许使用双引号，反之亦然，但在处理用户输入时不建议使用双引号。
如果以下字符未在属性值中转义，则将自动剥离并转换为空格：
- 无中断空格：\xC2\xA0
- 零宽度空间：\xE2\x80\x8B
自动关闭
自动结束标记，一个正斜杠，是可选的。标记前的空格是可选的。标记后不允许有空格。
[示例/]
自结束标记纯粹是装饰性的，除了会强制短代码解析器忽略它后面的任何结束标记之外，它没有任何作用。
封闭型短代码不能使用自动关闭标记。
逃逸
WordPress试图在[name]和[/name]标记之间插入卷曲引号。它将像处理其他内容一样处理这些内容。从4.0.1开始，未注册的短代码也会“纹理化”，这可能会产生意想不到的卷曲引号：
[randomthing param=“test”]
更好的例子是：
<code>[randomthing param=“test”]
为了使用卷曲引号，总是避免使用<code>元素。
注册的短代码仍在<code>元素内处理。为了避免在您的网站上显示注册的短代码，语法变为：
[[标题参数=“测试”]]
…将输出。。。
[caption param=“test”]
在这种情况下，<code>元素是可选的。
对于封闭短代码，请使用以下语法：
[[caption]我的字幕[/caption]]
历史
短代码API是在WordPress 2.5中引入的。
外部资源
默认短代码
相关的
短代码API