WordPress常用函数 wp_list_bookmarks()

wp_list_bookmarks()函数是比较常用的WordPress函数，特别是在我们想要调用友情链接时，就肯定用的到了。

语法

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

默认情况下(没有添加任何参数)的用法：

1. 链接被划分为不同类别，每个类别有一个名称
2. 包含所有链接，无论是链接的分类名称还是ID
3. 按名称排列链接列表
4. 如果有图片，包含图片
5. 图片和链接文本间应有空格
6. 显示链接的描述
7. 不显示链接等级
8. 无限制，显示所有链接
9. 显示所有链接

wp_list_bookmarks()参数详解

categorize

（布尔型）是否所有链接都应该显示在相应的分类目录下。

1. 1 （true）——默认值
2. 0（false）

category

（字符串）将要显示的链接分类目录的ID，用逗号隔开。如果没有指定分类，显示所有含有链接的链接分类。

exclude_category

（字符串）将被排除的链接分类目录的ID，用逗号隔开。默认值为 (no categories excluded)（不排除任何链接分类）。

category_name

（字符串）将要显示的链接所属分类的名称。如果没有指定分类，显示所有含有链接的链接分类。默认值为 (all Categories)（所有链接）。

category_before

（字符串）放置在每个链接分类目录前的文本。默认值为'<li id=”[category id]” class=”linkcat”>’。

category_after

（字符串）放置在链接分类目录后的文本。默认值为'<‘/li>’。

class

（字符串）链接分类列表所在类。默认值为’linkcat’。

category_orderby

（字符串）用以排列链接分类的值。有效值包括：

1. ‘name’ ——默认值
2. ‘id’
3. ‘slug’
4. ‘count’

category_order

（字符串）排列的顺序，以升序或降序排列category_orderby参数值。有效值包括：

1. ASC ——默认值
2. 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. 1 （true）
2. 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’。有效值包括：

1. ‘id’   (WP 3.2 及以后版本使用 ‘link_id’ )
2. ‘url’
3. ‘name’ ——默认值
4. ‘target’
5. ‘description’
6. ‘owner’ —— 通过连接管理器添加链接的用户
7. ‘rating’
8. ‘updated’
9. ‘rel’ —— 链接关系（XFN）
10. ‘notes’
11. ‘rss’
12. ‘length’ —— 链接名称的长度，范围从最短的名称到最长的名称
13. ‘rand’ —— 以任意顺序显示链接

order

（字符串）根据’orderby’参数中的设置为分类目录排序（升序或降序）。有效值包括：

1. ASC ——默认值
2. DESC

limit

（整数）可以显示的最大链接数。默认值为-1（所有链接）。

before

（字符串）放置在链接前的文本。默认值为'<li>’。

after

（字符串）放置在链接后的文本。默认值为'</li>’。

link_before

（字符串）超链接代码中链接文本前的文字。无默认值。

link_after

（字符串）超链接代码中链接文本后的文字。无默认值。

between

（字符串）链接/图片与其说明之间的文本。默认值为’n’（换行）。

show_images

（布尔型）是（TRUE）否（FALSE）显示链接的图片

1. 1 （true）——默认值
2. 0（false）

show_description

（布尔型）是（TRUE）否（FALSE）显示链接说明。该参数用于show_images为FALSE时或未定义链接图片时。

1. 1 （true）
2. 0（false）——默认值

show_name

（布尔型）显示链接文本（TRUE）。该参数用于show_images为TRUE时。

1. 1 （true）
2. 0（false）——默认值

show_rating

（字符串）是（TRUE）否（FALSE）显示链接的级别。

1. 1 （true）
2. 0（false）——默认值

show_updated

（布尔型）是（TRUE）否（FALSE）显示最近更新的时间标记。

1. 1 （true）
2. 0（false）——默认值

hide_invisible

（布尔型）是否显示公开度为“不公开”的链接。是（TRUE）否（FALSE）遵循管理面板中的设置。

1. 1 （true）——默认值
2. 0（false）

echo

（布尔型）显示结果（TRUE），或将结果保留以供PHP使用（FALSE）。

1. 1 （true）——默认值
2. 0（false）

实例

简单的链接列表

显示所有链接，标题为“Bookmarks”，各链接项包围在<li>标签中，标题则用<h2>标签。

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

没有标题的简单列表

按上一个例子的条件显示所有链接，但不包括默认标题。

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