is_singular()

💡 云策文档标注

概述

is_singular() 是一个 WordPress 条件标签函数，用于判断当前查询是否为任何文章类型的单个现有文章，包括文章、附件、页面和自定义文章类型。它基于全局 $wp_query 对象工作，并可接受 $post_types 参数来指定检查的文章类型。

关键要点

is_singular() 检查查询是否为单个现有文章，涵盖所有文章类型（如 post、attachment、page 和自定义文章类型）。
可选参数 $post_types 允许指定一个文章类型或数组，以进一步限制检查范围。
函数内部调用 WP_Query::is_singular()，如果 $wp_query 未设置，会触发 _doing_it_wrong() 并返回 false。
相关函数包括 is_page() 和 is_single()，用于更具体的查询检查。
在主题开发中常用于条件逻辑，例如显示不同的侧边栏广告或内容。

代码示例

// 检查是否为任何单个文章
if ( is_singular() ) {
    // 显示广告 #1
} else {
    // 显示广告 #2
}

// 检查是否为特定文章类型
if ( is_singular( 'post' ) ) {
    // 针对常规文章的代码
}

// 检查是否为多个自定义文章类型
if ( is_singular( array( 'newspaper', 'book' ) ) ) {
    // 针对报纸或书籍文章的代码
}

// 在钩子函数中使用
add_action( 'loop_start', 'your_function' );
function your_function() {
    if ( is_singular() ) {
        echo 'Hello World';
    }
}

注意事项

is_singular() 在查询运行前无效，会返回 false 并可能触发警告。
当使用静态页面作为首页时，is_singular() 和 is_page() 可能返回 true，但在博客页面返回 false。
确保在适当的钩子（如 loop_start）中使用，以避免条件标签过早执行。

📄 原文内容

Determines whether the query is for an existing single post of any post type (post, attachment, page, custom post types).

Description

If the $post_types parameter is specified, this function will additionally check if the query is for one of the Posts Types specified.

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 post types to check against. Default empty.

Return

bool Whether the query is for an existing single post or any of the given post types.

Source

function is_singular( $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_singular( $post_types );
}

View all references View on Trac View on GitHub

Uses	Description
WP_Query::is_singular()`wp-includes/class-wp-query.php`	Determines whether the query is for an existing single post of any post type (post, attachment, page, custom post types).
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
_doing_it_wrong()`wp-includes/functions.php`	Marks something as being incorrectly called.

Show 1 more Show less

Used by	Description
get_the_block_template_html()`wp-includes/block-template.php`	Returns the markup for the current template.
rest_get_queried_resource_route()`wp-includes/rest-api.php`	Gets the REST route for the currently queried object.
WP_Widget_Text::_filter_gallery_shortcode_attrs()`wp-includes/widgets/class-wp-widget-text.php`	Filters gallery shortcode attributes.
WP_Widget_Custom_HTML::_filter_gallery_shortcode_attrs()`wp-includes/widgets/class-wp-widget-custom-html.php`	Filters gallery shortcode attributes.
WP_Widget_Custom_HTML::widget()`wp-includes/widgets/class-wp-widget-custom-html.php`	Outputs the content for the current Custom HTML widget instance.
wp_oembed_add_discovery_links()`wp-includes/embed.php`	Adds oEmbed discovery links in the head element of the website.
wp_get_document_title()`wp-includes/general-template.php`	Returns document title for the current page.
feed_links_extra()`wp-includes/general-template.php`	Displays the links to the extra feeds such as category feeds.
WP::handle_404()`wp-includes/class-wp.php`	Set the Headers for 404, if nothing is found for requested URL.
WP::send_headers()`wp-includes/class-wp.php`	Sends additional HTTP headers for caching, content type, etc.
WP_Widget_Text::widget()`wp-includes/widgets/class-wp-widget-text.php`	Outputs the content for the current Text widget instance.
rel_canonical()`wp-includes/link-template.php`	Outputs rel=canonical for singular queries.
wp_get_shortlink()`wp-includes/link-template.php`	Returns a shortlink for a post, page, attachment, or site.
get_next_comments_link()`wp-includes/link-template.php`	Retrieves the link to the next comments page.
get_previous_comments_link()`wp-includes/link-template.php`	Retrieves the link to the previous comments page.
paginate_comments_links()`wp-includes/link-template.php`	Displays or retrieves pagination links for the comments on the current post.
get_posts_nav_link()`wp-includes/link-template.php`	Retrieves the post pages link navigation for previous and next pages.
is_page_template()`wp-includes/post-template.php`	Determines whether the current post uses a page template.
wp_list_pages()`wp-includes/post-template.php`	Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.
get_body_class()`wp-includes/post-template.php`	Retrieves an array of the class names for the body element.
redirect_canonical()`wp-includes/canonical.php`	Redirects incoming links to the proper URL based on the site url.

Show 16 more Show less

Changelog

Version	Description
1.5.0	Introduced.

User Contributed Notes

Skip to note 7 content

Codex

10 years ago

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
Default Post Type

True when viewing a regular post.
```
is_singular( 'post' );
```
Log in to add feedback
Skip to note 8 content

Codex

10 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
Custom Post Types

When any of the following return true: is_single() , is_page() or is_attachment() .
```
is_singular();
```
True when viewing a post of the Custom Post Type book.
```
is_singular( 'book' );
```
True when viewing a post of the Custom Post Type newspaper or book.
```
is_singular( array( 'newspaper', 'book' ) );
```
Log in to add feedback
Skip to note 9 content

Codex

10 years ago

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
Different Sidebar Ads in Singular Page
```
if ( is_singular() ) {
  // show adv. #1
} else {
  // show adv. #2
}
```
Log in to add feedback
Skip to note 10 content

Dave

6 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
To test for a single post:
```
if ( is_singular( 'post' ) ) {
    //your code here...
}
```
Log in to add feedback
Skip to note 11 content

Steven Lin

6 years ago

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
Usage With Hook in Custom Function

You can use the conditional tag in a custom function with a WordPress or theme specific hook in your functions file.
```
add_action( 'loop_start', 'your_function' );
function your_function() {
if ( is_singular() ) {
echo 'Hello World';
    }
}
```
Log in to add feedback
Skip to note 12 content

Feras Jobeir

5 years ago

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
In homepage:
```
is_singular()
```
and
```
is_page()
```
will return true if you are using a static page is a homepage (reading settings).
They will return false in blog page.
This is has been noticed in WP v5.7.2
Log in to add feedback

云策 WordPress 开发者社区

函数文档