wp_get_post_categories()

💡 云策文档标注

概述

wp_get_post_categories() 函数用于获取文章的分类列表，作为主题和插件的兼容层，并抽象化分类法层的复杂性。它基于 wp_get_object_terms() 实现，但返回结果未缓存，可能影响性能。

关键要点

函数返回文章的分类列表，支持通过 $args 参数自定义查询，如字段类型（ids、names、all）、排序和排除特定分类。
参数 $post_id 默认为 0，不自动使用全局 $post 的 ID；$args 数组可传递 WP_Term_Query 支持的参数，默认 fields 为 'ids'。
返回类型取决于 $args 中的 fields 设置：'all' 或 'all_with_object_id' 返回 WP_Term 对象数组，'ids' 返回分类 ID 数组，'names' 返回分类名称数组；若 'category' 分类法不存在则返回 WP_Error。
性能注意事项：函数结果未缓存，每次调用都会查询数据库，建议谨慎使用；对于性能敏感场景，推荐使用 get_the_category() 等替代函数。

代码示例

// 获取分类 ID 数组（默认行为）
$post_categories = wp_get_post_categories( $post_id );

// 获取 WP_Term 对象数组以直接访问分类信息
$post_categories = wp_get_post_categories( $post_id, array( 'fields' => 'all' ) );
if( $post_categories ) {
    foreach( $post_categories as $c ) {
        echo "Category Name: " . $c->name . ", Slug: " . $c->slug;
    }
}

// 获取分类名称数组并按降序排列
$terms_list = wp_get_post_categories( $post_id, array( 'fields' => 'names', 'order' => 'DESC' ) );
if( $terms_list ) {
    foreach( $terms_list as $term ) {
        echo esc_html( $term );
    }
}

// 排除特定分类 ID（如 1 和 7）
$terms_list = wp_get_post_categories( $post_id, array( 'fields' => 'names', 'exclude' => '1,7' ) );

注意事项

由于函数未缓存结果，频繁调用可能导致数据库负载增加，建议在需要高性能的场景下使用其他缓存函数或优化查询。

📄 原文内容

Retrieves the list of categories for a post.

Description

Compatibility layer for themes and plugins. Also an easy layer of abstraction away from the complexity of the taxonomy layer.

Parameters

$post_idintoptional: The Post ID. Does not default to the ID of the global $post. Default 0.
$argsarrayoptional: Category query parameters.
See WP_Term_Query::__construct() for supported arguments.

Default:array()

array|WP_Error List of categories. If the $fields argument passed via $args is 'all' or 'all_with_object_id', an array of WP_Term objects will be returned. If $fields is 'ids', an array of category IDs. If $fields is 'names', an array of category names.
WP_Error object if 'category' taxonomy doesn’t exist.

More Information

The results from wp_get_post_categories() aren’t cached which will result in a database call being made every time this function is called. Use this function with care. For performance, functions like get_the_category() should be used to return categories attached to a post.

Source

function wp_get_post_categories( $post_id = 0, $args = array() ) {
	$post_id = (int) $post_id;

	$defaults = array( 'fields' => 'ids' );
	$args     = wp_parse_args( $args, $defaults );

	$cats = wp_get_object_terms( $post_id, 'category', $args );
	return $cats;
}

View all references View on Trac View on GitHub

Uses	Description
wp_get_object_terms()`wp-includes/taxonomy.php`	Retrieves the terms associated with the given object(s), in the supplied taxonomies.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.

Used by	Description
bulk_edit_posts()`wp-admin/includes/post.php`	Processes the post data for the bulk editing of posts.
wp_get_post_cats()`wp-includes/deprecated.php`	Retrieves a list of post categories.
wp_xmlrpc_server::mt_getPostCategories()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves post categories.
wp_xmlrpc_server::mt_publishPost()`wp-includes/class-wp-xmlrpc-server.php`	Sets a post’s publish status to ‘publish’.
wp_xmlrpc_server::mw_getPost()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves a post.
wp_xmlrpc_server::mw_getRecentPosts()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves list of recent posts.
wp_xmlrpc_server::blogger_getPost()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves a post.
wp_xmlrpc_server::blogger_getRecentPosts()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves the list of recent posts.
wp_xmlrpc_server::_prepare_page()`wp-includes/class-wp-xmlrpc-server.php`	Prepares page data for return in an XML-RPC object.

Show 4 more Show less

Changelog

Version	Description
2.1.0	Introduced.

User Contributed Notes

Skip to note 4 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
The example below shows how categories are retrieved, and then additional information is retrieved for each category.
```
$post_categories = wp_get_post_categories( $post_id );
$cats = array();
	
foreach($post_categories as $c){
	$cat = get_category( $c );
	$cats[] = array( 'name' => $cat->name, 'slug' => $cat->slug );
}
```
- It is possible to retrieve all the additional information directly from the call to the function with the args parameter as described in the return description:
  
  $post_categories = wp_get_post_categories( $post_id, array ( ‘fields’ = > ‘all’ ) );
  
  paquinfrancis 6 years ago
- There is now a better way to retrieve more information. I’ll be adding example bellow
  
  Sabbir Hasan 5 years ago
Log in to add feedback

Skip to note 5 content

Sabbir Hasan

5 years ago

The example below shows how categories are retrieved, and using arguments additional info will be retrieved instead of calling get_category

$post_categories = wp_get_post_categories( $post_id, array( 'fields' => 'all' ) );
$cats = array();

if( $post_categories ){ // Always Check before loop!
	foreach($post_categories as $c){
		$cats[] = array( 'name' => $c->name, 'slug' => $c->slug );
		// Or we can just print it directly
		printf("Category Name: %s, Category Slug: %s, Category Url: %s <br/>", $c->name, $c->slug, esc_url( get_category_link( $c->term_id ) ) );
	}	
}

Only list Category names:

$post_categories = wp_get_post_categories( $post_id, array( 'fields' => 'names' ) );

if( $post_categories ){ // Always Check before loop!
	foreach($post_categories as $name){
		echo $name;
	}
}

Skip to note 6 content

Akramul Hasan

4 years ago

List category names in Descending order:

$terms_list = wp_get_post_categories( $post_id, array( 'fields'=>'names', 'order'=> 'DESC' ) );
if ( $terms_list ) { // Check $terms_list has value
	foreach ( $terms_list as $term ) {
		echo esc_html( $term ) . '<br />';
	}
}

If you want to exclude any specific term from the list you can do like:

// Add the 'exclude' key and put the term id you wanted to exclude from the result as key
// If you want to exclude multiple terms, then put their keys separated by a comma or space

$terms_list = wp_get_post_categories( $post_id, array( 'fields'=>'names', 'exclude'=> '1,7' ) );
if ( $terms_list ) { // Check $terms_list has value
	foreach ( $terms_list as $term ) {
		echo esc_html( $term ) . '<br />';
	}
}

云策 WordPress 开发者社区

函数文档