云策 WordPress 开发者社区

钩子文档

post_limits

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

概述

post_limits 是一个 WordPress 过滤器，用于修改查询的 LIMIT 子句，控制返回结果的数量。它允许开发者在查询发送到数据库前动态调整限制条件。

关键要点

  • 过滤器应用于 WP_Query 查询的 LIMIT 子句，参数包括 $limits（字符串）和 $query（WP_Query 实例引用）。
  • 可以返回 null 以移除 LIMIT 子句，但会导致 $wp_query->found_posts 设置为 0。
  • 在某些服务器环境中，LIMIT 可能影响页面上的所有查询（如菜单和部件），建议使用 pre_get_posts 动作钩子来仅限制页面文章数量。
  • 该过滤器自 WordPress 2.1.0 版本引入，常用于自定义查询结果限制。

代码示例

/**
 * Limit the main query search results to 25.
 *
 * We only want to filter the limit on the front end of the site, so we use
 * is_admin() to check that we aren't on the admin side.
 *
 * We also only want to filter the main query, so we check that this query is
 * the main query with $this->is_main_query().
 *
 * Finally, we only want to change the limit for searches, so we check that
 * this query is a search with $this->is_search().
 *
 * @see https://developer.wordpress.org/reference/hooks/post_limits/
 * 
 * @param string $limit The 'LIMIT' clause for the query.
 * @param object $this The current query object.
 *
 * @return string The filtered LIMIT.
 */
function wpcodex_filter_main_search_post_limits( $limit, $this ) {

	if ( ! is_admin() && $this->is_main_query() && $this->is_search() ) {
		return 'LIMIT 0, 25';
	}

	return $limit;
}
add_filter( 'post_limits', 'wpcodex_filter_main_search_post_limits', 10, 2 );

注意事项

  • 使用此过滤器时需注意服务器环境差异，避免意外限制其他查询组件。
  • 移除 LIMIT 子句可能影响分页和结果计数功能。
📄 原文内容

Filters the LIMIT clause of the query.

Parameters

$limitsstring
The LIMIT clause of the query.
$queryWP_Query
The WP_Query instance (passed by reference).

More Information

  • This filter applies to the LIMIT clause of the query before the query is sent to the database, allowing you to define a new query LIMIT.
  • You can return null to remove the LIMIT clause from the query, allowing you to return all results. However, this will set $wp_query->found_posts to 0.
  • On some server environments, the LIMIT will be applied to all queries on the page. This results in menu items and widgets also being limited to the defined number. To only limit the number of posts on a page use the action hook pre_get_posts.

Source

$limits = apply_filters_ref_array( 'post_limits', array( $limits, &$this ) );

View all references View on Trac View on GitHub

Used by Description
WP_Query::get_posts()wp-includes/class-wp-query.php

Retrieves an array of posts based on query variables.

Changelog

Version Description
2.1.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Steven Lin


    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

    Example migrated from Codex:

    The example below allows your query to return 25 results only for the search page. All other queries will continue to return the default value.

    /**
 * Limit the main query search results to 25.
 *
 * We only want to filter the limit on the front end of the site, so we use
 * is_admin() to check that we aren't on the admin side.
 *
 * We also only want to filter the main query, so we check that this query is
 * the main query with $this->is_main_query().
 *
 * Finally, we only want to change the limit for searches, so we check that
 * this query is a search with $this->is_search().
 *
 * @see <a href="https://developer.wordpress.org/reference/hooks/post_limits/" rel="ugc">https://developer.wordpress.org/reference/hooks/post_limits/</a>
 * 
 * @param string $limit The 'LIMIT' clause for the query.
 * @param object $this The current query object.
 *
 * @return string The filtered LIMIT.
 */
function wpcodex_filter_main_search_post_limits( $limit, $this ) {

	if ( ! is_admin() && $this->is_main_query() && $this->is_search() ) {
		return 'LIMIT 0, 25';
	}

	return $limit;
}
add_filter( 'post_limits', 'wpcodex_filter_main_search_post_limits', 10, 2 );