wordpress api_如何使用类别API在WordPress中列出类别

你的名字 2022-12-03 01:50 361阅读 0赞

wordpress api

In a previous article we saw [how to easily work with categories in WordPress][]. We covered how we can sort our posts into different categories, which can then be edited or deleted.

在上一篇文章中，我们看到了[如何轻松使用WordPress中的类别][how to easily work with categories in WordPress] 。 我们介绍了如何将帖子分类为不同的类别，然后可以对其进行编辑或删除。

Having covered the basics, it’s now time to have a look at something that will be of more interest to developers: the Categories API, and how to retrieve and display category data.

在介绍了基础知识之后，现在该看一下开发人员更感兴趣的内容：Categories API，以及如何检索和显示类别数据。

Like the [Links Manager API][], the Categories API is a big topic, even bigger in terms of the number of functions available. In this article, we’ll be covering one function that is useful when we want to list our categories.

像[Links Manager API一样][Links Manager API] ，Categories API是一个大话题，就可用功能而言，它甚至更大。 在本文中，我们将介绍一个在列出类别时有用的功能。

## 清单类别 **(**Listing Categories**)** ##

In the Links Manager API we find an important function that allows us to list our links. It’s no surprise therefore that we find the same thing in the Categories API: `wp_list_categories()`, this is the function we’ll work with here.

在Links Manager API中，我们找到了一个重要的功能，该功能使我们可以列出我们的链接。 因此，我们在Categories API中找到相同的东西也就不足为奇了： `wp_list_categories()` ，这是我们将在此处使用的功能。

Basically, you have to call this function in the place you want to see your categories listed.

基本上，您必须在要查看列出的类别的地方调用此函数。

wp_list_categories();

![WP list categories][]

As you can imagine, this result is entirely customizable. To mould it to our needs we can pass an argument to this function: an array containing values for the options we want to set. Let’s have a look at some of the available options.

可以想象，此结果是完全可定制的。 为了使它符合我们的需求，我们可以向该函数传递一个参数：一个包含要设置的选项值的数组。 让我们看一些可用的选项。

## 选择要显示的类别 **(**Choosing the Categories to Display**)** ##

Before seeing how to customize the output, we’ll begin with some options that allow us to choose what to display.

在查看如何自定义输出之前，我们将从一些允许我们选择要显示的内容的选项开始。

### 包含和排除类别 **(**Include and Exclude Categories**)** ###

First we find the option `include` which accepts a list of category IDs to display. When you use this option, `wp_list_categories()` will only display the categories with the IDs you passed it. You can indicate one or more IDs. If you want to indicate two or more IDs, you must separate these numbers with a comma.

首先，我们找到选项`include` ，该选项接受要显示的类别ID的列表。 使用此选项时， `wp_list_categories()`将仅显示带有您传递的ID的类别。 您可以指定一个或多个ID。 如果要指示两个或多个ID，则必须用逗号分隔这些数字。

$args = array(
    		'include' => '15,16,9'
    	);
    
    wp_list_categories($args);

If on the other hand you don’t want to choose what to display, but rather what not to display, the `exclude` option is for you. It can be used exactly like `include` .

另一方面，如果您不想选择要显示的内容，而是不想显示的内容，则`exclude`选项适合您。 可以像`include`一样使用它。

$args = array(
    		'exclude' => '15,16,9'
    	);

Note that if you want to use the `exclude` option, `include` must be empty (its default value). Otherwise, the `include` option wins and only the categories passed to it will be displayed.

请注意，如果要使用`exclude`选项，则`include`必须为空(其默认值)。 否则， `include`选项将获胜，并且只会显示传递给它的类别。

Another option to exclude categories is `exclude_tree`. Once again, it accepts a comma-separated list of categories’ IDs to exclude. The difference is that it will exclude the selected categories and all their children. Note that, to see this option working, you must set the option `hierarchical` to `0` (we will see below what this option does).

排除类别的另一种选择是`exclude_tree` 。 再次，它接受要排除的类别ID的逗号分隔列表。 不同之处在于它将排除所选类别及其所有子级。 请注意，要使此选项正常工作，必须将选项`hierarchical`设置为`0` (我们将在下面看到此选项的作用)。

// 14 is the ID of "My life", parent of "My goldfish" and "My garden" which will also be hidden
    $args = array(
    		'exclude_tree' => '14',
    		'hierarchical' => 0
    	);

### 订购输出 **(**Ordering the Output**)** ###

By default, categories are listed in alphabetical order. You can modify this behavior thanks to the `orderby` option, which accepts a string. You can pick from the following options: `ID` to order the categories by their ID (no, really?), `name` to sort them alphabetically (the default value), `slug` to sort them in the alphabetical order of their slugs, and `count` to order by the number of posts they contain.

默认情况下，类别按字母顺序列出。 您可以通过`orderby`选项修改此行为，该选项接受一个字符串。 您可以从以下选项中选择： `ID` ，以按其ID对类别进行排序(不，真的吗？)； `name`以按字母顺序对类别进行排序(默认值)； `slug` ，以其类别的字母顺序对其进行排序；以及按顺序`count`通过它们包含的帖子数。

The chosen order can be reversed by setting `DESC` (descending) as a value for the `order` option (by default this option is set to `ASC` (ascending)).

通过将`DESC` (降序)设置为`order`选项的值(默认情况下，此选项设置为`ASC` (升序))，可以反转所选订单。

In the example below, we list the categories by the number of posts they contain: as the order is reversed, the category containing the greatest number of posts will be the first one to be displayed.

在下面的示例中，我们按类别包含的帖子数列出类别：随着顺序的反转，包含最多帖子数的类别将成为第一个显示的类别。

$args = array(
    		'orderby' => 'count',
    		'order' => 'DESC'
    	);

### 限制显示类别的数量 **(**Limit the Number of Displayed Categories**)** ###

Once we have ordered our categories, we may want to limit the number of items listed. This can be achieved using the `number` option. By default, this option is set to `null` and there is no limit so all the categories are shown. By specifying a number, you can define the maximum number of categories to display. For example, we can list the five most used categories.

订购类别后，我们可能希望限制列出的项目数。 这可以使用`number`选项来实现。 默认情况下，此选项设置为`null`并且没有限制，因此显示所有类别。 通过指定数字，可以定义要显示的最大类别数。 例如，我们可以列出五个最常用的类别。

$args = array(
    		'orderby' => 'count',
    		'order' => 'DESC',
    		'number' => 5
    	);

This example lists the categories with the greatest number of posts. Another solution is to hide the unused categories. To do that we can use `hide_empty`, a boolean set to `1` by default: empty categories are not shown. You can choose to display them by setting this to `0`.

本示例列出了帖子数最多的类别。 另一种解决方案是隐藏未使用的类别。 为此，我们可以使用`hide_empty` ，默认情况下将布尔值设置为`1` ：不显示空类别。 您可以通过将其设置为`0`来选择显示它们。

// Show me all the categories, even the empty ones
    $args = array(
    		'hide_empty' => 0
    	);

## 指定要显示的详细信息 **(**Specifying Details to be Displayed**)** ##

Details are important, and there are always some that we want to include.

细节很重要，我们总是要包含一些细节。

### 专柜！ **(**Counters!**)** ###

For example you may want to display the number of posts contained in each category. To display this you can use the option `show_count` and set it to `1`. By default, this boolean is set to `0` and this count is not shown.

例如，您可能要显示每个类别中包含的帖子数。 要显示此内容，可以使用选项`show_count`并将其设置为`1` 。 默认情况下，此布尔值设置为`0`并且不显示此计数。

$args = array(
    		'show_count' => 1
    	);

Note that a post in a child category will also be added to the total number of posts of its parent. For example, the screenshot below is taken with three posts in the “*My life*” category: while there is only one post in this category, the two others are in the child categories.

请注意，子类别中的帖子也将添加到其父类别的帖子总数中。 例如，下面的屏幕快照是在“ *我的生活* ”类别中的三篇帖子中拍摄的：尽管此类别中只有一篇帖子，但其他两篇属于子类别。

![WP list categories counters][]

You can modify this behavior thanks to the option `pad_counts`. If you set this to `0`, the parents’ counts will only display the number of posts in these parents’ categories and not include the posts in their child categories.

您可以使用`pad_counts`选项来修改此行为。 如果将此`0`设置为`0` ，则父母的计数将仅显示这些父母类别中的帖子数，而不包括其子类别中的帖子。

$args = array(
    		'show_count' => 1,
    		'pad_counts' => 0
    	);

![WP list categories counters parents][]

### 类别说明 **(**Descriptions of the Categories**)** ###

As we saw in our previous article, we can set a description for our categories. This description can be displayed with the option `use_desc_for_title`. It’s a boolean set to `1` by default: descriptions are displayed in the `title` attribute of the links in the list. If you don’t want to see this description you can set this to `0`.

正如我们在上一篇文章中看到的，我们可以为我们的类别设置一个描述。 可以使用`use_desc_for_title`选项显示此描述。 默认情况下，它是一个布尔值，设置为`1` ：描述显示在列表中链接的`title`属性中。 如果您不想看到此描述，可以将其设置为`0` 。

$args = array(
    		'use_desc_for_title' => 1
    	);

![categories description][]

### 提要 **(**Feeds**)** ###

Just as WordPress generates a feed for your posts, it also creates one for every category. Visitors can choose to only follow the updates of categories they are interested in, if they don’t like all of your content.

正如WordPress为您的帖子生成供稿一样，它也为每个类别创建一个供稿。 如果访客不喜欢您所有的内容，他们可以选择仅关注他们感兴趣的类别的更新。

The links to these feeds can be shown in the list of our categories, thanks to the option `feed`. By default this option is set to an empty string and links are not shown. The code below shows how to enable this option.

由于提供了`feed`选项，因此可以在我们的类别列表中显示这些feed的链接。 默认情况下，此选项设置为空字符串，并且不显示链接。 下面的代码显示了如何启用此选项。

$args = array(
    		'feed' => 'RSS'
    	);

![categories feeds][]

By default, the linked feed is the RSS2 one. But WordPress can generate more feed types. If you prefer Atom for example, you can force WordPress to show this type of feed instead of the RSS2 one.

默认情况下，链接的提要是RSS2。 但是WordPress可以生成更多的供稿类型。 例如，如果您更喜欢Atom，则可以强制WordPress显示这种类型的供稿，而不是RSS2。

To select the type of feed you want to see displayed you can specify any of the following options : `atom`, `rss`, `rss2` and `rdf`.

要选择要显示的供稿类型，可以指定以下任何选项： `atom` ， `rss` ， `rss2`和`rdf` 。

$args = array(
    		'feed' => 'Atom',
    		'feed_type' => 'atom'
    	);

Finally, if you prefer to use an image to link to your RSS feeds, you can indicate the URL of the image you want to see in the `feed_image` option. The text in the `feed` option will then become the alternative text for the image.

最后，如果您喜欢使用图像链接到RSS feed，则可以在`feed_image`选项中指定要查看的图像的URL。 `feed`选项中的文本将成为图像的替代文本。

$args = array(
    		'feed' => 'RSS',
    		'feed_image' => 'http://website.org/my-awesome-rss-image.png'
    	);

## 该类别是当前类别吗？ **(**Is This Category the Current One?**)** ##

If you use `wp_list_categories()` on an archive page (in the `archive.php` template), you can see that the current category (the one displayed by the archive page) is highlighted: the `li` tag enclosing the link to this category has one more class than the other ones, named `current-cat`. You don’t have to do anything to activate this behavior, and you can’t deactivate it (but you are free to not use it in your CSS!).

如果在存档页面(在`archive.php`模板中`wp_list_categories()`上使用`wp_list_categories()` ，则可以看到当前类别(由存档页面显示的类别)突出显示：包含指向该类别链接的`li`标签还有一个该类比其他类命名为`current-cat` 。 您无需执行任何操作即可激活此行为，也无法停用它(但是您可以随意不在CSS中使用它！)。

However, maybe it’s a behavior you want to see on more pages, like those which display a post. The good news is you can, thanks to the option `current_category`. This boolean is set to `0` by default. By setting it to `1` the current category will be highlighted with the previously quoted class.

但是，也许这是您希望在更多页面上看到的行为，例如那些显示帖子的行为。 好消息是，由于选项`current_category` ，您可以做到。 默认情况下，此布尔值设置为`0` 。 通过将其设置为`1` ，当前类别将以先前引用的类别突出显示。

$args = array(
    		'current_category' => 1
    	);

For example, let’s assume that we display the list of our categories on the `single.php` template. Then, with the previous array, the category of the current post is highlighted thanks to the class `current-cat`. All we have to do now to display it is to add the appropriate CSS.

例如，假设我们在`single.php`模板上显示类别列表。 然后，使用前一个数组，由于类`current-cat`突出显示了当前帖子的类别。 现在我们要做的就是添加适当CSS。

## 显示层次结构 **(**Showing the Hierarchy**)** ##

If you have many categories, it’s a good idea to organise them into logical hierarchies, where we find parent categories and their children underneath them. There are a number of options for handling the display of hierarchies.

如果您有很多类别，将它们组织成逻辑层次结构是一个好主意，我们可以在其中找到父类别及其子类别。 有许多选项可以处理层次结构的显示。

We’ll look at `hierarchical` first. It’s a boolean set by default to `1`, whereby `wp_list_categories()` shows the hierarchy between the categories (with parents and children), exactly as in the screenshots since the beginning of this article. If you don’t want to show your hierarchy you can set it to `0`: your categories will then be listed in one column without indenting the child categories.

我们将首先看`hierarchical` 。 这是一个默认设置为`1`的布尔值，其中`wp_list_categories()`显示了类别(包括父项和子项)之间的层次结构，与自本文开始以来的屏幕快照中的情况完全相同。 如果您不想显示层次结构，可以将其设置为`0` ：然后，您的类别将列在一栏中，而不会缩进子类别。

Note the side effect of `hierarchical`: if you choose to display the hierarchy, then the parents categories will always be shown, even if they are empty and the `hide_empty` option is set to `1`.

注意`hierarchical`的副作用：如果选择显示层次结构，则将始终显示父类别，即使它们为空且`hide_empty`选项设置为`1` 。

// Don't show me the hierarchy
    $args = array(
    		'hierarchical' => 0
    	);

You can also use hierarchy to do other things like displaying the children of a given category using `child_of` . We could describe it as the opposite of `exclude_tree`: we give it the ID of a category and `wp_list_categories()` will only display its children. However, the name of the parent category is not displayed.

您还可以使用层次结构执行其他操作，例如使用`child_of`显示给定类别的子`child_of` 。 我们可以将其描述为`exclude_tree`的反义词：我们给它指定类别的ID，而`wp_list_categories()`将仅显示其子级。 但是，不显示父类别的名称。

// Show me all the children of this category
    $args = array(
    		'child_of' => 14
    	);

Unlike `exclude_tree`, we can only pass a single ID to `child_of`.

与`exclude_tree`不同，我们只能将单个ID传递给`child_of` 。

The `depth` option allows you to control the number of levels which can be displayed in the list. It can be useful if you love categories and have a complex tree with a lot of generations. By default it is set to `0` and shows all the generations. The example below shows only two levels of categories: the parents and their first level children. If these children have their own child categories, they won’t be shown.

`depth`选项使您可以控制列表中可以显示的级别数。 如果您喜欢类别并且有一棵具有很多世代的复杂树，则它可能会很有用。 默认情况下，它设置为`0`并显示所有世代。 下面的示例仅显示两个级别的类别：父母和他们的第一级孩子。 如果这些孩子有自己的孩子类别，则不会显示它们。

$args = array(
    		'depth' => 2
    	);

Note that `depth` is linked to `hierarchical`. In fact, if you set `hierarchical` to `0`, giving a value to `depth` will be useless: all the categories will be shown, regardless of their levels in the tree. On the contrary, you can also override the value of `hierarchical` with `depth` in one case: you set `depth` to `-1`. The effect of this value is to display all the categories without any relation. All of the categories will be shown in one column, even if `hierarchical` is set to `1`.

请注意， `depth`与`hierarchical` 。 实际上，如果将`hierarchical`设置为`0` ，则为`depth`赋予一个值将是无用的：将显示所有类别，无论它们在树中的级别如何。 相反，在一种情况下，您也可以用`depth`覆盖`hierarchical`的值：将`depth`设置为`-1` 。 此值的作用是显示所有类别而没有任何关系。 即使将`hierarchical`设置为`1` ，所有类别也将显示在一列中。

## 控制输出 **(**Controlling the Output**)** ##

By default, `wp_list_categories()` displays the list of our categories. If you don’t want that and prefer to store the result in a variable to display it later, you can set `echo` to `0`.

默认情况下， `wp_list_categories()`显示我们的类别列表。 如果您不希望这样做，而是希望将结果存储在变量中以便以后显示，则可以将`echo`设置为`0` 。

$args = array(
    		'echo' => 0
    	);
    
    $cats = wp_list_categories($args);

This can be useful if you want to modify the list before displaying it.

如果要在显示列表之前对其进行修改，这将很有用。

Next, let’s look at `show_option_none`. By default, if `wp_list_categories()` doesn’t find any category (it can happen if the other options are too restrictive for example), it displays the text “*No categories*“. You can change this to the text you want using this option.

接下来，让我们看看`show_option_none` 。 默认情况下，如果`wp_list_categories()`未找到任何类别(例如，如果其他选项限制太严格，则可能发生)，它将显示文本“ *No Categories* ”。 您可以使用此选项将其更改为所需的文本。

$args = array(
    		'show_option_none' => 'Nothing found :('
    	);

Next `title_li`. In our tests, you may have noticed that the list of categories is encapsulated into an item of another list. This can be useful if you use `wp_list_categories()` in a menu for example. Moreover, WordPress displays a title for this list, which is by default “*Categories*“.

下一个`title_li` 。 在我们的测试中，您可能已经注意到类别列表被封装到另一个列表的项目中。 例如，如果您在菜单中使用`wp_list_categories()` ，这将很有用。 此外，WordPress会为此列表显示标题，默认情况下为“ *Categories* ”。

You can modify this default title or even disable it by playing with `title_li`. It accepts a string, which is the title to display. If you give this option an empty string, the list of categories won’t be encapsulated in another list at all.

您可以修改此默认标题，甚至可以通过使用`title_li`禁用它。 它接受一个字符串，这是要显示的标题。 如果为该选项提供一个空字符串，则类别列表将根本不会封装在另一个列表中。

$args = array(
    		'title_li' => 'My awesome categories'
    	);

Be careful: if you disable the displaying of the list with an empty string you must enclose your list in `ul` tags!

请注意：如果禁用以空字符串显示列表，则必须将列表包含在`ul`标签中！

You don’t like lists? You will love the `style` option: by default it is set to `list` and `wp_list_categories()` displays categories as list items. If you set `style` to `none`, your categories will be separated by `br` tags.

你不喜欢清单？ 您将喜欢`style`选项：默认情况下，它设置为`list`而`wp_list_categories()`类别显示为列表项。 如果将`style`设置为`none` ，则类别将由`br`标签分隔。

$args = array(
    		'style' => 'none'
    	);

Finally, you can ask WordPress to display a link to all your categories thanks to the option `show_option_all`. You give a string to this option, and WordPress will display a new link, pointing to all of your categories.

最后， `show_option_all`选项`show_option_all` ，您可以要求WordPress显示指向所有类别的链接。 您为该选项输入一个字符串，WordPress将显示一个指向您所有类别的新链接。

$args = array(
    		'show_option_all' => 'All categories'
    	);

## 结论 **(**Conclusion**)** ##

That’s it for `wp_list_categories()`. The number of options available for this function is pretty big, as you can see.

`wp_list_categories()`就是这样。 如您所见，此功能可用的选项数量很多。

Of course, the Categories API is not limited to this function. However, it is an important one: if you don’t have any specific need and just want a basic list of categories, don’t look for another function, this one is your simplest option!

当然，类别API不限于此功能。 但是，这是一个重要的问题：如果您没有任何特定的需要，而只想要基本的类别列表，则不要寻找其他功能，这是您最简单的选择！

Note that we didn’t talk in this article about `wp_dropdown_categories()`. This function displays our categories into a dropdown HTML element. Like `wp_list_categories()`, its output can be fully customized thanks to an array of options. These options are similar to those available with `wp_list_categories()` , so we won’t describe them here. The only difficulty is that some options have other default values. To learn more about `wp_dropdown_categories()`, you can go to the [WordPress Codex][].

请注意，我们在本文中没有谈论`wp_dropdown_categories()` 。 此功能将我们的类别显示在下拉HTML元素中。 像`wp_list_categories()` ，由于有一系列选项，其输出可以完全自定义。 这些选项与`wp_list_categories()`可用的选项相似，因此我们在这里不再对其进行描述。 唯一的困难是某些选项具有其他默认值。 要了解有关`wp_dropdown_categories()`更多信息，可以转到[WordPress Codex][] 。

But there are still other cases: what if we want to display our categories in a special way? In this case, `wp_list_categories()` is not flexible enough, as we need to build our own DOM tree. That’s why, in the next article, we’ll have a look at some other useful functions in the Categories API.

但是还有其他情况：如果我们想以特殊方式显示类别怎么办？ 在这种情况下， `wp_list_categories()`不够灵活，因为我们需要构建自己的DOM树。 因此，在下一篇文章中，我们将看看Categories API中的其他有用功能。

> 翻译自: [https://www.sitepoint.com/wordpress-categories-api/][https_www.sitepoint.com_wordpress-categories-api]

wordpress api

[how to easily work with categories in WordPress]: https://www.sitepoint.com/wordpress-categories-explained/
[Links Manager API]: https://www.sitepoint.com/mastering-wordpress-links-manager-api/
[WP list categories]: /images/20221123/855022adac9e408a819d5ad65eedbf34.png
[WP list categories counters]: /images/20221123/186bf68669494b19bc7110d603c6106a.png
[WP list categories counters parents]: /images/20221123/aac89eb2c6ff484a8f8d5375e4ec2c8d.png
[categories description]: /images/20221123/17b2b07cf2724542b677fb7565d7c66f.png
[categories feeds]: /images/20221123/4d56c64b1f184c9f95e59555a6abf8a9.png
[WordPress Codex]: https://codex.wordpress.org/Function_Reference/wp_dropdown_categories
[https_www.sitepoint.com_wordpress-categories-api]: https://www.sitepoint.com/wordpress-categories-api/