WordPress 插件开发教程手册 — 简码

作为一项安全防范措施,WordPress 禁止在内容中运行 PHP 代码,为了让我们可以动态添加内容,WordPress 在 2.5 版本中引入了简码这个概念。简码是用来动态添加内容的代码,使用简码,我们可以在文章中动态的创建相册、播放视频,插入表单或者实现更多自定义操作。

为什么使用简码?

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

简码的优点:

  • 不会添加 HTML 标记到文章内容中,这意味着简码生成的标记和样式可以在随后很轻松的修改和维护。
  • 简码还可以接受参数,允许用户根据需要通过调整简码参数来修改简码内容的显示方式。

内置简码

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

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

简码最佳实践

开发简码的最佳实践包括 插件开发最佳实践 和下面几条建议:

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

外部资源

基本简码

添加基本简码

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

<?php
add_shortcode(
   string $tag,
    callable $func
);

在主题中注册简码

<?php
function wporg_shortcode($atts = [], $content = null) {
   // do something to $content

   // always return
   return $content;
}
add_shortcode('wporg', 'wporg_shortcode');

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

在插件中注册简码

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

<?php
function wporg_shortcodes_init() {
   function wporg_shortcode($atts = [], $content = null) {
      // do something to $content

      // always return
      return $content;
   }
   add_shortcode('wporg', 'wporg_shortcode');
}
add_action('init', 'wporg_shortcodes_init');

删除简码

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

<?php
remove_shortcode(
   string $tag
);

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

检查简码是否存在

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

闭合简码

WordPress 中有两种形式的简码:

  • 自闭合简码,就像我们在基本简码中演示的一样,类似于 HTML 的 br,img 这种不需要闭合标记的标签。
  • 闭合简码,类似于 HTML 中的 div,p 这种需要闭合的标记

包含内容

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

[wporg] content to manipulate [/wporg]

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

处理包含的内容

让我们在看一下原来的 [wporg] 简码代码:

<?php
function wporg_shortcode($atts = [], $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 中包含另外一个简码,其中包含的简码不会被解析,如下:

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

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

<?php
function wporg_shortcode($atts = [], $content = null) {
   // do something to $content

   // run shortcode parser recursively
   $content = do_shortcode($content);

   // always return
   return $content;
}
add_shortcode('wporg', 'wporg_shortcode');

简码限制

简码解析器不能处理混合的闭合和自闭合简码,如下:

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

解析器会把上面简码中的“ non-enclosed content [wporg]enclosed content“ 作为单个简码对待,而不是作为被 “ non-enclosed content “ 分隔的两个简码。

带参数的简码

现在,我们知道了如何创建一个基本简码,以及如何创建自闭合和闭合简码,现在,我们来了解一下简码如何处理参数。简码可以接受一些参数,我们称之为简码属性:

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

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

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

解析属性

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

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

完整示例

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

<?php
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([
      'title' => 'WordPress.org',
   ], $atts, $tag);

   // start output
   $o = '';

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

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

   // enclosing tags
   if (!is_null($content)) {
      // secure output by executing the_content filter hook on $content
      $o .= apply_filters('the_content', $content);

      // run shortcode parser recursively
      $o .= do_shortcode($content);
   }

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

   // return output
   return $o;
}
 
function wporg_shortcodes_init() {
   add_shortcode('wporg', 'wporg_shortcode');
}
 
add_action('init', 'wporg_shortcodes_init');

TinyMCE 增强的简码

我们可以在 TinyMCE 可视化编辑器中解析简码,并让他们显示实际内容,而不是简码本身。切换到 “文本” 模式,我们可以看到实际简码。以下是 WordPress 内置的 TinyMCE 增强简码。

音频简码

使用 audio 简码,我们可以嵌入一个音频文件。

标题简码

caption 把内容包裹在一个 div 里面,然后在 <p class=wp-caption-text> 标签里面显示对内容的说明。

相册简码

gallery 简码,可以让我们在一个 div 里面同时嵌入多个图像,多个图像可以分栏排列。

播放列表简码

playlist 简码可以让我们添加多个媒体文件,并以 HTML5 播放列表的方式显示。

视频简码

视频简码 video 和音频简码 audio 非常相似,只不过显示的是视频。

本站提供 WordPress 主题定制开发服务

本站长期承接 WordPress 主题、插件、基于 WooCommerce 的商店商城开发业务。 我们有 8 年 WordPress 开发经验,如果你想 用 WordPress 开发网站, 请联系 QQ: 470266798,或邮箱: 4626395@gmail.com 咨询。

发表评论

电子邮件地址不会被公开。 必填项已用*标注

*