短代码

短代码API

这 短代码API 是用于创建WordPress的简单功能短代码用于帖子和页面。例如，以下短代码（在帖子或页面的正文中）将添加附加到该帖子或页面的图像的照片库：[ gallery ]

API启用插件开发人员可以创建特殊类型的内容（例如表单，内容生成器），用户可以通过将相应的快捷代码添加到页面文本中来附加到某些页面。

短代码API使创建支持这样的属性的快捷代码很容易：

[ gallery id="123" size="medium" ]

API处理所有棘手的解析，消除了为每个短码编写自定义正则表达式的需求。包括辅助功能用于设置和获取默认属性。API支持自封和封闭的短代码。

作为那些急忙的快速起点，这是创建快速代码所需的PHP代码的最小示例：

// [foobar]
function wporg_foobar_func( $atts ) {
	return "foo and bar";
}
add_shortcode( 'foobar', 'wporg_foobar_func' );

这将创建[foobar]返回的短代码为：foo and bar

具有属性：

// [bartag foo="foo-value"]
function bartag_func( $atts ) {
	$a = shortcode_atts( array(
		'foo' => 'something',
		'bar' => 'something else',
	), $atts );

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

这会创建一个[bartag]支持两个属性的短代码：“ foo”和“ bar”。这两个属性都是可选的，并且将采用默认选项[foo="something" bar="something else"]如果没有提供。短代码将返回foo = {the value of the foo attribute}。

概述

短代码是通过提供处理程序功能来写的。快捷代码处理程序与WordPress过滤器大致相似：它们接受参数（属性）并返回结果（短代码输出）。

短代码的名称应全部较低，并使用所有字母，但是数字和下划线也应正常工作。警惕使用连字符（破折号），最好不要使用它们。

这add_shortcode功能用于注册简编处理程序。它采用两个参数：短代码名称（邮局中使用的字符串）和回调函数名称。

三个参数传递给短代码回调函数。您可以选择使用其中包括任何数量的任何数字。

$atts：一个关联属性数组，或一个空字符串，如果没有给出属性
$content：封闭的内容（如果短代码以其封闭形式使用）
$tag：短代码标签，用于共享回调功能

注册快捷代码处理程序的API调用将看起来像这样：

add_shortcode( 'wporgshortcode', 'wporg_shortcode_handler' );

什么时候内容显示了，短代码API将解析任何注册的快速代码，例如[myshortcode]，分开并解析属性和内容（如果有），并将其传递相应的快捷代码处理程序功能。任何字符串回（未回声）由快速代码处理程序插入邮局中，代替短代码本身。

这样输入快速代码属性：

[wporgshortcode foo="bar" bar="bing"]

这些属性将像以下内容一样转换为一个关联数组，将其传递给处理程序函数作为其$atts范围：

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

数组键是属性名称；数组值是相应的属性值。另外，零条目（$atts[0]）将容纳与快速代码正则匹配的字符串，但前提是与回调名称不同时。

处理属性

原始$atts数组可以包括用户指定的任何任意属性。（此外，数组的零入口可能包含以下等级识别的字符串；请参见下面的注释。）

为了帮助设置缺失属性的默认值，并消除了您的短代码未识别的所有属性，API提供了一个 shortcode_atts（）功能。

shortcode_atts()类似于wp_parse_args功能，但有一些重要的差异。它的参数是：

shortcode_atts( $defaults_array, $atts );

两个参数都是必需的。$defaults_array是一个关联数组，指定识别属性名称及其默认值。$atts是将其传递到短码处理程序中的原始属性数组。shortcode_atts()将返回一个归一化阵列，其中包含来自$defaults_array，从$atts数组如果存在。例如：

$a = shortcode_atts( array(
	'title' => 'My Title',
	'foo' => 123,
), $atts );

如果$atts要包含array( 'foo' => 456, 'bar' => 'something' )，所结果的$a将会array( 'title' => 'My Title', 'foo' => 456 )。的价值$atts['foo']覆盖123的默认值。$atts['title']未设置，因此使用默认的“我的标题”。默认数组中没有“ bar”项目，因此结果不包括在结果中。

属性名称在传递到处理程序函数之前始终将其转换为小写。值未触及。[myshortcode FOO="BAR"]生产$atts = array( 'foo' => 'BAR' )。

用于声明违约和解析属性的建议代码成语如下：

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

这将解析属性，设置默认值，消除所有不支持的属性，并将结果存储在命名的本地数组变量中$a将属性作为密钥 – $a['attr_1']，$a['attr_2']，等等。换句话说，默认数组近似于本地变量声明的列表。

重要的是 – 不要为您$atts属性名称：

$atts值是较低效果期间shortcode_atts( array( 'attr_1' => 'attr_1 default', // ...etc ), $atts )处理，所以您可能想只需使用较低案例即可。

关于混淆的正则表达/回调名称的注意：

属性阵列的零入口（ $atts[0]）将包含匹配快速代码正则态度的字符串，但前提是与回调名称不同时，否则该名称是回调函数的第三个参数。

add_shortcode('foo','foo'); // two shortcodes referencing the same callback
 add_shortcode('bar','foo');
    produces this behavior:
 [foo a='b'] ==> callback to: foo(array('a'=>'b'),NULL,"foo");
 [bar a='c'] ==> callback to: foo(array(0 => 'bar', 'a'=>'c'),NULL,"");

这是令人困惑的，也许反映了一个基本的错误，但是通过检查回调和零属性的第三个参数和零属性，可以正确确定使用哪个快捷代码来称呼它的错误。（拥有两个简码引用相同的回调例程，这不是错误，这允许使用常见的代码。）

输出

快捷代码处理程序功能的返回值插入到邮政内容输出中，代替短代码宏。 记住使用返回而不是回声 – 任何回声的内容都会输出到浏览器，但不会出现在页面上的正确位置。

折架是在解析的 wpautop 和 wptexturize 已应用后格式。这意味着您的短代码输出HTML不会自动使用卷曲的报价，添加了P和BR标签，等等。如果您确实希望将快捷代码输出格式化，则应致电wpautop()或者wptexturize()直接从短码处理程序返回输出时。

WPAUTOP识别短代码语法，并将尝试不将P或BR标签包裹在单独在线上的短码周围。旨在以这种方式使用的短代码应确保输出包裹在适当的块标签中，例如<p>或者<div>。

如果短代码产生很多HTML，则ob_start可用于捕获输出并将其转换为字符串，如下所示：

function wporg_shortcode() {
	ob_start();
	?> <HTML> <here> ... <?php
	return ob_get_clean();
}

封闭自我关闭的短码

上面的示例显示自插入的短代码宏，例如[myshortcode]。API还支持封闭快速代码，例如[myshortcode]content[/myshortcode]。

如果使用短代码宏来包装内容，则其处理程序功能将接收一个包含该内容的第二个参数。用户可以以任何一种形式编写短代码，因此有必要通过为处理程序函数提供第二个参数的默认值来允许任何一种情况：

function wporg_shortcode_handler( $atts, $content = null )

empty( $content )可用于区分自闭合和封闭案件。

封闭内容时，完整的短代码宏（包括其内容）将被函数输出替换。处理程序功能的责任是提供原始内容字符串的任何必要的逃避或编码，并将其包括在输出中。

这是一个封闭短代码的微不足道示例：

function wporg_caption_shortcode( $atts, $content = null ) {
	return '<span class="caption">' . $content . '</span>';
}
add_shortcode( 'caption', 'wporg_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: [myshortcode]

这将产生：

<span class="caption">Caption: [myshortcode]</span>

如果封闭的短代码旨在允许其输出中的其他快捷代码，则处理程序功能可以调用 do_shortcode（）递归：

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

在上一个示例中，这将确保[myshortcode]封闭内容中的宏被解析，其输出由标题跨度包含：

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

解析器不处理与您想要的相同快捷代码的封闭形式的混合。例如，如果您有：

[myshortcode example='non-enclosing' /] non-enclosed content [myshortcode] enclosed content [/myshortcode]

解析器将其视为单个短代码封闭的“非封闭内容”，而不是被视为两个短码，而是将其视为单一的短代码。[myshortcode]封闭内容”。

封闭短代码的属性与自我关闭的短代码相同。这是一个例子caption_shortcode()改进以支持“类”属性：

function wporg_caption_shortcode( $atts, $content = null ) {
	$a = shortcode_atts( array(
		'class' => 'caption',
	), $atts );

	return '<span class="' . esc_attr($a['class']) . '">' . $content . '</span>';
}

My Caption

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

其他功能简要

解析器支持XHTML风格的结尾快速代码[myshortcode /]，但这是可选的。
短代码宏可以使用单引号或双引号来用于属性值，或者如果属性值不包含空格，则完全省略它们。[myshortcode foo='123' bar=456]等同于[myshortcode foo="123" bar="456"]。请注意，最后一个位置中的属性值可能不会以向前的斜线结束，因为上面的段落中的功能会消耗该斜线。
对于与较旧的临时短代码的向后兼容性，可能会省略属性名称。如果属性没有名称，它将在该属性中给出一个位置数字键$atts大批。例如，[myshortcode 123]会产生$atts = array( 0 => 123 )。位置属性可以与命名的属性混合，如果值包含空格或其他重要字符，则可以使用引号。
快速代码API具有测试用例。可以在 http://svn.automattic.com/wordpress-tests/trunk/tests/shortcode.php

功能参考

可用以下快捷代码API功能：

function add_shortcode( $tag, $func )

注册一个新的快捷代码处理程序功能。$tag是用户（无括号）所写的短代码字符串，例如“ myShortCode”。$ func是处理程序功能名称。

给定的短代码可能只有一个处理程序功能。打电话add_shortcode()同样，使用相同的$标签名称将覆盖上一个处理程序。

function remove_shortcode( $tag )

列出现有的短代码。$tag是在add_shortcode()。

function remove_all_shortcodes()

所有快速代码。

function shortcode_atts( $pairs, $atts )

处理一个原始属性数组$atts针对在$pairs。返回一个数组。结果将包含来自$pairs，与来自$atts。任何键$atts$对不存在的是忽略。

function do_shortcode( $content )

解析任何已知的短代码宏$content细绳。返回一个包含原始内容的字符串，其中包含短代码宏被其处理程序功能输出代替。

do_shortcode（）在“ the_content”上注册为默认过滤器，优先级为11。

限制

嵌套的短码

短代码解析器正确处理嵌套的短代码宏，只要其处理程序功能通过递归调用来支持它 do_shortcode（）：

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

但是，如果使用短代码宏用来封装同一名称的另一个宏：解析器将失败：

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

这是对无上下文的REGEXP解析器的限制do_shortcode() – 它非常快，但不计算嵌套的水平，因此在这些情况下，它无法与其正确的关闭标签匹配。

在未来版本的WordPress中，具有嵌套短代码语法的插件可能需要确保wptexturize()处理器不会干扰内部代码。建议对于如此复杂的语法，no_texturize_shortcodes 过滤器应在外部标签上使用。在此处使用的示例中，应将TAG-A添加到短代码列表中以不纹理。如果仍然需要对TAG-A或TAG-B的内容进行纹理，那么您可以致电wptexturize()打电话之前do_shortcode()如上所述。

未注册的名称

一些插件作者选择了一种不注册短代码名称的策略，例如，在调用父折叠码的处理程序功能之前禁用嵌套的短代码。这可能会带来意想不到的后果，例如无法解析短代码属性值。例如：

[tag-a unit="north"]
   [tag-b size="24"]
      [tag-c color="red"]
   [/tag-b]
[/tag-a]

从版本4.0.1开始，如果插件未能注册tag-b和tag-c作为有效的快捷代码，则wptexturize()处理器将在解析任何快捷代码之前输出以下文本：

[tag-a unit="north"]
   [tag-b size=”24”]
      [tag-c color=”red”]
   [/tag-b]
[/tag-a]

未注册的短码应被视为没有特殊含义的正常纯文本，并且不建议使用未注册的短码的做法。如果您必须在短代码标签之间包装原始代码，则至少考虑使用 no_texturize_shortcodes 过滤以防止Tag-a内容的质地化：

add_shortcode( 'tag-a', 'wporg_tag_a_handler' );
add_filter( 'no_texturize_shortcodes', 'wporg_ignore_tag_a' );

function wporg_ignore_tag_a( $list ) {
  $list[] = 'tag-a';
  return $list;
}

未封闭的短码

在某些情况下，短代码解析器无法正确处理封闭和未封闭的短码的使用。例如，在这种情况下，解析器只能正确识别短代码的第二个实例：

[tag]
[tag]
   CONTENT
[/tag]

但是，在这种情况下，解析器将同时识别这两者：

[tag]
   CONTENT
[/tag]
[tag]

连字符

以短码的名义使用连字符时要谨慎。在下面的实例中，WordPress可能会将第二个开口短代码视为等同于第一个（基本上WordPress）在连字符之前看到第一部分）：

[tag]
[tag-a]

这完全取决于首先定义哪个快捷代码。如果要使用连字符，请先定义最短的短代码。

为避免这种情况，请使用下划线或根本没有分离器：

[tag]
[tag_a]

[tag]
[taga]

如果短代码的第一部分彼此不同，则可以使用连字符逃脱：

[tag]
[tagfoo-a]

重要的： 使用连字符可能会有您可能不知道的含义；例如，其他安装的短代码也是使用连字符，通用单词与连字符的使用可能会导致碰撞（如果在同一请求中一起使用短代码）：

// plugin-A
[is-logged-in]

// plugin-B
[is-admin]

方括号

短代码解析器不接受属性中的方括号。因此，以下将失败：

[tag attribute="[Some value]"]

被化妆托架包围的标签尚未完全支持 wptexturize（）或它的过滤器。这些代码可能会产生意外的结果：

[I put random text near my captions. ]

笔记： 这些限制可能会在WordPress的未来版本中发生变化，您应该测试以确保绝对确定。

html

从版本3.9.3开始，在短代码属性中使用HTML的使用受到限制。例如，此简编码无法正常工作，因为它包含一个>特点：

[tag value1="35" value2="25" compare=">"]

版本4.0旨在允许经过验证的HTML，因此这将起作用：

[tag description="<b>Greetings</b>"]

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相同的方式使用特殊字符。乍一看，方形牙套似乎很神奇，但它们并不是任何语言的真正一部分。例如：

Gallery短代码被API解析为特殊符号，因为它是注册的短代码。另一方面，当未注册短码时，简单地忽略了方形括号：

[randomthing]

随机符号及其方形括号被忽略，因为它们不属于任何注册短代码的一部分。

在一个完美的世界中[*]符号可以由API处理，但是我们必须考虑以下挑战：HTML允许方形括号，并且并非总是在有限的情况下允许在短码内允许在短码内进行角括号，并且所有此代码都必须通过多个代码运行输出之前，可自定义的过滤器和解析器的层。由于这些语言兼容性问题，方形括号不可能是神奇的。

快捷代码语法使用以下一般部分：

[name attributes close]

[name attributes]Any HTML or shortcode may go here.[/name]

逃脱的短码是相同的，但完全有两个额外的牙套：

[[name attributes close]]

[[name attributes]Any HTML or shortcode may go here.[/name]]

同样，必须注册快捷代码名称，否则所有四个示例将被忽略。

名称

短代码名称绝不能包含以下字符：

方形牙套：[ ]
角牙：< >
Ampersand：&
前锋斜线：/
空格：太空线式选项卡
非打印字符：x00 – x20

建议还要避免用短代码的名称引用。

属性

属性是可选的。短代码名称和短代码属性之间需要一个空间。当使用多个属性时，每个属性必须至少由一个空间分开。

每个属性应符合以下格式之一：

attribute_name = 'value'

attribute_name = "value"

attribute_name = value

"value"

value

属性名称是可选的，只能包含以下字符，以构成所有平台的兼容性：

上案例和下案字母：A-Za-z
数字：0-9
下划线：_
连字符：-

属性名称中不允许空格。可以在名称和名称之间使用可选空间=符号。可选空间也可以在=符号和值。

应当指出的是，即使可以在编辑器中与混合案例一起使用属性，但它们在解析后始终是小写。

属性值绝不能包含以下字符：

方形牙套：[ ]
引号："，'

未引用的值也绝不包含空格。

HTML字符<和>对属性的支持只有有限的支持。

在短代码属性中逃脱特殊字符的推荐方法是HTML编码。最重要的是，任何出现在短码属性中的用户输入都必须被逃脱或剥夺特殊字符。

请注意，单引号内允许双引号，反之亦然，但是在处理用户输入时不建议这样做。

如果以下字符在属性值中未逃脱，则将自动剥离并转换为空格：

无破的空间：xC2xA0
零宽度空间：xE2x80x8B

自我关闭

自插曲标记是一个单一的前向斜杠，是可选的。标记之前的空间是可选的。标记后不允许空间。

[example /]

自闭合标记纯粹是化妆品，没有效果，除了它将迫使快速代码解析器忽略其后面的任何关闭标签。

封闭类型的短代码可能不会使用自闭合标记。

逃脱

WordPress尝试在[name]和[/name]标签。它将像其他任何内容一样处理内容。截至4.0.1，未注册的短码也被“纹理化”，这可能会产生意外的卷发报价：

[randomthing param="test"]

一个更好的例子是：

<code>[randomthing param="test"]</code>

这<code>为了卷曲的报价，总是避免元素。

注册的短号仍在内部处理<code>元素。为了逃避在网站上显示的注册短代码，语法变为：

[caption param="test"]

将输出：

这<code>在这种情况下，元素是可选的。

对于包装折码，请使用以下语法：

[My Caption]

外部资源

WordPress短代码生成器
添加快捷代码 – WordPress代码摘要生成器 – 摘要生成器和有关如何将代码添加到WordPress网站的完整文档。
Aaron D. Campbell的短码摘要 – 解释短代码，并提供示例，包括如何将短代码合并到元框中，以将其使用JS发送给编辑器。
创新的WordPress短码 – 一个WordPress插件，向您展示了如何有效地使用短代码来更改帖子内容设计。
WordPress快捷代码API概述 – 使用短代码的使用和插件示例的说明。
简单的短代码驱动的bbcode插件 – 一个简单的插件，通过短码增加了对BBCODE的支持。看到短码的好方法。

默认的短代码

[ audio ]
[ wp_caption ]
[ caption ]
[ embed ]
[ gallery ]
[ video ]
[ playlist ]

短代码API

历史

概述

处理属性

输出

封闭自我关闭的短码

其他功能简要

功能参考

限制

嵌套的短码

未注册的名称

未封闭的短码

连字符

方括号

html

注册数

正式语法

名称

属性

自我关闭

逃脱

外部资源

默认的短代码

短代码API功能列表

By zhuon

Related Post

发表回复取消回复

You Missed

ChangElog

使用数据视图在插件中显示并与数据交互

在WordPress中注册自定义纵横比6.6

开发人员有什么新功能？（2024年8月）

嵌套的短码

未注册的名称

未封闭的短码

连字符

方括号

html

注册数

名称

属性

自我关闭

逃脱

By zhuon

Related Post

发表回复 取消回复

You Missed

发表回复取消回复