云策 WordPress 开发者社区

函数文档

in_category()

查看官方原文 ↗
💡 云策文档标注

概述

in_category() 函数用于检查当前文章是否属于指定的一个或多个分类。它支持通过分类 ID、名称或 slug 进行匹配，并可在 WordPress Loop 内外使用。

关键要点

  • 函数检查当前文章是否在给定的分类中，支持参数为整数、字符串或数组形式。
  • 从 WordPress 2.7 开始，增加了 $post 参数，允许指定文章 ID 或 WP_Post 对象，从而可在 Loop 外使用。
  • 函数内部调用 has_category() 实现，空分类参数返回 false。
  • 历史版本中，WordPress 2.5 前不支持分类名称，2.7 前不支持分类 slug 和多个分类比较，且仅限于 Loop 内使用。
  • 相关函数 has_category() 提供类似功能，位于 wp-includes/category-template.php。

代码示例

// 在 Loop 外检查文章分类以切换模板
if ( in_category('fruit') ) {
    include 'single-fruit.php';
} elseif ( in_category('vegetables') ) {
    include 'single-vegetables.php';
} else {
    // 正常 Loop 处理
    if ( have_posts() ) : while ( have_posts() ) : the_post();
    // ...
}

注意事项

  • 函数不直接支持检查父分类及其子分类，但可通过自定义函数如 wpdocs_post_is_in_a_subcategory() 实现。
  • 根据用户贡献笔记，in_category() 可能接受 WP_Term 对象作为 $category 参数，但官方文档未明确说明。
📄 原文内容

Checks if the current post is within any of the given categories.

Description

The given categories are checked against the post’s categories’ term_ids, names and slugs.
Categories given as integers will only be checked against the post’s categories’ term_ids.

Prior to v2.5 of WordPress, category names were not supported.
Prior to v2.7, category slugs were not supported.
Prior to v2.7, only one category could be compared: in_category( $single_category ).
Prior to v2.7, this function could only be used in the WordPress Loop.
As of 2.7, the function can be used anywhere if it is provided a post ID or post object.

For more information on this and similar theme functions, check out the Conditional Tags article in the Theme Developer Handbook.

Parameters

$categoryint|string|int[]|string[]required
Category ID, name, slug, or array of such to check against.
$postint|null|WP_Postoptional
Post to check. Defaults to the current post.

Default:null

Return

bool True if the current post is in any of the given categories.

Source

function in_category( $category, $post = null ) {
	if ( empty( $category ) ) {
		return false;
	}

	return has_category( $category, $post );
}

View all references View on Trac View on GitHub

Uses Description
has_category()wp-includes/category-template.php

Checks if the current post has any of given category.

Changelog

Version Description
2.7.0 The $post parameter was added.
1.2.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note

    Testing the current post outside the Loop
    During a request for an individual post (usually handled by the single.php template), you can test that post’s categories even before the Loop is begun.

    You could use this to switch templates like so:

    if ( in_category('fruit') ) {
	include 'single-fruit.php';
} elseif ( in_category('vegetables') ) {
	include 'single-vegetables.php';
} else {
	// Continue with normal Loop
	if ( have_posts() ) : while ( have_posts() ) : the_post();
	// ...
}

    (The Custom Post Templates Plugin allows for creation of templates for single posts. It also shows an example of how to add a template which is used for all posts in a given category, not just a single post. That example is commented out in the plugin by default but can be easily implemented by uncommenting the appropriate lines.)

  2. Skip to note 6 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    Testing the current post within the Loop
    in_category() is often used to take different actions within the Loop depending on the current post’s category, e.g.

    if ( in_category( 'pachyderms' )) {
	// They have long trunks...
} elseif ( in_category( array( 'Tropical Birds', 'small-mammals' ) )) {
	// They are warm-blooded...
} else {
	// etc.
}

  3. Skip to note 7 content


    revive


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    To check whether a post is within a parent category or any of it’s subcategories:

    https://codex.wordpress.org/Function_Reference/in_category#Testing_if_a_post_is_in_a_descendant_category</a>
 */

if ( ! function_exists( 'wpdocs_post_is_in_a_subcategory' ) ) {
function wpdocs_post_is_in_a_subcategory( $categories, $_post = null ) {
    foreach ( (array) $categories as $category ) {
        // get_term_children() only accepts integer ID
        $subcats = get_term_children( (int) $category, 'category' );
        if ( $subcats && in_category( $subcats, $_post ) )
            return true;
    }
    return false;
  }
}
?>

    Use for checking if within a single cat:

    wpdocs_post_is_in_a_subcategory( 25 );

    Use for checking if within an array of parent categories, or any of their subcats:

    wpdocs_post_is_in_a_subcategory( array( 25, 28, 124, 297, 298, 299 ) );