Как добавить пагинацию в WP_Query с уникальным отображением страниц

В стандартных сценариях WordPress пагинация выводится с помощью функции paginate_links() или плагинов вроде WP-PageNavi. Но зачастую возникает необходимость кастомизировать вывод пагинации именно для своих запросов WP_Query — с уникальным отображением номеров страниц, кастомным HTML и функционалом. В этой статье подробно разберём, как сделать пагинацию для пользовательских запросов WP_Query с уникальным внешним видом, сохранив все преимущества SEO и UX.

Особенности пагинации для WP_Query: базовая логика

Пагинация в WordPress строится на параметрах 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);

После вывода постов можно вызвать пагинацию так:

echo paginate_links([
    'total' => $query->max_num_pages,
    'current' => $paged,
]);

Но такой подход не всегда подходит, если нужна уникальная раскраска страниц, добавление иконок, нумерация с префиксом или иная кастомизация.

Создание уникального отображения страниц — настройка HTML и CSS пагинации

Чтобы сделать пагинацию уникальной, нам нужно:

• Сформировать массив ссылок с кастомным HTML
• Добавить классы для активной страницы и соседних страниц
• Вставить дополнительные элементы — например, иконки стрелок или анимацию

Пример функции, генерирующей кастомный HTML пагинации:

function wppagenavi_custom_pagination($query) {
    $paged = max(1, get_query_var('paged'));
    $max_pages = $query->max_num_pages;

    if ($max_pages <= 1) return; // Нет пагинации

    echo '<nav class="wppagenavi-pagination"><ul>';

    // Кнопка 'Предыдущая'
    if ($paged > 1) {
        echo '<li class="prev"><a href="' . get_pagenum_link($paged - 1) . '">« Назад</a></li>';
    } else {
        echo '<li class="prev disabled"><span>« Назад</span></li>';
    }

    // Основные ссылки с нумерацией
    for ($i = 1; $i <= $max_pages; $i++) {
        $class = $i === $paged ? 'active' : '';
        echo '<li class="page-number ' . $class . '"><a href="' . get_pagenum_link($i) . '">' . $i . '</a></li>';
    }

    // Кнопка 'Следующая'
    if ($paged < $max_pages) {
        echo '<li class="next"><a href="' . get_pagenum_link($paged + 1) . '">Вперёд »</a></li>';
    } else {
        echo '<li class="next disabled"><span>Вперёд »</span></li>';
    }

    echo '</ul></nav>';
}

Такой код даёт полный контроль над разметкой, позволяет применить свои стили и анимации. Пример базового CSS для стилизации пагинации:

.wppagenavi-pagination ul {
    list-style: none;
    display: flex;
    gap: 8px;
}
.wppagenavi-pagination .page-number a {
    padding: 6px 12px;
    border: 1px solid #ccc;
    color: #333;
    text-decoration: none;
}
.wppagenavi-pagination .active a {
    background-color: #0073aa;
    color: #fff;
    border-color: #0073aa;
}
.wppagenavi-pagination .disabled span {
    color: #999;
    cursor: not-allowed;
}

Пагинация с префиксом и дополнительной информацией

Иногда нужно, чтобы страницы отображались не просто цифрами, а с префиксом, например: "Страница 1 из 10" или "Шаг 1". Это можно реализовать, дополнив функцию:

function wppagenavi_prefixed_pagination($query) {
    $paged = max(1, get_query_var('paged'));
    $max_pages = $query->max_num_pages;

    if ($max_pages <= 1) return;

    echo '<nav class="wppagenavi-pagination"><ul>';

    for ($i = 1; $i <= $max_pages; $i++) {
        $class = $i === $paged ? 'active' : '';
        $text = 'Шаг ' . $i;
        echo '<li class="page-number ' . $class . '"><a href="' . get_pagenum_link($i) . '">' . $text . '</a></li>';
    }

    echo '</ul></nav>';
}

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

Пример интеграции с плагином WP-PageNavi и кастомным шаблоном

Плагин WP-PageNavi — популярный инструмент для пагинации. Его можно расширить, добавив свои стили и шаблоны. Для этого нужно:

1. В настройках плагина указать кастомный шаблон, например:

<div class="wppagenavi-custom">
<a href="%PAGE_LINK%" class="number">%PAGE_NUMBER%</a>
</div>

2. Использовать фильтр wp_pagenavi, чтобы добавить атрибуты и классы:

add_filter('wp_pagenavi', 'wppagenavi_modify_pagenavi_html');
function wppagenavi_modify_pagenavi_html($html) {
    // Пример добавления класса к ссылкам
    $html = str_replace('<a ', '<a class="wppagenavi-link" ', $html);
    return $html;
}

Так можно совместить удобство плагина и уникальный внешний вид пагинации.

Обработка пагинации в AJAX с уникальной навигацией

Если на сайте используется AJAX подгрузка постов (например, в блогах или каталогах), пагинация должна обновляться без перезагрузки страницы. Для этого создадим пример AJAX-обработчика, который возвращает кастомный HTML пагинации и посты:

add_action('wp_ajax_wppagenavi_ajax_pagination', 'wppagenavi_ajax_pagination_handler');
add_action('wp_ajax_nopriv_wppagenavi_ajax_pagination', 'wppagenavi_ajax_pagination_handler');

function wppagenavi_ajax_pagination_handler() {
    $paged = isset($_POST['paged']) ? intval($_POST['paged']) : 1;
    $args = [
        'post_type' => 'post',
        'posts_per_page' => 5,
        'paged' => $paged,
    ];
    $query = new WP_Query($args);

    ob_start();
    if ($query->have_posts()) {
        while ($query->have_posts()) {
            $query->the_post();
            echo '<h2>' . get_the_title() . '</h2>';
            echo '<div>' . get_the_excerpt() . '</div>';
        }
    } else {
        echo '<p>Посты не найдены</p>';
    }

    echo '<div class="wppagenavi-ajax-pagination">';
    wppagenavi_custom_pagination($query);
    echo '</div>';

    wp_reset_postdata();

    $content = ob_get_clean();

    wp_send_json_success(['content' => $content]);
}

// JS пример для вызова AJAX
// jQuery(document).on('click', '.wppagenavi-pagination a', function(e) {
//     e.preventDefault();
//     var page = new URL(this.href).searchParams.get('paged') || 1;
//     jQuery.post(ajaxurl, { action: 'wppagenavi_ajax_pagination', paged: page }, function(response) {
//         if (response.success) {
//             jQuery('#posts-container').html(response.data.content);
//         }
//     });
// });

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

Выводы и рекомендации

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

• Правильно передавайте параметр paged в запрос и используйте $query->max_num_pages.
• Создавайте функции с уникальным HTML, чтобы контролировать внешний вид навигации.
• Добавляйте префиксы и дополнительные элементы для лучшего UX.
• Используйте фильтры плагинов (например, WP-PageNavi) для интеграции кастомных стилей.
• Реализуйте AJAX пагинацию с обработкой и обновлением контента на лету.

Если хотите расширить функционал, обратите внимание на плагин ABC Pagination от WPSHOP. Он позволяет создавать гибкую и мощную пагинацию с минимальным кодом и максимальной кастомизацией.