get_the_category_list()

💡 云策文档标注

概述

get_the_category_list() 函数用于检索文章的分类列表，可以输出为 HTML 列表或自定义分隔符格式。它通常用于快速生成文章元数据中的分类链接，适合简单场景，而更复杂的列表功能建议使用 wp_list_categories()。

关键要点

函数返回文章的分类列表字符串，支持自定义分隔符和父级分类显示方式。
参数 $separator 控制分隔符，默认为空字符串时生成无序列表；$parents 可选 'multiple'、'single' 或空字符串，用于处理父级分类；$post_id 指定文章 ID，默认为当前文章。
内部使用 get_the_category() 获取分类，并应用过滤器 the_category 和 the_category_list 进行自定义。
函数检查文章类型是否关联到分类法，并处理未分类情况。

代码示例

// 生成逗号分隔的分类列表
echo get_the_category_list( ', ' );

// 生成无序列表（默认行为）
echo get_the_category_list();

// 指定父级显示为 'multiple'
echo get_the_category_list( '', 'multiple' );

注意事项

对于复杂分类列表需求，推荐使用 wp_list_categories() 函数。
函数输出可通过 the_category 和 the_category_list 过滤器进行修改。
确保文章类型支持分类法，否则可能返回空或“未分类”字符串。

📄 原文内容

Retrieves category list for a post in either HTML list or custom format.

Description

Generally used for quick, delimited (e.g. comma-separated) lists of categories, as part of a post entry meta.

For a more powerful, list-based function, see wp_list_categories() .

Parameters

$separatorstringoptional: Separator between the categories. By default, the links are placed in an unordered list. An empty string will result in the default behavior.
$parentsstringoptional: How to display the parents. Accepts 'multiple', 'single', or empty.
Default empty string.
$post_idint|falseoptional: ID of the post to retrieve categories for. Defaults to the current post.

Default:false

Return

string Category list for a post.

Source

function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
	global $wp_rewrite;

	if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
		/** This filter is documented in wp-includes/category-template.php */
		return apply_filters( 'the_category', '', $separator, $parents );
	}

	/**
	 * Filters the categories before building the category list.
	 *
	 * @since 4.4.0
	 *
	 * @param WP_Term[] $categories An array of the post's categories.
	 * @param int|false $post_id    ID of the post to retrieve categories for.
	 *                              When `false`, defaults to the current post in the loop.
	 */
	$categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );

	if ( empty( $categories ) ) {
		/** This filter is documented in wp-includes/category-template.php */
		return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
	}

	$rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';

	$thelist = '';
	if ( '' === $separator ) {
		$thelist .= '<ul class="post-categories">';
		foreach ( $categories as $category ) {
			$thelist .= "nt<li>";
			switch ( strtolower( $parents ) ) {
				case 'multiple':
					if ( $category->parent ) {
						$thelist .= get_category_parents( $category->parent, true, $separator );
					}
					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';
					break;
				case 'single':
					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '"  ' . $rel . '>';
					if ( $category->parent ) {
						$thelist .= get_category_parents( $category->parent, false, $separator );
					}
					$thelist .= $category->name . '</a></li>';
					break;
				case '':
				default:
					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a></li>';
			}
		}
		$thelist .= '</ul>';
	} else {
		$i = 0;
		foreach ( $categories as $category ) {
			if ( 0 < $i ) {
				$thelist .= $separator;
			}
			switch ( strtolower( $parents ) ) {
				case 'multiple':
					if ( $category->parent ) {
						$thelist .= get_category_parents( $category->parent, true, $separator );
					}
					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';
					break;
				case 'single':
					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>';
					if ( $category->parent ) {
						$thelist .= get_category_parents( $category->parent, false, $separator );
					}
					$thelist .= "$category->name</a>";
					break;
				case '':
				default:
					$thelist .= '<a href="' . esc_url( get_category_link( $category->term_id ) ) . '" ' . $rel . '>' . $category->name . '</a>';
			}
			++$i;
		}
	}

	/**
	 * Filters the category or list of categories.
	 *
	 * @since 1.2.0
	 *
	 * @param string $thelist   List of categories for the current post.
	 * @param string $separator Separator used between the categories.
	 * @param string $parents   How to display the category parents. Accepts 'multiple',
	 *                          'single', or empty.
	 */
	return apply_filters( 'the_category', $thelist, $separator, $parents );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘the_category’, string $thelist, string $separator, string $parents ): Filters the category or list of categories.
apply_filters( ‘the_category_list’, WP_Term[] $categories, int|false $post_id ): Filters the categories before building the category list.

Uses	Description
get_the_category()`wp-includes/category-template.php`	Retrieves post categories.
get_category_parents()`wp-includes/category-template.php`	Retrieves category parents with separator.
get_category_link()`wp-includes/category-template.php`	Retrieves category link URL.
is_object_in_taxonomy()`wp-includes/taxonomy.php`	Determines if the given object type is associated with the given taxonomy.
get_post_type()`wp-includes/post.php`	Retrieves the post type of the current post or of a given post.
WP_Rewrite::using_permalinks()`wp-includes/class-wp-rewrite.php`	Determines whether permalinks are being used.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_url()`wp-includes/formatting.php`	Checks and cleans a URL.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 4 more Show less

Used by	Description
the_category()`wp-includes/category-template.php`	Displays category list for a post in either HTML list or custom format.

Changelog

Version	Description
1.5.1	Introduced.

User Contributed Notes

Skip to note 3 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
Display as List Items
By leaving the $separator value empty, it will generate an unordered list instead, complete with classes.
Result:
```
<ul class="post-categories">
	<li>
		<a href="<a href="http://myblog.com/category/business&quot" rel="nofollow ugc">http://myblog.com/category/business"</a>; title="View all posts in Business" rel="category tag">Business</a>
	</li>
</ul>
```
Log in to add feedback

Skip to note 4 content

Codex

11 years ago

Implementation in WordPress default Twenty Eleven theme
In content-single.php:

%5$s</a>. Bookmark the <a href="%3$s" title="Permalink to %4$s" rel="bookmark">permalink</a>.', 'twentyeleven' );
} elseif ( '' != $categories_list ) {
	$utility_text = __( 'This entry was posted in %1$s by <a href="%6$s">%5$s</a>. Bookmark the <a href="%3$s" title="Permalink to %4$s" rel="bookmark">permalink</a>.', 'twentyeleven' );
} else {
	$utility_text = __( 'This entry was posted by <a href="%6$s">%5$s</a>. Bookmark the <a href="%3$s" title="Permalink to %4$s" rel="bookmark">permalink</a>.', 'twentyeleven' );
}

printf(
	$utility_text,
	$categories_list,
	$tag_list,
	esc_url( get_permalink() ),
	the_title_attribute( 'echo=0' ),
	get_the_author(),
	esc_url( get_author_posts_url( get_the_author_meta( 'ID' ) ) )
);
?>

云策 WordPress 开发者社区

函数文档