云策 WordPress 开发者社区

函数文档

is_post_type_archive()

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

概述

is_post_type_archive() 是一个 WordPress 条件标签函数，用于判断当前查询是否为现有文章类型归档页面。它基于全局 $wp_query 对象，在查询运行后使用，否则返回 false。

关键要点

  • 函数检查查询是否针对现有文章类型归档页面，返回布尔值。
  • 接受可选参数 $post_types，可以是字符串或数组，用于指定要检查的文章类型，默认为空。
  • 在查询运行前调用会触发 _doing_it_wrong() 警告并返回 false。
  • 常用于主题开发中，结合其他函数如 get_the_archive_title() 或 wp_enqueue_scripts() 实现条件逻辑。

代码示例

// 检查当前页面是否为自定义文章类型 'snippets' 的归档页面
if ( is_post_type_archive( 'snippets' ) ) {
    // 执行相关操作，如加载样式或脚本
    wp_enqueue_style( 'custom-style', get_stylesheet_uri() );
    wp_enqueue_script( 'custom-script', get_template_directory_uri() . '/js/script.js', array(), '1.0.0', true );
}

注意事项

  • 仅适用于文章类型归档页面（如 /?post_type=my-custom-post-type），不适用于带分类或其他参数的查询（如 /category/uncategorized/?post_type=custom）。
  • 要检查 post_type 查询参数是否存在，应使用 get_query_var('post_type')。
  • 在导航菜单等上下文中使用时需注意时机，建议在 pre_get_posts 钩子中处理以避免问题。
📄 原文内容

Determines whether the query is for an existing post type archive page.

Description

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

Parameters

$post_typesstring|string[]optional
Post type or array of posts types to check against. Default empty.

Return

bool Whether the query is for an existing post type archive page.

Source

function is_post_type_archive( $post_types = '' ) {
	global $wp_query;

	if ( ! isset( $wp_query ) ) {
		_doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
		return false;
	}

	return $wp_query->is_post_type_archive( $post_types );
}

View all references View on Trac View on GitHub

Uses Description
WP_Query::is_post_type_archive()wp-includes/class-wp-query.php

Determines whether the query is for an existing post type archive page.
__()wp-includes/l10n.php

Retrieves the translation of $text.
_doing_it_wrong()wp-includes/functions.php

Marks something as being incorrectly called.

Show 1 moreShow less

Used by Description
wp_get_document_title()wp-includes/general-template.php

Returns document title for the current page.
get_the_archive_description()wp-includes/general-template.php

Retrieves the description for an author, post type, or term archive.
get_the_archive_title()wp-includes/general-template.php

Retrieves the archive title based on the queried object.
feed_links_extra()wp-includes/general-template.php

Displays the links to the extra feeds such as category feeds.
wp_title()wp-includes/general-template.php

Displays or retrieves page title for all areas of blog.
post_type_archive_title()wp-includes/general-template.php

Displays or retrieves title for a post type archive.
WP::handle_404()wp-includes/class-wp.php

Set the Headers for 404, if nothing is found for requested URL.
_wp_menu_item_classes_by_context()wp-includes/nav-menu-template.php

Adds the class property classes for the current context, if applicable.
get_body_class()wp-includes/post-template.php

Retrieves an array of the class names for the body element.

Show 4 moreShow less

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Codex


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

    Example
    If the current page is an archive of a custom post type, display the custom post type title:

    
<h1></h1>

    Notes
    This returns true for a page like /?post_type=my-custom-post-type, but not for /category/uncategorized/?post_type=custom. It’s only testing whether this is an archive of all posts of a given type. It is not checking for the existence of the post_type query parameter — that can be found by get_query_var('post_type').

    Also, depending on when this function runs it may or may not be run by nav_menu_item. For example:

    Whether “Do stuff” gets run in the menu depends on whether the theme use nav menus. A better usage would be:

    query['post_type'] ) {
         // Do stuff
    }
}
add_action( 'pre_get_posts', 'wpdocs_my_function' );
?>

  2. Skip to note 5 content


    Muhammad Ayoub


    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

    Conditionally enqueue (add) styles/scripts with custom post type archive page 

    add_action( 'wp_enqueue_scripts', function() {
    // check if this is snippets archive page
    if ( is_post_type_archive( 'snippets' ) ) {
        wp_enqueue_style( 'wpdocs-style-name', get_stylesheet_uri() );
        wp_enqueue_script( 'wpdocs-script-name', get_template_directory_uri() . '/js/example.js', array(), '1.0.0', true );
    }
} );