简码

简码 API

Shortcode  API是一组简单的函数，用于创建 用于帖子和页面的 WordPress 简码。例如，以下简码（在帖子或页面的正文中）将添加附加到该帖子或页面的图片库： [ gallery ]

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

Shortcode 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 和 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 Shortcode API 是一种方便的功能，可以让开发者和用户在文章和页面中插入自定义的短代码，来实现一些特定的功能。比如插入一个联系表单，插入一个商品展示模块，等等。

使用 Shortcode API 需要遵循以下几个步骤：

  1. 创建 Shortcode 函数：

创建 Shortcode 函数，这个函数需要返回一个字符串，用于显示在文章或页面中。下面是一个简单的例子：

function my_shortcode_function() {
    return "Hello, world!";
}

这个函数就是一个简单的 Shortcode，当你在文章或页面中使用 [my_shortcode] 时，会显示出 Hello, world!。

  1. 注册 Shortcode：

使用 add_shortcode() 函数来注册你的 Shortcode。第一个参数是你的 Shortcode 名称，第二个参数是你的 Shortcode 函数名称。

add_shortcode( 'my_shortcode', 'my_shortcode_function' );
  1. 插入 Shortcode：

现在，当你编辑文章或页面的时候，就可以插入你的 Shortcode 了。只需要在文章或页面中使用你注册的 Shortcode 名称，比如 [my_shortcode]。

这样，当你发布这个文章或页面的时候，Shortcode 就会被解析成你返回的字符串，也就是 Hello, world!。

除了简单的字符串之外，你还可以在 Shortcode 函数中返回 HTML、CSS、JavaScript 或者其他代码，用来实现更加复杂的功能。

上面是一个简单的 Shortcode 实现的过程，但是 Shortcode API 还有更多的功能和选项，比如可以在 Shortcode 中传递参数，可以自定义 Shortcode 样式等等。如果你想了解更多关于 WordPress Shortcode API 的知识，建议阅读官方文档。

简码 API 函数列表

概述

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

简码名称应全部小写并使用所有字母，但数字和下划线也应该可以正常工作。小心使用连字符（破折号），最好不要使用它们。

该 add_shortcode 函数用于注册简码处理程序。它有两个参数：简码名称（帖子正文中使用的字符串）和回调函数名称。

三个参数传递给简码回调函数。您可以选择使用任意数量的它们，包括不使用它们。

  • $atts: 属性的关联数组，如果没有给出属性则为空字符串
  • $content：包含的内容（如果简码以其封闭形式使用）
  • $tag: shortcode 标签，对共享回调函数很有用

注册简码处理程序的 API 调用看起来像这样：

add_shortcode( 'wporgshortcode', 'wporg_shortcode_handler' );

当 显示the_content时 ，简码​​ API 将解析任何已注册的简码，例如[myshortcode]，分离并解析属性和内容（如果有），并将它们传递给相应的简码处理函数。简码处理程序返回（未回显）的任何字符串  都将插入到帖子正文中，以代替简码本身。

简码属性输入如下：

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

这些属性将被转换成如下所示的关联数组，作为其 $atts 参数传递给处理函数：

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

数组键是属性名称；数组值是相应的属性值。此外，zeroeth 条目 ( $atts[0]) 将保存与简码正则表达式匹配的字符串，但前提是它与回调名称不同。

处理属性

原始 $atts 数组可以包含用户指定的任意属性。（此外，数组的第 0 个条目可能包含正则表达式识别的字符串；请参阅下面的注释。）

为了帮助设置缺失属性的默认值，并消除您的简码无法识别的任何属性，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]) 的第 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,"");

这令人困惑并且可能反映了一个潜在的错误，但是重载的回调例程可以通过检查回调的第三个参数和 zeroeth 属性来正确确定调用它的简码。（让两个简码引用相同的回调例程不是错误，这允许使用公共代码。）

输出

简码处理函数的返回值被插入到帖子内容输出中以代替简码宏。 请记住使用 return 而不是 echo——任何被回显的内容都会输出到浏览器，但不会出现在页面的正确位置。

 在应用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 是处理程序函数名称。

对于给定的简码，可能只存在一个处理函数。使用相同的 $tag 名称再次调用add_shortcode()将覆盖以前的处理程序。

function remove_shortcode( $tag )

注销现有的简码。$tag是在add_shortcode().

function remove_all_shortcodes()

注销所有简码。

function shortcode_atts( $pairs, $atts )

$atts根据中指定的一组默认值处理原始属性数组$pairs。返回一个数组。结果将包含来自 的每个键$pairs，并与来自 的值合并$atts。$atts$pairs 中不存在的任何键都将被忽略。

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]

这是 context-free 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过滤器来防止标签-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]

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]]

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

名称

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

  • 方括号：[ ]
  • 角撑：< >
  • 符号：&
  • 正斜杠：/
  • Whitespace：空格换行标签
  • 非打印字符：x00-x20

建议也避免在简码名称中使用引号。

属性

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

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

attribute_name = 'value'

attribute_name = "value"

attribute_name = value

"value"

value

属性名称是可选的，并且应仅包含以下字符以实现跨所有平台的兼容性：

  • 大小写字母：A-Z a-z
  • 数字：0-9
  • 下划线：_
  • 连字符：-

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

需要注意的是，虽然属性在编辑器中可以混合大小写使用，但在解析后它们总是小写的。

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

  • 方括号：[ ]
  • 行情："，'

未加引号的值也绝不能包含空格。

HTML 字符<并且>在属性中的支持有限。

转义简码属性中特殊字符的推荐方法是 HTML 编码。最重要的是，简码属性中出现的任何用户输入都必须转义或去除特殊字符。

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

以下字符，如果未在属性值内转义，将被自动剥离并转换为空格：

  • 不间断空间：xC2xA0
  • 零宽度空间：xE2x80x8B

自动关闭

自闭合标记（单个正斜杠）是可选的。标记前的空格是可选的。标记后不允许有空格。

[example /]

自闭合标记纯粹是装饰性的，除了强制简码解析器忽略其后的任何闭合标记外，没有任何效果。

封闭类型简码不能使用自闭标记。

逃离

[name]WordPress 尝试在和标签之间插入大引号[/name]。它将像处理任何其他内容一样处理该内容。从 4.0.1 开始，未注册的简码也被“纹理化”，这可能会产生意想不到的卷曲引号：

[randomthing param="test"]

一个更好的例子是：

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

<code>为了大引号，始终避免使用该元素。

已注册的简码仍在元素内部处理<code>。要转义已注册的简码以显示在您的网站上，语法变为：

[[caption param="test"]]

这将输出：

[caption param="test"]

<code>在那种情况下该元素是可选的。

要包含简码，请使用以下语法：

[[caption]My Caption]

外部资源

  • WordPress 简码生成器
  • 添加简码 – WordPress 代码片段生成器 – 片段生成器和有关如何将代码添加到 WordPress 网站的完整文档。
  • Aaron D. Campbell 的简码摘要 - 解释简码并提供示例，包括如何将简码合并到元框中以使用 js 将它们发送给编辑器。
  • Innovative WordPress Shortcodes In Action  – 一个 WordPress 插件，向您展示如何有效地使用简码来更改您的帖子内容设计。
  • WordPress Shortcode API Overview  – 使用简码插件的使用说明和示例。
  • Simple shortcode-powered BBCode plugin  – 一个简单的插件，通过简码添加对 BBCode 的支持。查看实际简码的好方法。

默认简码

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