WordPress友情链接列表标签:wp_list_bookmarks

WordPress模板标签wp_list_bookmarks用于输出博客的友情链接,虽然小工具里已经有了链接功能,但wp_list_bookmarks()函数可以让我们的主题开发更灵活。

wp_list_bookmarks( array|string $args = '' )

函数参数

$args

数组或字符串值

wp_list_bookmarks()函数$args参数默认的值如下:

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

wp_list_bookmarks()函数$args参数可用的值如下:

categorize

布尔值,默认值:1

友情链接是否显示在相应的分类下。

category

字符串值,默认为空

指定友情链接的分类ID,多个分类ID用逗号分隔。

exclude_category

字符串值,默认为空

要排除的友情链接分类ID,多个ID用逗号分隔,默认不排除任何分类。

category_name

字符串值,默认为空

要显示的友情链接分类的名称

category_before

字符串值,默认值:<li id=”%id” class=”%class”>

在每个友情链接分类前添加一个字符串

category_after

字符串值,默认值:</li>

在每个友情链接分类后添加一个字符串

class

字符串值,默认值:linkcat

如果category_before为默认值,则该li元素会有一个名为linkcat的类,可以通过class的值修改这个类名。

category_orderby

字符串值,默认值:name

友情链接的分类排序

  • name:以友情链接分类名称排序
  • id:以友情链接分类ID排序
  • slug:以友情链接的分类别名排序
  • count:以友情链接分类下的链接数量排序
  • term_group:暂时还没有使用

category_order

字符串值,默认值:ASC

友情链接分类排序顺序

  • ASC:升序
  • DESC:降序

title_li

字符串值,默认值:Bookmarks

友情链接列表的标题

title_before

字符串值,默认值:<h2>

当categorize为1时,title_before指定友情链接分类名称前的字符,当categorize为0时title_before没有作用。

title_after

字符串值,默认值:</h2>

当categorize为1时,title_after指定友情链接分类名称后的字符,当categorize为0时title_after没有作用。

show_private

布尔值,默认值:0

是否显示私密的链接分类,但我在后台并没有找到链接分类的私密设置选项,虽然链接可以设置为私密链接,但show_private的值并不影响私密链接的输出,影响私密链接输出的参数是hide_invisible,下面会介绍。

include

字符串值,默认为空

要显示的链接ID,多个ID用逗号分隔。如果该参数不为空,请将categorize设置为0,因为我在测试中发现,如果为include指定了值,那么每个链接分类下都会输出相同的链接。

exclude

字符串值,默认为空

要排除的链接ID,多个ID用逗号分隔,此参数没有include的问题。

orderby

字符串值,默认值:name

友情链接的排序方式

  • link_id:友情链接的ID
  • url:按链接的URL排序
  • name:友情链接的名称
  • target:按“目标”设置排序
  • description:按描述排序
  • owner:按添加链接的用户排序
  • rating:按评分排序
  • updated:按更新时间排序,由于这个更新时间并不是指本地修改的时间,而是基于pingomatic的更新,一般这个时间都是:0000-00-00 00:00:00,所以按updated排序没有任何意义。
  • rel:按链接关系(XFN)排序
  • notes:按备注排序
  • rss:按RSS地址排序
  • length:按链接名称的长度排序
  • rand:随机排序

order

字符串值,默认值:ASC

友情链接的排序顺序

  • ASC:升序
  • DESC:降序

limit

整数型,默认值:-1

要显示的链接数量,默认显示所有链接。

before

字符串值,默认值:<li>

默认情况下链接是以<li>列表输出的,即<a>之前的字符。

after

字符串值,默认值:</li>

</a>之后的字符

link_before

字符串值,默认为空

在链接锚文本的前面添加字符

link_after

字符串值,默认为空

在链接锚文本的后面添加字符

between

字符串值,默认值:\n

当show_description为1时,也就是链接描述显示时,between的值将在描述前输出,默认为换行

show_images

布尔值,默认值:1

是否显示链接图像,默认显示,如果为0,则显示链接名称而不是图像。

show_description

布尔值,默认值:0

是否显示链接描述,默认不显示

show_name

布尔值,默认值:0

是否显示链接的名称

show_rating

布尔值,默认值:0

是否显示链接的评分

show_updated

布尔值,默认值:0

是否显示链接更新时间,由于这个更新时间并不是指本地修改的时间,而是基于pingomatic的更新,一般这个时间都是:0000-00-00 00:00:00,所以没有任何输出。

hide_invisible

布尔值,默认值:1

是否隐藏私密链接,默认隐藏,设置为0私密链接也会被显示出来。

echo

布尔值,默认值:1

是否输出结果,如果为0,只返回结果而不输出。

函数使用示例

不按分类输出5个文字链接(不显示链接图像),并且不显示列表标题。

<ul>
    <?php 
		$args = array(
			'categorize' => 0,
			'title_li' => '',
			'limit' => 5,
			'show_images' => 0,
		);
		wp_list_bookmarks($args);
	?>
</ul>

下面的代码输出一样的结果:

<ul>
	<?php wp_list_bookmarks('categorize=0&title_li=&limit=5&show_images=0'); ?> 
</ul>

本站的友情链接页面代码:

<ul>
	<?php wp_list_bookmarks('title_li=0&categorize=0&orderby=link_id&show_description=1&show_images=0&between=:'); ?>
</ul>

扩展阅读

wp_list_bookmarks()函数位于:wp-includes/bookmark-template.php

相关函数:

Typora