

wordpress主查询中$wp_query实例详解

wordpress知识

2025-12-01

$wp_query的本质

$wp_query是WordPress自动创建的全局WP_Query实例，在页面加载初期被初始化，负责执行当前页面的数据库查询，存储查询细节，并通过其属性和方法向开发者提供访问接口。

可通过全局变量调用：

global $wp_query;

$wp_query的核心属性与方法

查询参数与状态属性

$query_vars：关联数组，包含所有查询参数（如post_type、category_name等）。

// 获取当前查询的文章类型，可能返回 'post'、'page' 或自定义类型
$post_type = $wp_query->query_vars['post_type'];

$query：以字符串形式表示的原始查询参数（如p=123或category_name=news），较少直接使用。

is_single、is_page、is_category、is_home、is_search：布尔型属性，用于判断当前页面类型。

if ($wp_query->is_category){
  echo '当前是分类页';
}

文章数据属性

$posts：数组，存储查询返回的所有文章对象。

// 获取第一篇文章的标题
if (!empty($wp_query->posts[0])){
  echo $wp_query->posts[0]->post_title;
}

$post：当前循环中正在处理的文章对象，由the_post()方法更新，与全局$post变量同步。

$found_posts：符合条件的总文章数，不受分页限制，用于分页计算。

$max_num_pages：根据found_posts与每页数量计算得出的总页数。

$current_post：当前遍历的文章索引，配合have_posts()使用。

$post_count：当前页实际返回的文章数量，受posts_per_page限制。

常用控制方法

have_posts()：判断是否还有未处理的文章。

the_post()：将查询指针移至下一篇文章，更新$wp_query->post与全局$post，并触发the_post钩子。

while ($wp_query->have_posts()){
  $wp_query->the_post(); // 移动到下一篇文章
  // 输出文章内容（如 the_title()、the_content()）
}

rewind_posts()：重置查询指针，使循环可从头开始，适用于多次遍历场景。

// 第一次循环
while ($wp_query->have_posts()){
  $wp_query->the_post();
  the_title();
}
// 重置指针，准备第二次循环
$wp_query->rewind_posts();
// 第二次循环
while ($wp_query->have_posts()) {
  $wp_query->the_post();
  the_excerpt();
}

查询主体与参数操作

get_queried_object()：返回当前查询的主体对象，根据页面类型返回WP_Post、WP_Term或WP_User等实例。

$category = $wp_query->get_queried_object();
echo '当前分类：' . $category->name;

set($key, $value)：动态设置查询参数，常用于pre_get_posts钩子中调整主查询。

get($key)：获取指定查询参数值。

function custom_posts_per_page($query){
  if ($query->is_main_query() && $query->is_archive()){
    $query->set('posts_per_page', 10); // 分类/归档页每页显示 10 篇
  }
}
add_action('pre_get_posts', 'custom_posts_per_page');