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() 詳解