WordPress 友情連結函式 wp_list_bookmarks() 詳解

在主題製作中，wp_list_bookmarks 是比較常用的 WordPress 函式，在主題中呼叫友情連結的時候，通常都要用到。下面就對這個 WordPress 友情連結函式 wp_list_bookmarks() 做一下詳細的介紹。

注：wp_list_bookmarks() 已經取代了之前的老函式 get_links_list() 和 get_links() 。

wp_list_bookmarks() 基本用法

<?php wp_list_bookmarks( $args ); ?>

預設引數是：

<?php $args = array(
    'orderby'          => 'name',
    'order'            => 'ASC',
    'limit'            => -1,
    'category'         => ' ',
    'exclude_category' => ' ',
    'category_name'    => ' ',
    'hide_invisible'   => 1,
    'show_updated'     => 0,
    'echo'             => 1,
    'categorize'       => 1,
    'title_li'         => __('Bookmarks'),
    'title_before'     => '<h2>',
    'title_after'      => '</h2>',
    'category_orderby' => 'name',
    'category_order'   => 'ASC',
    'class'            => 'linkcat',
    'category_before'  => '<li id=%id class=%class>',
    'category_after'   => '</li>' ); ?>

預設情況下 (沒有新增任何引數) 的用法：

連結被劃分為不同類別，每個類別有一個名稱
包含所有連結，無論是連結的分類名稱還是 ID
按名稱排列連結列表
如果有圖片，包含圖片
圖片和連結文字間應有空格
顯示連結的描述
不顯示連結等級
無限制，顯示所有連結
顯示所有連結

wp_list_bookmarks() 引數詳解

categorize

（布林型）是否所有連結都應該顯示在相應的分類目錄下。

1（true）——預設值
0（false）

category

（字串）將要顯示的連結分類目錄的 ID，用逗號隔開。如果沒有指定分類，顯示所有含有連結的連結分類。

exclude_category

（字串）將被排除的連結分類目錄的 ID，用逗號隔開。預設值為 (no categories excluded)（不排除任何連結分類）。

category_name

（字串）將要顯示的連結所屬分類的名稱。如果沒有指定分類，顯示所有含有連結的連結分類。預設值為 (all Categories)（所有連結）。

category_before

（字串）放置在每個連結分類目錄前的文字。預設值為'<li id="[category id]" >』。

category_after

（字串）放置在連結分類目錄後的文字。預設值為'<『/li>』。

class

（字串）連結分類列表所在類。預設值為』linkcat』。

category_orderby

（字串）用以排列連結分類的值。有效值包括：

『name』 ——預設值
『id』
『slug』
『count』

category_order

（字串）排列的順序，以升序或降序排列 category_orderby 引數值。有效值包括：

ASC ——預設值
DESC

title_li

（字
符串）連結列表的標題。預設值為『__(『Bookmarks』)』，顯示標題為「Bookmarks」（the_(『
『) 用於本地化。）只有將 categorize 設為 0（false）時，才可使用該引數（否則將使用分類名稱）。若將 title_li 設為空（0），則不
顯示列表標題，且連結列表不會被 <ul>,
</ul> 標籤圍繞（要確保將 categorize 選項設為 0，以使 title_li 生效）。

title_before

（字串）』categorize』值為 1（true）時顯示在每個連結類別前的文字，或』categorize』值為 0（false）時在』title_li』中定義的文字。預設值為'<h2>』。

title_after

『categorize』值為 1（true）時顯示在每個連結類別後的文字，或』categorize』值為 0（false）時在』title_li』中定義的文字。預設值為'</h2>』。

show_private

（布林型）是否應顯示某個連結分類（即使該分類被認為是私密的）。忽略管理面板的設定，顯示私密連結分類（TRUE），或者不顯示私密連結分類（FALSE）。

1（true）
0（false）——預設值

include

（字串）在結果中包含的數值型連結 ID 列表，各 ID 用逗號隔開。例如，『include=1,3,6』表示返回或響應 ID 為 1 、 3 、 6 的連結。如果使用 include 字串，那麼 category 、 category_name 、 exclude 引數將被忽略。預設值為 (all Bookmarks)（所有連結）。

exclude

（字串）將要被排除的連結的 ID，各 ID 用逗號隔開。如『exclude=4,12』表示不返回 ID 為 4 和 12 的連結。預設值為 (exclude nothing)（不排除任何連結）。

orderby

（字串）以何順序為連結排序。這可能是一份各個值的列表，各值由逗號隔開。預設值為』name』，除非你傳遞』『（空）值給該引數，此時引數值為』id』。有效值包括：

『id』 (WP 3.2 及以後版本使用『link_id』 )
『url』
『name』 ——預設值
『target』
『description』
『owner』 —— 透過連線管理器新增連結的使用者
『rating』
『updated』
『rel』 —— 連結關係（XFN）
『notes』
『rss』
『length』 —— 連結名稱的長度，範圍從最短的名稱到最長的名稱
『rand』 —— 以任意順序顯示連結

order

（字串）根據』orderby』引數中的設定為分類目錄排序（升序或降序）。有效值包括：

ASC ——預設值
DESC

limit

（整數）可以顯示的最大連結數。預設值為-1（所有連結）。

before

（字串）放置在連結前的文字。預設值為'<li>』。

after

（字串）放置在連結後的文字。預設值為'</li>』。

link_before

（字串）超連結程式碼中連結文字前的文字。無預設值。

link_after

（字串）超連結程式碼中連結文字後的文字。無預設值。

between

（字串）連結/圖片與其說明之間的文字。預設值為』n』（換行）。

show_images

（布林型）是（TRUE）否（FALSE）顯示連結的圖片

1（true）——預設值
0（false）

show_description

（布林型）是（TRUE）否（FALSE）顯示連結說明。該引數用於 show_images 為 FALSE 時或未定義連結圖片時。

1（true）
0（false）——預設值

show_name

（布林型）顯示連結文字（TRUE）。該引數用於 show_images 為 TRUE 時。

1（true）
0（false）——預設值

show_rating

（字串）是（TRUE）否（FALSE）顯示連結的級別。

1（true）
0（false）——預設值

show_updated

（布林型）是（TRUE）否（FALSE）顯示最近更新的時間標記。

1（true）
0（false）——預設值

hide_invisible

（布林型）是否顯示公開度為「不公開」的連結。是（TRUE）否（FALSE）遵循管理面板中的設定。

1（true）——預設值
0（false）

echo

（布林型）顯示結果（TRUE），或將結果保留以供 PHP 使用（FALSE）。

1（true）——預設值
0（false）

wp_list_bookmarks() 使用示例

簡單的連結列表

顯示所有連結，標題為「Bookmarks」，各連結項包圍在<li> 標籤中，標題則用<h2> 標籤。

<?php wp_list_bookmarks('title_li=&category_before=&category_after='); ?>

沒有標題的簡單列表

按上一個例子的條件顯示所有連結，但不包括預設標題。

1	<?php wp_list_bookmarks('title_li=&categorize=0'); ?>

顯示某個分類下的所有連結

顯示 ID 為 2 的連結分類下的所有連結，使用連結圖片，不顯示連結說明，按 URL 排列連結。

<?php wp_list_bookmarks('categorize=0&category=2&before=<span>&after=</span>&show_images=1&show_description=0&orderby=url'); ?>

顯示連結等級和時間標記

以數字編號列表形式顯示所有連結，各連結下另起一行填寫連結說明，不適用連結圖片，按 ID 排列連結，顯示連結等級和最新更新的時間。

<ol>
<?php wp_list_bookmarks('between=<br />&show_images=0&orderby=id&show_rating=1&show_updated=1'); ?>
</ol>

用圖片取代標題

從主題目錄中選擇一個圖片代替普通文字作為連結列表標題。

<?php wp_list_bookmarks('categorize=0&title_before=&title_after=&title_li=<img src="'.get_bloginfo("stylesheet_directory").'/images/blogroll.gif" alt="blogroll" />'); ?>

小結：

1. 總的來說，要用好 wp_list_bookmarks() 函式，需要自己熟練掌握引數的用法，重要的是多多實踐。

WordPress 友情連結函式 wp_list_bookmarks() 詳解