# 6.1 简码简介

简码是通过提供处理函数来编写的。简码处理程序与 WordPress 过滤器大致相似:它们接受参数(属性)并返回结果(简码输出)。换句话说,简码是用来动态添加内容的代码,使用简码,我们可以在文章中动态的创建相册、播放视频,插入表单或者实现更多自定义操作。

简码名称应全部小写并使用所有字母,但数字和下划线也应能正常工作

为什么使用简码?

简码是保持文章内容干净和语义化的一种比较好的方式,使用简码,我们可以在不插入 PHP 代码的情况下,呈现动态内容给用户。当最终用户使用简码添加相册到文章中时,他们可以使用几个参数来设置相册的显示方式。

# 内置简码

默认情况下,WordPress 包含了以下简码:

  • caption – 为图片或视频添加说明
  • gallery – 显示相册
  • audio – 嵌入和播放音频文件
  • video – 嵌入和播放视频文件
  • playlist – 显示音频或视频文件
  • embed – 显示嵌入式内容

简码相关API

# 简码最佳实践

  • 总是返回!简码实际上是一个过滤器,所以创建 “副作用” 将导致意想不到的错误。
  • 在简码前面添加自己的前缀,以避免和其他简码产生冲突。
  • 净化输入并转义输出

# 6.2 基本简码

# 添加基本简码

我们可以使用 WordPress 的 Shortcode API 添加简码,使用 add_shortcode() 函数注册一个包含自定义输入的回调函数。

<?php
add_shortcode(
    string $tag,
    callable $func
);
1
2
3
4
5

# 在主题中注册简码

<?php
function mla_shortcode($atts = [], $content = null) {
   // 处理 $content
   $content = $content."mla";
   // 总是返回
   return $content;
}
add_shortcode('mla', 'mla_shortcode');
1
2
3
4
5
6
7
8

mla 是我们注册的简码,使用这个简码时,会调用 mla_shortcode 函数来显示内容。

# 在插件中注册简码

和在主题中注册简码不一样,插件在 WordPress 的加载过程中,运行得非常早,因此,我们需要推迟添加简码的操作到 WordPress 初始化完成之后。建议使用 init Action 来实现。

<?php
function mla_shortcodes_init() {
   function mla_shortcode($atts = [], $content = null) {
        // 处理 $content
        $content = $content."mla";

        // 返回
        return $content;
   }
   add_shortcode('mla', 'mla_shortcode');
}
add_action('init', 'mla_shortcodes_init');
1
2
3
4
5
6
7
8
9
10
11
12

# 删除简码

当我们不再需要一个简码时,可以使用 remove_shortcode() 来删除他。

<?php
remove_shortcode(
   string $tag
);
1
2
3
4

确保在尝试删除之前,我们已经注册了简码,为添加简码的操作设置一个较高的优先级,或者把删除简码的操作挂载到稍晚运行的钩子上面。

# 检查简码是否存在

如果需要检查简码是否已被注册,使用 shortcode_exists() 函数来检查。

# 6.3 封闭式vs自封闭式简码

WordPress 中有两种形式的简码:

  • 自封闭式简码,类似于 HTML 的 br,img 这种不需要闭合标记的标签。
  • 封闭式简码,类似于 HTML 中的 div,p 这种需要闭合的标记。

# 包含内容

使用封闭式简码可以对简码包含的内容进行操作

<?php
[mla] content to manipulate [/mla]
1
2

如上面的简码所示,为了包含一段内容,我们需要添加一个开始标记 [$tag] 和结束标记 [/$tag] 。

# 处理包含的内容

<?php
function mla_shortcode($atts = [], $content = null) {
   // 操作内容

   // 返回
   return $content;
}
add_shortcode('mla', 'mla_shortcode');
1
2
3
4
5
6
7
8

我们可以看到,简码函数接受两个参数,$atts 和 $content,$content 参数保存着闭合简码包含的内容,$atts 参数保存着简码的参数,在下一节中我们会详细说明。

$content 的默认值为 null,我们可以使用 PHP 函数 is_null() 来区分封闭式标签和自封闭式标签。

显示简码时,简码 [$tag] 、其中包含的内容和结束标记 [/$tag] 会被简码的回调函数的返回值替换。

# 简码嵌套

简码解析器只对传递一次简码内容,也就是说,如果 $content 中包含另外一个简码,其中包含的简码不会被解析,如下:

<?php
[mla] another [shortcode] is included [/mla]
1
2

但是可以在处理函数的最终返回值上调用 do_shortcode() ,使 $content 中包含的简码也可以被解析。

<?php
function mla_shortcode($atts = [], $content = null) {
   // 操作内容

   // 递归运行简码
   $content = do_shortcode($content);

   // 返回
   return $content;
}
add_shortcode('mla', 'mla_shortcode');
1
2
3
4
5
6
7
8
9
10
11

# 6.4 带参数的简码

# 简码可以接受一些参数,我们称之为简码属性:

<?php
[mla title=WordPress.org] Having fun with WordPress.org shortcodes. [/mla]
1
2

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

  • $atts – 数组 – [$tag] 的属性
  • $content – 字符串 – 简码包含的内容
  • $tag – 字符串 – [$tag] 的名称(即简码的名称)
<?php
function mla_shortcode($atts = [], $content = null, $tag = '') {}
1
2

# 解析属性

对用户来说,简码只是在文章中带有方括号的字符串,用户不可能知道简码包含哪些属性以及这些属性的作用是什么。对于插件开发人员来说,没有办法强制要求用户使用属性,用户可以使用一个属性,或者一个也不用。

为了控制如何使用简码,我们需要完成以下工作:

.e.g.

下面是一个简码的完整示例,使用了基本简码结构,照顾到了自闭合和闭合的情况,对简码的属性和输出采取了净化和转义措施。下面的 [mla] 简码接受一个标题参数,为我们显示了一个可以使用 CSS 美化的文本框。

<?php
function mla_shortcode($atts = [], $content = null, $tag = '') {
   // 规范化属性键,小写
   $atts = array_change_key_case((array)$atts, CASE_LOWER);

   // 使用用户属性覆盖默认属性
   $mla_atts = shortcode_atts([
      'title' => 'WordPress.org',
   ], $atts, $tag);

   // 开始输出
   $o = '';

   // 输出 class 为 mla-box 的div
   $o .= '<div class=mla-box>';

   // 安全输出标题
   $o .= '<h2>' . esc_html__($mla_atts['title'], 'mla') . '</h2>';

   // 判断 封闭式简码 自封闭式简码
   if (!is_null($content)) {
      // 通过对 $content 执行内容过滤器钩子来安全输出
      $o .= apply_filters('the_content', $content);

      // 递归运行简码分析器
      $o .= do_shortcode($content);
   }

   //  class 为 mla-box 的 div 闭合
   $o .= '</div>';

   // 返回输出
   return $o;
}
 
function mla_shortcodes_init() {
   add_shortcode('mla', 'mla_shortcode');
}
 
add_action('init', 'mla_shortcodes_init');
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40