WordPress 短代碼(Shortcodes)詳細介紹和使用

WordPress Shortcode 指的是一些使用[]包含的短代碼,WordPress 會識別這些短代碼並根據短代碼的定義輸出為特定的內容,Shortcode API 這個功能是 WordPress 從 2.5版本開始引入的,使用它可以給網站內容添加各種功能,Shortcode 這個接口非常容易使用,且功能非常強大。

簡單地說 WordPress Shortcode 指的是一些使用[]包含的短代碼,WordPress 會識別這些短代碼並根據短代碼的定義輸出為特定的內容。

Shortcode 類型

Shortcode API 支持幾乎所有可能的組合形式:自關閉標籤,開放標籤,含有參數的標籤等。

[mycode]
[mycode foo="bar" id="123" color="red" something="data"]
[mycode]Some Content[/mycode]
[mycode]<p><a href="http://example.com/">HTML Content</a<>/p>[/mycode]
[mycode]Content [another-shotcode] more content[/mycode]
[mycode foo="bar" id="123"]Some Content[/mycode]

Shortcode 基本概念

首先你要去定義一個函數,來處理你定義的 Shortcode,和它的屬性參數以及引用的內容。

function my_shortcode_func($attr, $content) {
    // $attr $key=>$value 的陣列
    // $content 是 shortcode 中包含的字串
    // 對 $attr 和 $content 進行處理
    // 返回預期的值
}

然後把自己定義的 Shortcode 和其處理函數管理起來,以便 [mycode attr=”value”] content [/mycode] 能夠按照預期執行。

add_shortcode('mycode', 'my_shortcode_func')

Shortcode 相關的所有函數

WordPress 定義了以下和 Shortcode 相關的函數:

add_shortcode('mycode', 'function_name'); // 定義一個新的 Shortcode
remove_shortcode('mycode'); // 移除一個 Shortcode
remove_all_shortcodes(); // 移除所有的 Shortcode
$return = do_shortcode($content); // 應用 Shortcode 到內容而不輸出

判斷簡碼

關於判斷簡碼有兩個函數分別是 shortcode_exists() 和 has_shortcode()。

  • shortcode_exists()
    shortcode_exists()函數判斷簡碼是否存在。

    remove_all_shortcodes();
    if( shortcode_exists( 'test' ) ) echo '簡碼 test 存在';//False
    add_shortcode( 'test', 'Bing_shortcode_test' );
    if( shortcode_exists( 'test' ) ) echo '簡碼 test 存在';//True
  • has_shortcode()
    has_shortcode() 函數,判斷字符串中是否出現某某簡碼。

    $content = '測試測試測試測試測試測試測試測試';
    if( has_shortcode( $content, 'test' ) ) echo '字串中有 test 簡碼';//False
    $content = '測試測試測試測[test]測試[/test]試測試測試測試測試';
    if( has_shortcode( $content, 'test' ) ) echo '字串中有 test 簡碼';//True

一個簡單的 Shortcode 例子

以 Antispambot ShortCode 插件為例,內容就是電子信箱地址,有個參數 $link 其值為 1 時候,把信箱顯示成可點擊狀態,短碼如下:

function antispambot_shortcode_handler($atts, $content='') {
	extract( shortcode_atts( array('link' => '0'), $atts ) );
 
	if($link){
		return '<a href="mailto:'.antispambot($content,1).'" title="mail to '.antispambot($content,0).'">'.antispambot($content,0).'</a>';
	}else{
		return antispambot( $content,0);
	}
}
add_shortcode('email', 'antispambot_shortcode_handler');

在側邊欄 Widgets 中使用 Shortcode

Shortcode 很方便,但是只能用在日誌內容中,那麼如何在 WordPress 的側邊欄的 Widgets 中使用 Shortcode,方法是在當前主題的 functions.php 中添加如下代碼:

add_filter('widget_text', 'do_shortcode');

然後你在 WordPress 管理後台外觀小工具 (Widgets) 介面添加一個文本 Widget,然後插入並啟用 shortcode 即可。

在主題的文件中使用 Shortcode

WordPress 添加的鉤子:

add_filter( 'the_content', 'do_shortcode', 11 );

如果你想用在主題文件中使用名為 [my_shortcode] 的 Shortcode,你只需要按照下面的方式使用 do_shortcode() 函數即可:

<?php echo do_shortcode("[my_shortcode]"); ?>

解決 Shortcode 中自動添加的 br 或者 p 標籤

我們在使用 WordPress Shortcode API 開發外掛的時候,有個比較麻煩的問題,就是 WordPress 會自動在 shortcode 內添加 br 或者 p 標籤,這樣可能會打亂你的原先預想的 HTML 結構和佈局。

推薦閱讀ಠ.ಠ  無縫整合 Google 自訂搜尋引擎到 WordPress 網站

造成這個問題的原因是 WordPress 默認的日誌內容處理流程中,wpautop(將回車轉換成 p 或者 br 標籤的函數)是在 Shortcode 前面運行的。所以我們的解決方案也是非常簡單,改變它們執行的順序,在當前主題的 functions.php 文件中添加:

remove_filter('the_content', 'wpautop');
add_filter('the_content', 'wpautop' , 12);

這樣調整順序之後,你的 shortcode 裡面的內容,就不會有自動添加的 p 或者 br 標籤,但是如果 shortcode 中部分的內容你又需要一些 p 或者 br 標籤用來換行的話,你需要自己手動在自己 shortcode 處理程序中添加 wpautop 來處理了。

function bio_shortcode($atts, $content = null) {
   $content = wpautop(trim($content));
   return '<div class="bio">' . $content . '</div>';
}
add_shortcode('bio', 'bio_shortcode');

RelatedPost