简码

简码
基本简码
附上简码
带参数的简码
TinyMCE 增强短代码

简码

作为安全预防措施，禁止在 WordPress 内容中运行 PHP；为了允许与内容进行动态交互，WordPress 2.5 版本中引入了简码。

短代码是可用于与内容执行动态交互的宏。即从帖子中附加的图像创建图库或渲染视频。

为什么使用简码？

短代码是保持内容简洁和语义的一种有价值的方式，同时允许最终用户以编程方式改变其内容的呈现方式。

当最终用户使用短代码将照片库添加到他们的帖子中时，他们会使用尽可能少的数据来指示如何呈现图库。

优点：

帖子内容中不会添加任何标记，这意味着标记和样式可以轻松地即时或稍后进行操作。
短代码还可以接受参数，允许用户根据实例修改短代码的行为方式。

内置简码

默认情况下，WordPress 包含以下短代码：

[caption]– 允许您在内容周围添加字幕
[gallery]– 允许您显示图片库
[audio]– 允许您嵌入和播放音频文件
[video]– 允许您嵌入和播放视频文件
[playlist]– 允许您显示音频或视频文件的集合
[embed]– 允许您包裹嵌入的物品

简码最佳实践

开发短代码的最佳实践包括插件开发最佳实践和以下列表：

总是回来！
短代码本质上是过滤器，因此创建“副作用”将导致意想不到的错误。
为您的短代码名称添加前缀，以避免与其他插件发生冲突。
清理输入并转义输出。
为用户提供有关所有短代码属性的清晰文档。

快速参考

请参阅使用基本短代码结构、处理自关闭和封闭场景、短代码中的短代码以及保护输出的完整示例。

外部资源

WordPress 短代码生成器

基本简码

添加简码

可以使用短代码 API 添加您自己的短代码。该过程涉及使用注册$func对短代码的回调。$tagadd_shortcode()

add_shortcode(
    string $tag,
    callable $func
);

[wporg]是您的新简码。使用短代码将触发wporg_shortcode回调函数。

add_shortcode('wporg', 'wporg_shortcode');
function wporg_shortcode( $atts = [], $content = null) {
    // do something to $content
    // always return
    return $content;
}

删除短代码

可以使用 Shortcode API 删除短代码。$tag该过程涉及使用remove_shortcode()删除注册。

remove_shortcode(
    string $tag
);

在尝试删除之前，请确保已注册短代码。为add_action()指定更高的优先级编号或挂钩到稍后运行的操作挂钩。

检查短代码是否存在

要检查短代码是否已注册，请使用shortcode_exists().

附上简码

使用短代码有两种场景：

短代码是一个自闭合标签，就像我们在基本短代码部分中看到的那样。
短代码包含内容。

附上内容

使用短代码封装内容允许对封装的内容进行操作。

[wporg]content to manipulate[/wporg]

如上所示，为了包含一段内容，您所需要做的就是添加开始[$tag]和结束[/$tag]，类似于 HTML。

处理所附内容

让我们回到原来的 [wporg] 短代码：

function wporg_shortcode( $atts = array(), $content = null ) {
    // do something to $content
    // always return
    return $content;
}
add_shortcode( 'wporg', 'wporg_shortcode' );

查看回调函数，我们发现我们选择接受两个参数，$atts和$content。该$content参数将保存我们所包含的内容。我们稍后再谈$atts。

默认值$content设置为，null以便我们可以使用 PHP 函数is_null()来区分自闭合标签和封闭标签。

短代码[$tag]（包括其内容和结尾）[/$tag]将替换为处理函数的返回值。

处理程序函数负责保护输出。

简码接收

短代码解析器对帖子的内容执行一次传递。

这意味着如果$content短代码处理程序的参数包含另一个短代码，则不会对其进行解析。在本例中，[shortcode]将不会被处理：

[wporg]another [shortcode] is included[/wporg]

通过调用处理函数的do_shortcode()最终返回值，可以在其他短代码中使用短代码。

function wporg_shortcode( $atts = array(), $content = null ) {
	// do something to $content
	// run shortcode parser recursively
	$content = do_shortcode( $content );
	// always return
	return $content;
}
add_shortcode( 'wporg', 'wporg_shortcode' );

局限性

短代码解析器无法处理相同的封闭和非封闭形式的混合[$tag]。

[wporg] non-enclosed content [wporg]enclosed content[/wporg]

non-enclosed content解析器不会将其视为由文本“”分隔的两个短代码，而是将其视为包含“ non-enclosed content [wporg]enclosed content”的单个短代码。

带参数的简码

现在我们知道如何创建基本的短代码以及如何将其用作自闭合和封闭，我们将了解在短代码[$tag]和处理函数中使用参数。

短代码[$tag]可以接受参数，称为属性：

[wporg title="WordPress.org"]
Having fun with WordPress.org shortcodes.
[/wporg]

简码处理函数可以接受 3 个参数：

$atts– 数组 – [$tag] 属性
$content– 字符串 – 短代码中的内容。在上面的示例中，它将是“享受 WordPress.org 短代码的乐趣”。
$tag– string – [$tag] 的名称（即短代码的名称）

function wporg_shortcode( $atts = array(), $content = null, $tag = '' ) {}

解析属性

对于用户来说，短代码只是帖子内容中带有方括号的字符串。用户不知道哪些属性可用以及幕后发生了什么。

对于插件开发人员来说，无法强制执行属性使用策略。用户可以包括一个属性、两个属性或根本没有属性。

要控制短代码的使用方式：

声明处理函数的默认参数
使用array_change_key_case()对属性数组的键值进行标准化
使用提供默认值数组和用户的Shortcode_atts()解析属性$atts
返回之前保护输出

完整示例

使用基本的短代码结构的完整示例，处理自关闭和封闭场景并保护输出。

一个[wporg]短代码，它将接受标题并显示一个我们可以使用 CSS 设计样式的框。

/**
 * The [wporg] shortcode.
 *
 * Accepts a title and will display a box.
 *
 * @param array  $atts    Shortcode attributes. Default empty.
 * @param string $content Shortcode content. Default null.
 * @param string $tag     Shortcode tag (name). Default empty.
 * @return string Shortcode output.
 */
function wporg_shortcode( $atts = [], $content = null, $tag = '' ) {
	// normalize attribute keys, lowercase
	$atts = array_change_key_case( (array) $atts, CASE_LOWER );

	// override default attributes with user attributes
	$wporg_atts = shortcode_atts(
		array(
			'title' => 'WordPress.org',
		), $atts, $tag
	);

	// start box
	$o = '<div class="wporg-box">';

	// title
	$o .= '<h2>' . esc_html( $wporg_atts['title'] ) . '</h2>';

	// enclosing tags
	if ( ! is_null( $content ) ) {
		// $content here holds everything in between the opening and the closing tags of your shortcode. eg.g [my-shortcode]content[/my-shortcode].
        // Depending on what your shortcode supports, you will parse and append the content to your output in different ways.
		// In this example, we just secure output by executing the_content filter hook on $content.
		$o .= apply_filters( 'the_content', $content );
	}

	// end box
	$o .= '</div>';

	// return output
	return $o;
}

/**
 * Central location to create all shortcodes.
 */
function wporg_shortcodes_init() {
	add_shortcode( 'wporg', 'wporg_shortcode' );
}

add_action( 'init', 'wporg_shortcodes_init' );