is_main_query()

💡 云策文档标注

概述

is_main_query() 是一个条件函数，用于判断当前查询（如在循环中）是否为 WordPress 的“主查询”，而非自定义或次要查询。它常用于钩子中区分主查询与自定义查询，并返回布尔值。

关键要点

is_main_query() 是一个无参数函数，通过比较 $wp_query 和 $wp_the_query 对象来确定当前查询是否为主查询。
在 'pre_get_posts' 等钩子回调中，应直接使用传递的 WP_Query 对象的 is_main_query() 方法，而非调用此函数，以避免循环调用。
函数适用于前端和后台查询，返回 true 表示当前查询是主查询，false 表示不是。

代码示例

add_action( 'pre_get_posts', 'foo_modify_query_exclude_category' );
function foo_modify_query_exclude_category( $query ) {
    if ( ! is_admin() && $query->is_main_query() && ! $query->get( 'cat' ) )
        $query->set( 'cat', '-5' );
}

注意事项

在 'pre_get_posts' 钩子中，使用 $query->is_main_query() 而非 is_main_query() 函数，以避免错误调用。
查询运行前调用此函数会返回 false，并可能触发 _doing_it_wrong() 警告。

📄 原文内容

Determines whether the query is the main query.

Description

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

Return

bool Whether the query is the main query.

More Information

The is_main_query() function is a conditional function that can be used to evaluate whether the current query (such as within the loop) is the “main” query (as opposed to a secondary query).

This function is most commonly used within hooks to distinguish WordPress’ main query (for a page, post, or archive) from a custom/secondary query.

is_main_query() may be used with both front-end queries (theme templates, plugins, etc.), as well as admin queries. It will return true if the current query is the main query, and false if not.

Usage

if ( is_main_query() ) {
// do stuff
}

Under the Hood

This function does not accept any parameters. Instead, it automatically compares the $wp_query object (i.e., the “current query”) with the $wp_the_query object (the “main query”)

This function is an alias for the method WP_Query::is_main_query(). In filter or action hook callbacks that are passed the WP_Query object, such as ‘pre_get_posts‘, it is circular to call this function. Instead, directly call the passed object’s method. For example, if your filter callback assigns the passed WP_Query object to $query, you would call the method like so:
$query->is_main_query()

Example

add_action( 'pre_get_posts', 'foo_modify_query_exclude_category' );
function foo_modify_query_exclude_category( $query ) {
if ( ! is_admin() && $query->is_main_query() && ! $query->get( 'cat' ) )
$query->set( 'cat', '-5' );
}

Source

function is_main_query() {
	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.' ), '6.1.0' );
		return false;
	}

	if ( 'pre_get_posts' === current_filter() ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: pre_get_posts, 2: WP_Query->is_main_query(), 3: is_main_query(), 4: Documentation URL. */
				__( 'In %1$s, use the %2$s method, not the %3$s function. See %4$s.' ),
				'<code>pre_get_posts</code>',
				'<code>WP_Query->is_main_query()</code>',
				'<code>is_main_query()</code>',
				__( 'https://developer.wordpress.org/reference/functions/is_main_query/' )
			),
			'3.7.0'
		);
	}

	return $wp_query->is_main_query();
}

View all references View on Trac View on GitHub

Uses	Description
WP_Query::is_main_query()`wp-includes/class-wp-query.php`	Determines whether the query is the main query.
current_filter()`wp-includes/plugin.php`	Retrieves the name of the current filter hook.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
_doing_it_wrong()`wp-includes/functions.php`	Marks something as being incorrectly called.

Show 2 more Show less

Used by	Description
wp_get_loading_optimization_attributes()`wp-includes/media.php`	Gets loading optimization attributes.
wp_get_loading_attr_default()`wp-includes/deprecated.php`	Gets the default value to use for a `loading` attribute on an element.

Changelog

Version	Description
3.3.0	Introduced.

User Contributed Notes

Skip to note 2 content

Codex

11 years ago

Example of using WP_Query->is_main_query() instead of is_main_query() (invalid)

/**
 * If the global query is for a category, exclude category 5.
 *
 * @param WP_Query $query Global WP_Query instance.
 */
function wpdocs_modify_query_exclude_category( $query ) {
    if ( ! is_admin() && $query->is_main_query() && ! $query->get( 'cat' ) )
        $query->set( 'cat', '-5' );
}
add_action( 'pre_get_posts', 'wpdocs_modify_query_exclude_category' );

云策 WordPress 开发者社区

函数文档