WP_Query 完全指南
WP_Query 是 WordPress 最强大的查询类，用于获取文章、页面和自定义类型的内容。
📚 基本使用
简单查询
php
<?php
// 创建新查询
$query = new WP_Query(array(
'post_type' => 'post',
'posts_per_page' => 5,
'post_status' => 'publish',
));
// 循环
if ($query->have_posts()) :
while ($query->have_posts()) : $query->the_post();
// 输出文章标题
the_title('<h2>', '</h2>');
the_content();
endwhile;
wp_reset_postdata(); // 重置全局 $post
endif;1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
主循环 vs 次级循环
php
<?php
// 主循环（当前页面）
if (have_posts()) :
while (have_posts()) : the_post();
the_title();
endwhile;
endif;
// 次级循环（不同内容）
$my_query = new WP_Query(array(
'post_type' => 'portfolio',
'posts_per_page' => 3,
));
if ($my_query->have_posts()) :
while ($my_query->have_posts()) : $my_query->the_post();
the_title();
endwhile;
wp_reset_postdata(); // 重要！
endif;1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
📝 查询参数
文章类型和状态
php
<?php
// 单个文章类型
$query = new WP_Query(array(
'post_type' => 'post',
));
// 多个文章类型
$query = new WP_Query(array(
'post_type' => array('post', 'page', 'portfolio'),
));
// 特定文章
$query = new WP_Query(array(
'post_type' => 'any',
'post__in' => array(1, 2, 5),
));
// 排除文章
$query = new WP_Query(array(
'post__not_in' => array(1, 2),
));
// 文章状态
$query = new WP_Query(array(
'post_status' => 'publish',
));
// 或 'draft', 'pending', 'private', 'trash', 'any'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
文章数量和分页
php
<?php
// 获取所有文章
$query = new WP_Query(array(
'posts_per_page' => -1,
));
// 每页 10 篇
$query = new WP_Query(array(
'posts_per_page' => 10,
));
// 分页
$query = new WP_Query(array(
'posts_per_page' => 10,
'paged' => get_query_var('paged') ?: 1,
));
// 无分页
$query = new WP_Query(array(
'no_found_rows' => true,
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
排序和排序依据
php
<?php
// 按标题升序
$query = new WP_Query(array(
'orderby' => 'title',
'order' => 'ASC',
));
// 按发布日期降序
$query = new WP_Query(array(
'orderby' => 'date',
'order' => 'DESC',
));
// 按随机排序
$query = new WP_Query(array(
'orderby' => 'rand',
));
// 多字段排序
$query = new WP_Query(array(
'orderby' => array(
'title' => 'ASC',
'date' => 'DESC',
),
));
// 按评论数排序
$query = new WP_Query(array(
'orderby' => 'comment_count',
'order' => 'DESC',
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
分类和标签
php
<?php
// 特定分类
$query = new WP_Query(array(
'cat' => 5, // 分类 ID
));
// 多个分类
$query = new WP_Query(array(
'cat' => '5,6,7', // 包含任一
// 或
'category__and' => array(5, 6), // 同时包含
'category__in' => array(5, 6), // 排除子分类
));
// 按分类名称
$query = new WP_Query(array(
'category_name' => 'news',
));
// 按标签
$query = new WP_Query(array(
'tag' => 'featured',
'tag__in' => array(1, 2, 3),
'tag__and' => array(1, 2),
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
自定义分类法
php
<?php
// 自定义分类查询
$query = new WP_Query(array(
'tax_query' => array(
array(
'taxonomy' => 'genre',
'field' => 'slug',
'terms' => 'sci-fi',
),
),
));
// 多个分类
$query = new WP_Query(array(
'tax_query' => array(
'relation' => 'OR',
array(
'taxonomy' => 'genre',
'field' => 'slug',
'terms' => array('sci-fi', 'action'),
),
array(
'taxonomy' => 'actor',
'field' => 'name',
'terms' => 'John',
),
),
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
作者查询
php
<?php
// 特定作者
$query = new WP_Query(array(
'author' => 1, // 作者 ID
));
// 多个作者
$query = new WP_Query(array(
'author' => '1,2,3', // 或
'author__in' => array(1, 2),
'author__not_in' => array(3),
));
// 按作者名
$query = new WP_Query(array(
'author_name' => 'john',
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
日期查询
php
<?php
// 年份
$query = new WP_Query(array(
'year' => 2024,
));
// 月份
$query = new WP_Query(array(
'monthnum' => 4,
));
// 日期范围
$query = new WP_Query(array(
'date_query' => array(
'after' => '2024-01-01',
'before' => '2024-12-31',
),
));
// 最近 30 天
$query = new WP_Query(array(
'date_query' => array(
'after' => date('Y-m-d', strtotime('-30 days')),
),
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
搜索查询
php
<?php
$query = new WP_Query(array(
's' => 'search term',
));
// 高亮搜索词
add_filter('the_title', function($title) {
if (is_search() && !is_admin()) {
$search = get_query_var('s');
$title = preg_replace('/(' . $search . ')/i', '<strong>$1</strong>', $title);
}
return $title;
});1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
自定义字段
php
<?php
// 特定值
$query = new WP_Query(array(
'meta_query' => array(
array(
'key' => 'color',
'value' => 'blue',
),
),
));
// 多个字段
$query = new WP_Query(array(
'meta_query' => array(
'relation' => 'AND',
array(
'key' => 'color',
'value' => 'blue',
),
array(
'key' => 'price',
'value' => array(100, 500),
'compare' => 'BETWEEN',
'type' => 'NUMERIC',
),
),
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
📊 查询属性
WP_Query 对象属性
php
<?php
$query = new WP_Query($args);
// 文章总数
$query->found_posts;
// 最大页数
$query->max_num_pages;
// 当前页码
$query->get('paged');
// 文章 ID
global $post;
$post->ID;
// 是否是主查询
$query->is_main_query();1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
💡 实用查询示例
特色文章
php
<?php
$featured = new WP_Query(array(
'meta_query' => array(
array(
'key' => 'featured',
'value' => '1',
),
),
'posts_per_page' => 3,
));1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
相关文章
php
<?php
$current_post = get_queried_object_id();
$categories = get_the_category($current_post);
$related = new WP_Query(array(
'category__in' => wp_list_pluck($categories, 'term_id'),
'post__not_in' => array($current_post),
'posts_per_page' => 3,
));1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
作者文章统计
php
<?php
$author_posts = new WP_Query(array(
'author' => $author_id,
'posts_per_page' => -1,
'fields' => 'ids', // 仅获取 ID，更高效
));
$post_count = count($author_posts->posts);1
2
3
4
5
6
7
2
3
4
5
6
7
🛡️ 性能优化
优化查询
php
<?php
// 仅获取必要字段
$query = new WP_Query(array(
'fields' => 'ids', // 仅 ID
// 或
'fields' => 'id=>parent', // ID 和父级
));
// 禁用分页计数
$query = new WP_Query(array(
'no_found_rows' => true,
));
// 缓存结果
$query = new WP_Query(array(
'cache_results' => true,
));1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17