掌握WordPress链接管理器API

In a previous article, we saw what the WordPress Links Manager is, how to access it, and how to use it to manage a sorted list of links. We also learnt how to display our links, thanks to the default widget.

在上一篇文章中，我们了解了WordPress链接管理器是什么，如何访问它以及如何使用它来管理链接的排序列表。 由于有了默认的小部件，我们还学习了如何显示链接。

However, this widget is not perfect: while it is more than enough to display a basic blogroll, we can’t do all we want to do with it. In the next two articles, we will see how to use the Links Manager API to display our links. In this article, we will focus on describing the main function of the API, before learning how to use the other functions in the next article.

但是，此小部件并不完美：尽管它足以显示基本的Blogroll，但我们无法用它做我们想做的所有事情。 在接下来的两篇文章中，我们将看到如何使用Links Manager API来显示我们的链接。 在本文中，我们将重点介绍API的主要功能，然后在下一篇文章中学习如何使用其他功能。

列出链接的功能 (A Function to List Our Links)

We find several functions in the Links Manager API. However, we won’t use all of them. In fact, if you have already seen some code that uses this API, you might also have seen the use of one the following three functions: get_links(), get_links_list() and wp_get_links(). You shouldn’t use these functions: they are all deprecated.

我们在Links Manager API中找到了几个功能。 但是，我们不会全部使用它们。 实际上，如果您已经看过一些使用此API的代码，则可能还看到了以下三个函数之一的使用： get_links() ， get_links_list()和wp_get_links() 。 您不应该使用这些功能：不推荐使用它们。

The function we will study in this article is wp_list_bookmarks(). All it does is display your links in the shape of a list, but some options allow us to customize the result and that’s why this function is so interesting.

我们将在本文中研究的功能是wp_list_bookmarks() 。 它所做的只是以列表的形式显示您的链接，但是一些选项使我们可以自定义结果，这就是为什么此功能如此有趣的原因。

Basically, you can use the wp_list_bookmarks() function without giving it any argument. It will then display all the categories, one after another. For each of these categories, it displays an unordered list with the different links with their image. Without any customization in the wp_list_bookmarks() function or even in the CSS, we see the result below.

基本上，您可以使用wp_list_bookmarks()函数，而无需为其提供任何参数。 然后它将依次显示所有类别。 对于这些类别中的每一个，它都会显示一个无序列表，并带有其图像的不同链接。 在wp_list_bookmarks()函数甚至CSS中都没有进行任何自定义，我们将看到以下结果。

The default widget, on the left, has a better result. Let’s see the different available options to personalize our display.

左侧的默认小部件效果更好。 让我们看看不同的可用选项来个性化我们的显示。

个性化输出 (Personalizing the Output)

The wp_list_bookmarks() function admits only one argument: an array listing all the options we want to customize. We will here separate these options into two categories: those which concern the data by themselves (such as how to retrieve a given category, or how to sort the links) and those which concern the display (such as which title to display).

wp_list_bookmarks()函数仅接受一个参数：一个列出我们要自定义的所有选项的数组。 在这里，我们将这些选项分为两类：与数据本身相关的选项(例如如何检索给定类别或如何对链接进行排序)和与显示相关的选项(例如要显示的标题)。

自定义数据 (Customizing the Data)

选择类别 (Choosing the Categories)

If you want to display links in several places, chances are great that you will want to choose one specific category to display in each place. That can be achieved thanks to the category option. As it is the first option we see, an example will be clearer, so I have included one below.

如果要在多个位置显示链接，则很有可能要选择一个特定类别在每个位置显示。 这要归功于category选项。 因为这是我们看到的第一个选项，所以一个示例将更加清楚，因此我在下面提供了一个示例。

$args = array(
		'category' => '4,5'
	);

wp_list_bookmarks($args);

Thanks to the argument sent to the wp_list_bookmarks() function, we only display two categories, identified by their ID. Here, you can indicate the IDs you want, separated by a comma. By default, this option is set to ' ' to display all the categories.

多亏了发送到wp_list_bookmarks()函数的参数，我们只显示了两个类别，由它们的ID标识。 在这里，您可以指定所需的ID，以逗号分隔。 默认情况下，此选项设置为' '以显示所有类别。

If you prefer, instead of listing the categories you want to display, you can list the ones you want to hide with the option exclude_category. As in the previous option, its value is a list of categories IDs to hide. By default, no category is hidden thanks to the value ' '.

如果愿意，您可以使用exclude_category选项列出要隐藏的类别，而不是列出要显示的类别。 与上一个选项一样，其值是要隐藏的类别ID的列表。 默认情况下，由于值' '没有隐藏任何类别。

The ID of a category is not always practical to use. That’s why you can use the option category_name. By default, its value is ' ' and all the categories are shown, but you can indicate the name of a category, so that only this category shows.

类别的ID并非总是实用。 这就是为什么您可以使用选项category_name 。 默认情况下，其值为' '并显示所有类别，但是您可以指定类别的名称，以便仅显示该类别。

$args = array(
		'category_name' => 'tools'
	);

Note that this option accepts the name of a category, and not its slug. The value of this option is case-insensitive: the example above works while my category is named “Tools“. Finally, you should know that you can’t define a list of categories to show with this option: only one name is accepted. So, if you want to display several categories, you must use the category option.

请注意，此选项接受类别的名称，而不接受子类别。 此选项的值不区分大小写：以上示例在我的类别命名为“ Tools ”时起作用。 最后，您应该知道无法使用此选项定义要显示的类别列表：仅接受一个名称。 因此，如果要显示多个类别，则必须使用category选项。

In the case that your scripts don’t care about the categories, and you want to show all the links, regardless of their category, you can set the categorize option to false. Once this is set, it will not sort the links depending on their category. Instead, With this option, you will see all the links, in a fake category named “Bookmarks“.

如果您的脚本不关心类别，并且想要显示所有链接，无论它们的类别如何，都可以将categorize选项设置为false 。 设置此选项后，将不会根据链接的类别对链接进行排序。 相反，使用此选项，您将看到所有链接，它们位于名为“ Bookmarks ”的虚假类别中。

You can combine the option categorize with the others. For example, you can choose to only display the categories 4 and 5 with category, but not show that they are in different categories if you set the option categorize to false.

您可以将选项categorize与其他选项结合使用。 例如，您可以选择只显示类4和5与category ，但并不表明他们是在不同的类别，如果你设置的选项categorize到false 。

$args = array(
		'category' => '4,5',
		'categorize' => false
	);

选择订单 (Choosing the Order)

If you tried the category option with more than one ID, you should notice that WordPress automatically sorted the output. You can indicate '4,5' or '5,4', and the order will always be the same, unless you use another option.

如果您尝试使用具有多个ID的category选项，则应注意WordPress自动对输出进行了排序。 您可以指示'4,5'或'5,4' ，除非您使用其他选项，否则顺序将始终相同。

This option is category_orderby. By default, categories are shown in alphabetical order thanks to the default value name. You can choose to sort categories by their ID with the value id, by their slug with the value slug, or by the number of links they contain with the value count.

此选项为category_orderby 。 默认情况下，由于默认值name ，类别以字母顺序显示。 您可以选择按ID值为id ，按值slug或按值count包含的链接数对类别进行排序。

A second option, named category_order, allows you to reverse the order by choosing the value DESC. By default, this option is set to ASC and the order is not reversed.

第二个名为category_order选项允许您通过选择值DESC来颠倒顺序。 默认情况下，此选项设置为ASC ，并且顺序不颠倒。

The example below displays two categories: the first category is the one which contains the greatest number of links.

下面的示例显示两个类别：第一个类别是包含最多链接的类别。

$args = array(
		'category' => '5,6',
		'category_orderby' => 'count',
		'category_order' => 'DESC'
	);

Analog options can be found to sort the links by themselves. Thanks to the orderby option, you can, in fact, choose how links are sorted. A lot of values are accepted, and you can use several values (separated by a comma), which can be useful if two links are considered ‘equal’ by the first chosen order.

可以找到模拟选项来对链接本身进行排序。 实际上， orderby选项，您可以选择链接的排序方式。 接受许多值，并且您可以使用多个值(用逗号分隔)，如果两个链接被第一个选择的顺序视为“相等”，这将很有用。

You can sort your links using their ID with link_id or their URL with url. Their name can also be used; with name, links are alphabetically sorted and, with length, they are sorted in function of the length of their name. Thanks to the owner value, you can sort the links following the user who added them.

您可以使用自己的身份证用自己的链接进行排序link_id ，或者与URL url 。 也可以使用它们的名称。 使用name ，链接按字母顺序排序，使用length ，则根据其名称的长度排序。 由于owner值，您可以按照添加链接的用户对链接进行排序。

Some values are less useful than others: you can sort the links following their target (target), their description (description), their attached notes (notes), their RSS address (rss) or even the value of their rel attribute (rel).

有些值没有其他有用：您可以按照目标( target )，描述( description )，附加注释( notes )，RSS地址( rss )甚至它们的rel属性( rel )的值对链接进行排序。 。

You can also choose to sort your links using the rating you have assigned to them (rating). A more interesting value is updated: it sorts the links following the last time the page they point to were updated. Finally, if you don’t want to use a specific order, the rand value can be used.

您还可以选择使用已分配给它们的rating ( rating )对链接进行排序。 updated一个更有趣的值：它在链接指向的页面上次updated对其进行排序。 最后，如果您不想使用特定的订单，则可以使用rand值。

By default, links are sorted following their name. You can reverse this order, or any other you chose, by indicating DESC in the order option.

默认情况下，链接按其名称排序。 您可以通过在order选项中指定DESC来颠倒此订单或您选择的其他任何order 。

If you have a lot of links and only want to display a given number of them, you can indicate this number in the limit option. By default, it is set to -1 and shows all the links.

如果您有很多链接，并且只想显示给定数量的链接，则可以在limit选项中指定该数字。 默认情况下，它设置为-1并显示所有链接。

Below is an example which combines several options outlined above. It displays two categories with the order we defined in the previous example. Into these categories, links are sorted following their rating: the order is reversed to show the greatest rating in first. Moreover, we don’t show more than five links by category.

以下是结合了以上概述的几个选项的示例。 它按照我们在上一个示例中定义的顺序显示两个类别。 在这些类别中，链接按照其评分进行排序：顺序颠倒以首先显示最高评分。 此外，按类别显示的链接不会超过五个。

$args = array(
		// Sort the categories
		'category' => '5,6',
		'category_orderby' => 'count',
		'category_order' => 'DESC',

		// Sort the links
		'orderby' => 'rating',
		'order' => 'DESC',
		'limit' => 5
	);

显示隐藏的链接 (Displaying the Hidden Links)

When you add a new link, you can decide to keep it private. WordPress’ default widget doesn’t show private links, but your scripts can, thanks to an option in wp_list_bookmarks(): hide_invisible. This option is a boolean. By default, it is set to true and hides private links, but you can set it to false and it will show all your links, even if some of them are private.

添加新链接时，您可以决定将其设为不公开。 WordPress的默认窗口小部件不显示私有链接，但是由于wp_list_bookmarks()的选项： hide_invisible ，您的脚本可以hide_invisible 。 此选项是布尔值。 默认情况下，它设置为true并隐藏私有链接，但是您可以将其设置为false ，即使其中有些链接是私有的，它也会显示所有链接。

// Show me all the links, even the private ones!
$args(
		'hide_invisible' => false
	);

Note that if your script can be used by other WordPress users apart from you (for example, if your script is included in a theme or plugin that others can use), you should warn these users that your script displays private links, as it is not really a behavior we expect.

请注意，如果您的脚本可以被您以外的其他WordPress用户使用(例如，如果您的脚本包含在其他人可以使用的主题或插件中)，则应警告这些用户，您的脚本会显示私有链接，因为这不是我们期望的行为。

自定义显示 (Customizing the Display)

An option called echo allows you to decide if wp_list_bookmarks() must return (false) or display (true, the default value) the links. However, it returns the string that it echoes, so customizing it is not very practical. That’s why other options allow us to personalize this display.

称为echo的选项使您可以决定wp_list_bookmarks()必须返回( false )或显示( true ，默认值)链接。 但是，它返回它回显的字符串，因此对其进行自定义不是很实用。 这就是为什么其他选项允许我们个性化此显示的原因。

First, the title_li option, is useful in only one case; when you set categorize to false. In fact, WordPress uses this option to display the title above your links if they are not categorized. You can set it to null so that it does not display any title.

首先， title_li选项仅在一种情况下有用。 当您将categorize设置为false 。 实际上，如果未对链接进行分类，WordPress将使用此选项在链接上方显示标题。 您可以将其设置为null ，以使其不显示任何标题。

$args = array(
		'categorize' => false,
		'title_li' => 'Here are ALL my links!'
	);

By default, the names of categories are displayed in an h2 tag. You can change that by using the options title_before and title_after, which respectively display a text before and after the categories names (or the fake category if you set categorize to false). Don’t forget to close in title_after the tags you open in title_before!

默认情况下，类别名称显示在h2标记中。 您可以使用title_before和title_after选项title_before title_after ，它们分别在类别名称(或假类别，如果您将categorize设置为false )之前和之后显示文本。 不要忘记在title_after中打开标签后在title_before中title_before ！

// Display the titles in a smaller heading
$args = array(
		'title_before' => '<h4>',
		'title_after' => '</h4>'
	);

Each category (even the fake one) is in a list item. By default, this item uses the linkcat CSS class, but you can personalize it with the class option.

每个类别(甚至是伪造的类别)都在列表项中。 默认情况下，该项目使用linkcat CSS类，但是您可以使用class选项对其进行个性化设置。

$args = array(
		'class' => 'my-class'
	);

You can go further than just using the class option. With category_before and category_after, you can personalize the text that appears both before and after every category. By default, it defines a li tag, which then contains all the links in the current category.

您不仅可以使用class选项，还可以走得更远。 使用category_before和category_after ，您可以个性化出现在每个类别之前和之后的文本。 默认情况下，它定义一个li标记，该标记随后包含当前类别中的所有链接。

$args = array(
		'category_before' => '<div id=%id class=%class>',
		'category_after' => '</div>'
	);

As you can see, you can insert the %id and %class tags used by WordPress to display the corresponding values.

如您所见，您可以插入WordPress使用的%id和%class标签以显示相应的值。

Finally, we find before (default value: '<li>') and after (default value: '</li>'), which are similar to category_before and category_after but are used for each bookmark. In the same way, we find link_before and link_after, the equivalents of title_before and title_after.

最后，我们找到before (默认值： '<li>' )和after (默认值： '</li>' )，它们类似于category_before和category_after但用于每个书签。 以相同的方式，我们找到link_before和link_after ，它们是title_before和title_after的等效title_after 。

$args = array(
		'before' => '<li class="a-link">',
		'after' => '</li>',
		'link_before' => '<em>',
		'link_after' => '</em>'
	);

产生表格 (Generating a Table)

To see how to use and combine several options in a concrete example, we will now learn how to generate a table listing all our links with just one function: wp_list_bookmarks().

为了在一个具体示例中了解如何使用和组合多个选项，我们现在将学习如何生成一个表，其中仅通过一个函数列出了所有链接： wp_list_bookmarks() 。

For this example, I created nine links, sorted into three categories. There are three links in each category. The first link is rated 10, the second eight and the last seven. We will use wp_list_bookmarks() to generate a table containing all these links. This table will contain a heading line and three more lines (one for each category). In each line, we will find the name of the category and the three links, sorted following their rating. See the image below to have an idea of the result.

在此示例中，我创建了九个链接，分为三个类别。 每个类别中有三个链接。 第一个链接的评分为10，第二个链接的评分为最后7个。 我们将使用wp_list_bookmarks()生成包含所有这些链接的表。 该表将包含一个标题行和另外三行(每个类别一行)。 在每一行中，我们将找到类别的名称和三个链接，并按照它们的等级进行排序。 请参阅下图了解结果。

You can reproduce this example without the need to have as many links as are provided below. In fact, you just need to have the same number of links in each category (and the same rating system in each category).

您可以重现此示例，而无需具有下面提供的尽可能多的链接。 实际上，您只需要在每个类别中拥有相同数量的链接(并且在每个类别中具有相同的评分系统)。

First, let’s create our table.

首先，让我们创建表。

<table>
	<tr>
		<th>Category</th>
		<th>10</th>
		<th>8</th>
		<th>7</th>
	</tr>

	< ?php
	$args = array(
		);

	wp_list_bookmarks($args);
	?>
</table>

Currently, this code won’t work: by default, `wp_list_bookmarks()` generates a list, and you should know that inserting a list into a table like this is not the right thing to do. So, let’s indicate the right options in our `$args` array.

当前，此代码将不起作用：默认情况下，`wp_list_bookmarks()`会生成一个列表，并且您应该知道将列表插入到这样的表中是不正确的。 因此，让我们在$ args数组中指定正确的选项。

First, we choose the categories to display. If you want to display all your categories, you can skip this options. Here, I chose to display three categories, sorted by their name.

首先，我们选择要显示的类别。 如果要显示所有类别，则可以跳过此选项。 在这里，我选择显示三个类别，按其名称排序。

$args = array(
		// Categories to display
		'category' => '4,5,6',
		'category_orderby' => 'name'
	);

Then, we sort our links. We chose in the heading line to first display the 10-rated link, so we ask wp_list_bookmarks() to sort the links following their rating, and then we reverse the default ascending order.

然后，我们对链接进行排序。 我们在标题行中选择首先显示10个评分的链接，因此我们要求wp_list_bookmarks()按照链接的评分对链接进行排序，然后反转默认的升序。

$args = array(
		// Sort the links
		'orderby' => 'rating',
		'order' => 'DESC'
	);

Now, we need to indicate that we don’t want to create a list. We will here use the category_before and category_after options to customize the code around each category. Before the category we open a tr tag that we close right after.

现在，我们需要表明我们不想创建列表。 我们将在这里使用category_before和category_after选项来自定义每个类别的代码。 在类别之前，我们打开一个tr标记，然后紧随其后关闭。

$args = array(
		// One category = one line
		'category_before' => '<tr>',
		'category_after' => '</tr>'
	);

That’s better than the default output which displays a li tag for each category. But it’s still not enough, as we want to display the categories’ names in a heading cell. To do that, we use the title_before and title_after options to customize the code before and after each name.

这要好于默认输出，后者为每个类别显示一个li标签。 但这还不够，因为我们想在标题单元格中显示类别的名称。 为此，我们使用title_before和title_after选项在每个名称之前和之后自定义代码。

$args = array(
		// Category's name in a heading cell
		'title_before' => '<th>',
		'title_after' => '</th>'
	);

Finally, by default, all the links are displayed in a li tag: thanks to the before and after options we changed to use table cells.

最后，默认情况下，所有链接都显示在li标记中：由于使用了before和after选项，我们更改为使用表格单元格。

$args = array(
		// One link = one table cell
		'before' => '<td>',
		'after' => '</td>'
	);

And here we are! All you have to do now is combine the options we saw above to have the right result.

我们到了！ 您现在要做的就是结合上面看到的选项以得到正确的结果。

$args = array(
		// Categories to display
		'category' => '4,5,6',
		'category_orderby' => 'name',

		// Sort the links
		'orderby' => 'rating',
		'order' => 'DESC',

		// One category = one line
		'category_before' => '<tr>',
		'category_after' => '</tr>',

		// Category's name in a heading cell
		'title_before' => '<th>',
		'title_after' => '</th>',

		// One link = one table cell
		'before' => '<td>',
		'after' => '</td>'
	);

Now, it’s time to ask a question: is this example useful? In theory, yes. It is useful to see a concrete example of how to use the wp_list_bookmarks() function to generate something other than a list. The available options allow us to create virtually anything we want.

现在，该问一个问题了：这个例子有用吗？ 从理论上讲，是的。 看看如何使用wp_list_bookmarks()函数生成列表以外的内容的具体示例很有用。 可用的选项使我们几乎可以创建所需的任何内容。

But in practice, it is not really overly helpful. wp_list_bookmarks() is not the perfect function to use to achieve what we did. In fact, what if the rating system is not exactly the same in each category? What if we want to display the rating and not only the link’s name?

但是实际上，它并不是真的有太大帮助。 wp_list_bookmarks()并不是用来实现我们所做的完美功能。 实际上，如果每个类别的评分系统都不完全相同怎么办？ 如果我们要显示等级而不只是链接名称怎么办？

There are a lot of things that are simply not possible with wp_list_bookmarks(), and that’s why the other functions exist.

使用wp_list_bookmarks()根本不可能完成很多事情，这就是为什么存在其他函数的原因。

结论 (In Conclusion)

The WordPress Links Manager API is a very useful tool and, now, you can play with it the way you want to, thanks to the functions covered in this article.

WordPress链接管理器API是一个非常有用的工具，由于本文介绍的功能，现在您可以按照自己的方式进行操作。

In theory, you could do a lot of things with only the wp_list_bookmarks() function, by playing with the available options. However, this is not the best solution when it comes to creating a sound and readable code. That’s why the other functions we will see in the next article in this series are very important.

从理论上讲，您可以仅通过wp_list_bookmarks()函数通过使用可用选项来完成很多工作。 但是，这不是创建声音和可读代码的最佳解决方案。 这就是为什么我们将在本系列下一篇文章中看到的其他功能非常重要的原因。

翻译自: https://www.sitepoint.com/mastering-wordpress-links-manager-api/