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