作為一項(xiàng)安全防范措施，WordPress 內(nèi)容內(nèi)禁止運(yùn)行 PHP 代碼，為了讓我們可以動(dòng)態(tài)的添加內(nèi)容，WordPress 2.5 中引入了簡(jiǎn)碼這個(gè)概念。

簡(jiǎn)碼是用于動(dòng)態(tài)添加內(nèi)容的代碼，使用簡(jiǎn)碼，我們可以在文章中動(dòng)態(tài)的創(chuàng)建相冊(cè)、播放視頻，插入表單或者實(shí)現(xiàn)更多的自定義操作。

為什么使用簡(jiǎn)碼？

簡(jiǎn)碼是較好的保持文章內(nèi)容干凈和語(yǔ)義化的方式，使用簡(jiǎn)碼，我們可以在不插入 PHP 代碼的情況下，把動(dòng)態(tài)內(nèi)容呈現(xiàn)給用戶。

當(dāng)最終用戶使用簡(jiǎn)碼將相冊(cè)添加到文章中時(shí)，他們可以使用很少的幾個(gè)參數(shù)來(lái)設(shè)置相冊(cè)如何顯示。

簡(jiǎn)碼的優(yōu)點(diǎn)：

• 不會(huì)添加 HTML 標(biāo)記到文章內(nèi)容中，這意味著簡(jiǎn)碼生成的標(biāo)記和樣式可以在隨后很方便的修改和維護(hù)。
• 簡(jiǎn)碼還可以接受參數(shù)，允許用戶根據(jù)需要通過(guò)調(diào)整簡(jiǎn)碼參數(shù)來(lái)修改簡(jiǎn)碼內(nèi)容的顯示。

內(nèi)置簡(jiǎn)碼

默認(rèn)情況下，WordPress 包含了以下簡(jiǎn)碼：

• caption – 為圖片或視頻添加說(shuō)明的簡(jiǎn)碼
• gallery – 顯示相冊(cè)的簡(jiǎn)碼
• audio – 嵌入和播放音頻文件的簡(jiǎn)碼
• video – 嵌入和播放視頻文件的簡(jiǎn)碼
• playlist – 顯示音頻或視頻文件的簡(jiǎn)碼
• embed – 顯示嵌入式內(nèi)容的簡(jiǎn)碼

簡(jiǎn)碼最佳實(shí)踐

開(kāi)發(fā)簡(jiǎn)碼的最佳實(shí)踐包括?插件開(kāi)發(fā)最佳實(shí)踐?和下面幾條建議：

• 總是返回！簡(jiǎn)碼實(shí)際上是過(guò)濾器，所以創(chuàng)建 “副作用” 將導(dǎo)致意想不到的錯(cuò)誤。
• 在簡(jiǎn)碼前面添加自己的前綴，以避免與其他簡(jiǎn)碼沖突。
• 消毒輸入并轉(zhuǎn)義輸出
• 我用戶提供關(guān)于所有簡(jiǎn)碼屬性的明確說(shuō)明文檔

外部資源

• WordPress簡(jiǎn)碼生成器

基本簡(jiǎn)碼

添加基本簡(jiǎn)碼

我們可以使用 WordPress 的 Shortcode API 添加自己的簡(jiǎn)碼，整個(gè)過(guò)程很簡(jiǎn)單，使用?add_shortcode()?函數(shù)注冊(cè)一個(gè)包含自定義輸入的回調(diào)函數(shù)就可以了。

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

在主題中注冊(cè)簡(jiǎn)碼

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

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

wporg 是我們注冊(cè)的簡(jiǎn)碼，使用這個(gè)簡(jiǎn)碼會(huì)調(diào)用 wporg_shortcode 函數(shù)來(lái)顯示內(nèi)容。

在插件中注冊(cè)簡(jiǎn)碼

和在主題中注冊(cè)簡(jiǎn)碼不一樣，WordPress插件在 WordPress 的加載過(guò)程中，運(yùn)行得非常早，因此，我們需要推遲添加簡(jiǎn)碼的動(dòng)作到 WordPress 初始化完成之后。建議使用?init?Action 來(lái)實(shí)現(xiàn)。

<?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');

刪除簡(jiǎn)碼

如果我們不再需要一個(gè)簡(jiǎn)碼，可以使用?remove_shortcode()?來(lái)刪除。

<?php
remove_shortcode(
   string $tag
);

確保在嘗試刪除之前，我們已經(jīng)注冊(cè)了簡(jiǎn)碼，為添加簡(jiǎn)碼的操作設(shè)置一個(gè)比較高的優(yōu)先級(jí)，或者把刪除簡(jiǎn)碼的操作掛載到一個(gè)稍晚一點(diǎn)運(yùn)行的鉤子上面。

檢查簡(jiǎn)碼是否存在

如果需要檢查簡(jiǎn)碼是否已被注冊(cè)，使用?shortcode_exists()?函數(shù)來(lái)檢查。

封閉簡(jiǎn)碼

WordPress 中有兩種形式的簡(jiǎn)碼：

• 自封閉簡(jiǎn)碼，就像我們?cè)诨竞?jiǎn)碼中演示的一樣，類似于 HTML 的 br，img 這種不需要封閉標(biāo)記的標(biāo)簽。
• 封閉簡(jiǎn)碼，類似于 HTML 中的 div，p 這種需要封閉的標(biāo)記

包含內(nèi)容

使用封閉簡(jiǎn)碼可以對(duì)簡(jiǎn)碼包含的內(nèi)容進(jìn)行操作，

[wporg] content to manipulate [/wporg]

如上面的簡(jiǎn)碼所示，為了包含一段內(nèi)容，我們需要添加一個(gè)開(kāi)始標(biāo)記 [$tag] 和結(jié)束標(biāo)記 [/$tag]?。

處理包含的內(nèi)容

讓我們?cè)诳匆幌略瓉?lái)的 [wporg] 簡(jiǎn)碼代碼：

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

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

我們可以看到，簡(jiǎn)碼函數(shù)接受兩個(gè)參數(shù)，$atts?和?$content，$content?參數(shù)保存著封閉簡(jiǎn)碼的包含的內(nèi)容，$atts?參數(shù)保存著簡(jiǎn)碼的參數(shù)，這個(gè)我們?cè)谙乱还?jié)中會(huì)詳細(xì)說(shuō)明。

$content?的默認(rèn)值為 null，我們可以使用 PHP 函數(shù) is_null() 來(lái)區(qū)分閉合標(biāo)簽和自閉合標(biāo)簽。

顯示簡(jiǎn)碼的時(shí)候，簡(jiǎn)碼 [$tag]?、其中包含的內(nèi)容和結(jié)束標(biāo)記 [/$tag]?會(huì)被簡(jiǎn)碼的回調(diào)函數(shù)的返回值替換。

[c-alert type=”warning” content=”請(qǐng)注意簡(jiǎn)碼回調(diào)的安全輸出問(wèn)題。” /]

簡(jiǎn)碼嵌套

簡(jiǎn)碼解析器只對(duì)簡(jiǎn)碼的內(nèi)容進(jìn)行一次傳遞。這就意味著如果 $content 中包含另外一個(gè)簡(jiǎn)碼，則其中包含的簡(jiǎn)碼不會(huì)被解析。如下：

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

我們可以在處理函數(shù)的最終返回值上調(diào)用?do_shortcode()?，使 $content 中包含的簡(jiǎn)碼也可以被解析。

<?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');

限制

簡(jiǎn)碼解析器不能處理混合的閉合和自閉合簡(jiǎn)碼，如下：

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

non-enclosed content??解析器不把它當(dāng)作由文本 “[wporg]”?分隔的兩個(gè)短代碼，而是把它當(dāng)作一個(gè)包含“?non-enclosed content [wporg] enclosed content”的短代碼。

帶參數(shù)的簡(jiǎn)碼

現(xiàn)在我們知道了如何創(chuàng)建一個(gè)基本簡(jiǎn)碼，以及如何創(chuàng)建自閉合和閉合簡(jiǎn)碼，現(xiàn)在，我們來(lái)了解一下簡(jiǎn)碼如果處理參數(shù)。

簡(jiǎn)碼可以接受一些參數(shù)，我們稱之為簡(jiǎn)碼的屬性：

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

簡(jiǎn)碼處理函數(shù)可以接受 3 個(gè)參數(shù)：

• $atts?– 數(shù)組 – [$tag] 的屬性
• $content?– 字符串 – 簡(jiǎn)碼包含的內(nèi)容
• $tag?– 字符串 – [$tag] 的名稱（即簡(jiǎn)碼的名稱）

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

解析屬性

對(duì)于用戶來(lái)說(shuō)，簡(jiǎn)碼只是在文章中，帶有方括號(hào)的字符串，用戶不可能知道簡(jiǎn)碼包含哪些屬性以及這些屬性的作用是什么。

對(duì)于插件開(kāi)發(fā)人員來(lái)說(shuō)，我們強(qiáng)制要求用戶使用屬性，用戶可以使用一個(gè)屬性，或者根本不使用。

為了控制如何使用簡(jiǎn)碼，我們需要完成下面的工作：

• 聲明處理函數(shù)的默認(rèn)參數(shù)
• 使用?array_change_key_case()?函數(shù)對(duì)屬性數(shù)組的鍵大小進(jìn)行標(biāo)準(zhǔn)化
• 使用?shortcode_atts()?提供默認(rèn)值數(shù)組，并解析用戶屬性?$atts
• 在返回之前確保輸出的安全

完整示例

下面是一個(gè)簡(jiǎn)碼的完整示例，使用了基本的簡(jiǎn)碼結(jié)構(gòu)，照顧到了自封閉和封閉的情況，對(duì)簡(jiǎn)碼的屬性和輸出采取了凈化和轉(zhuǎn)義措施。下面的 [wporg] 簡(jiǎn)碼接受一個(gè)標(biāo)題參數(shù)，為我們顯示了一個(gè)可以使用 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 增強(qiáng)的簡(jiǎn)碼

我們可以在 TinyMCE 可視化編輯器中解析簡(jiǎn)碼，并讓他們顯示實(shí)際的內(nèi)容，而不是簡(jiǎn)碼本身。

切換到 “文本” 模式，我們可以看到實(shí)際的簡(jiǎn)碼。

以下是 WordPress 內(nèi)置的 TinyMCE 增強(qiáng)簡(jiǎn)碼。

音頻簡(jiǎn)碼

使用 audio 簡(jiǎn)碼，我們可以嵌入一個(gè)音頻文件。

標(biāo)題簡(jiǎn)碼

caption?把內(nèi)容包裹在一個(gè) div 里面，然后在?<p class="wp-caption-text">?標(biāo)簽里面顯示對(duì)內(nèi)容的說(shuō)明。

相冊(cè)簡(jiǎn)碼

gallery 簡(jiǎn)碼，可以讓我們?cè)谝粋€(gè) div 里面同時(shí)嵌入多個(gè)圖像，多個(gè)圖像可以分欄排列。

播放列表簡(jiǎn)碼

playlist 簡(jiǎn)碼可以讓我們添加多個(gè)媒體文件，并以 HTML5 播放列表的方式顯示。

視頻簡(jiǎn)碼

視頻簡(jiǎn)碼 video 和音頻簡(jiǎn)碼 audio 非常相似，只不過(guò)顯示的是視頻。