Как сделать пагинацию для WordPress на основе пользовательского запроса WP_Query

В WordPress часто возникает задача вывести список записей с пагинацией, используя кастомный запрос WP_Query. В этой статье разберём, как правильно реализовать пагинацию для пользовательских запросов, чтобы избежать типичных ошибок, улучшить производительность и обеспечить корректную работу навигации.

Основы пагинации в WP_Query: параметры и структура запроса

Для начала важно понимать, что пагинация в WordPress основывается на параметрах paged и posts_per_page в объекте WP_Query. Параметр paged отвечает за номер текущей страницы, а posts_per_page — за количество записей на странице.

Пример базового запроса с пагинацией:

$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
$args = [
    'post_type' => 'post',
    'posts_per_page' => 5,
    'paged' => $paged,
];
$query = new WP_Query($args);

Обратите внимание, что get_query_var('paged') возвращает текущий номер страницы из URL. Без правильной установки этого параметра пагинация работать не будет.

Важно, чтобы при использовании пользовательского запроса пагинация строилась не на глобальном объекте $wp_query, а на вашем экземпляре WP_Query.

Вывод ссылок пагинации: функции и кастомизация

Для вывода навигации по страницам можно использовать стандартную функцию WordPress paginate_links(). Она позволяет получить HTML с ссылками на страницы.

Пример вывода пагинации для нашего запроса:

if ($query->max_num_pages > 1) {
    echo paginate_links([
        'base' => get_pagenum_link(1) . '%_%',
        'format' => 'page/%#%/',
        'current' => max(1, $paged),
        'total' => $query->max_num_pages,
        'prev_text' => '« Назад',
        'next_text' => 'Вперед »',
    ]);
}

Параметр base формирует базовый URL с заменой для номера страницы, а format — шаблон для подстановки номера.

Если на вашем сайте используется постоянные ссылки (pretty permalinks), обязательно укажите правильный формат в format, например page/%#%/. Для обычных ссылок можно оставить 'format' => '?paged=%#%'.

Реализация через WP-PageNavi

Для более удобной и стильной пагинации можно использовать плагин WP-PageNavi. Он позволяет вывести номера страниц с красивым дизайном и дополнительными опциями.

Для вывода пагинации с WP-PageNavi для кастомного запроса достаточно вызвать:

if (function_exists('wp_pagenavi')) {
    wp_pagenavi(['query' => $query]);
}

Это автоматически сгенерирует навигацию, основанную на вашем объекте WP_Query.

Обработка пагинации с фильтрами и мета-записями

Если в запросе используются дополнительные параметры — фильтры по таксономиям, мета-полям, датам — пагинация всё равно должна учитывать общее количество записей, подходящих под условия.

Пример сложного запроса с мета-полями и пагинацией:

$args = [
    'post_type' => 'product',
    'posts_per_page' => 10,
    'paged' => $paged,
    'meta_query' => [
        [
            'key' => '_price',
            'value' => [100, 500],
            'type' => 'numeric',
            'compare' => 'BETWEEN',
        ],
    ],
    'tax_query' => [
        [
            'taxonomy' => 'product_cat',
            'field' => 'slug',
            'terms' => 'electronics',
        ],
    ],
];
$query = new WP_Query($args);

Такой запрос корректно посчитает количество страниц, и пагинация будет работать без дополнительной настройки.

Оптимизация запросов и кеширование

Для повышения производительности рекомендуем использовать кеширование результатов, например, с помощью Transients API:

function wppagenavi_get_cached_query($args, $cache_key) {
    $cached = get_transient($cache_key);
    if ($cached !== false) {
        return $cached;
    }
    $query = new WP_Query($args);
    set_transient($cache_key, $query, HOUR_IN_SECONDS);
    return $query;
}

$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
$args = [
    'post_type' => 'post',
    'posts_per_page' => 5,
    'paged' => $paged,
];
$cache_key = 'wppagenavi_query_page_' . $paged;
$query = wppagenavi_get_cached_query($args, $cache_key);

Это позволит уменьшить нагрузку на базу данных при повторных просмотрах страниц.

Типичные ошибки при реализации пагинации на пользовательских запросах

Ниже рассмотрим распространённые ошибки и способы их устранения.

Отсутствие параметра paged

Без передачи параметра paged в WP_Query пагинация не будет работать, так как запрос всегда будет возвращать первую страницу.

Использование глобального $wp_query вместо собственного запроса

Если вы создаёте отдельный WP_Query, в навигации нужно использовать именно этот объект, иначе пагинация может ссылаться на неправильные страницы.

Некорректный формат ссылки в функции paginate_links()

Ошибки в параметрах base и format приводят к неправильным URL пагинации и 404 ошибкам.

Вывод пагинации в шаблоне: пример полной реализации

Приведём готовый пример для вставки в файл шаблона:

$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
$args = [
    'post_type' => 'post',
    'posts_per_page' => 5,
    'paged' => $paged,
];
$query = new WP_Query($args);

if ($query->have_posts()) :
    while ($query->have_posts()) : $query->the_post();
        the_title('<h2>', '</h2>');
        the_excerpt();
    endwhile;

    echo paginate_links([
        'base' => str_replace(999999999, '%#%', esc_url(get_pagenum_link(999999999))),
        'format' => '?paged=%#%',
        'current' => max(1, $paged),
        'total' => $query->max_num_pages,
        'prev_text' => '« Назад',
        'next_text' => 'Вперед »',
    ]);

    wp_reset_postdata();
else :
    echo '<p>Записей не найдено.</p>';
endif;

Этот код корректно выведет записи и пагинацию, учитывая текущую страницу из URL.

Заключение

Пагинация для пользовательских запросов WP_Query — частая задача, требующая внимания к деталям. Правильное использование параметров paged, корректный вывод ссылок и оптимизация запросов обеспечивают удобную навигацию и хорошую производительность сайта.

Для расширенных возможностей и более удобного оформления рекомендуем использовать плагин WP-PageNavi.