Как использовать хуки пагинации в WordPress: практические примеры и советы

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

Что такое хуки пагинации в WordPress и зачем они нужны

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

• Добавлять дополнительные элементы перед или после пагинации;
• Изменять HTML-разметку навигации;
• Подключать собственные стили и скрипты;
• Обрабатывать запросы на AJAX-обновление страниц.

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

Основные хуки пагинации WordPress

Ниже рассмотрим ключевые хуки, которые встречаются в функциях стандартной пагинации WordPress, например, paginate_links() и the_posts_pagination():

• pre_get_posts — позволяет изменить параметры основного запроса, например, количество постов на страницу;
• paginate_links_output (неофициальный, через фильтр paginate_links) — фильтр для изменения HTML пагинации;
• get_the_posts_pagination — фильтр для изменения разметки, возвращаемой the_posts_pagination();
• wp_link_pages_args — фильтр для настройки пагинации внутри одного поста (страницы разбиения контента).

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

Пример 1: Кастомизация HTML пагинации через фильтр wppagenavi_filter_paginate_links

Для примера создадим фильтр, который изменит стандартный HTML пагинации, добавив свои CSS-классы и обернув ссылки в дополнительные теги. Это поможет лучше стилизовать навигацию.

function wppagenavi_filter_paginate_links( $link ) {
    $link = str_replace('<a ', '<a class="wppagenavi-link" ', $link);
    $link = '<span class="wppagenavi-wrapper">' . $link . '</span>';
    return $link;
}
add_filter('paginate_links', 'wppagenavi_filter_paginate_links');

Этот код добавит класс wppagenavi-link ко всем ссылкам пагинации и обернёт их в <span> с классом wppagenavi-wrapper. Теперь вы можете применять свои стили через CSS.

Пример 2: Изменение количества постов на страницу через хук wppagenavi_pre_get_posts

Иногда нужно динамически менять количество постов, отображаемых на странице пагинации. Для этого воспользуемся фильтром pre_get_posts:

function wppagenavi_pre_get_posts( $query ) {
    if ( !is_admin() && $query->is_main_query() && $query->is_paged() ) {
        $query->set( 'posts_per_page', 5 );
    }
}
add_action('pre_get_posts', 'wppagenavi_pre_get_posts');

Данный код установит количество постов на страницу равным 5 для всех архивов и главной страницы с пагинацией. Такой подход полезен, если стандартное значение не подходит для вашего дизайна.

Пример 3: Добавление AJAX пагинации с использованием хуков и скриптов

Для улучшения UX можно реализовать пагинацию без перезагрузки страницы, используя AJAX и хуки WordPress. Рассмотрим минимальный пример:

Шаг 1: Подключение скрипта AJAX

function wppagenavi_enqueue_scripts() {
    wp_enqueue_script('wppagenavi-ajax', get_template_directory_uri() . '/js/wppagenavi-ajax.js', array('jquery'), null, true);
    wp_localize_script('wppagenavi-ajax', 'wppagenavi_ajax', array(
        'ajax_url' => admin_url('admin-ajax.php'),
        'nonce' => wp_create_nonce('wppagenavi_nonce'),
    ));
}
add_action('wp_enqueue_scripts', 'wppagenavi_enqueue_scripts');

Шаг 2: Обработка AJAX запроса в PHP

function wppagenavi_load_posts_ajax() {
    check_ajax_referer('wppagenavi_nonce', 'nonce');

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

    if ($query->have_posts()) {
        ob_start();
        while ($query->have_posts()) {
            $query->the_post();
            get_template_part('template-parts/content', get_post_format());
        }
        wp_send_json_success(ob_get_clean());
    } else {
        wp_send_json_error('Нет записей');
    }

    wp_die();
}
add_action('wp_ajax_wppagenavi_load_posts', 'wppagenavi_load_posts_ajax');
add_action('wp_ajax_nopriv_wppagenavi_load_posts', 'wppagenavi_load_posts_ajax');

Шаг 3: JavaScript для отправки запроса и обновления контента

jQuery(document).ready(function($) {
    $(document).on('click', '.pagination a', function(e) {
        e.preventDefault();
        var page = $(this).attr('href').split('paged=')[1];

        $.ajax({
            url: wppagenavi_ajax.ajax_url,
            type: 'POST',
            data: {
                action: 'wppagenavi_load_posts',
                nonce: wppagenavi_ajax.nonce,
                paged: page
            },
            success: function(response) {
                if (response.success) {
                    $('.posts-container').html(response.data);
                } else {
                    alert('Ошибка загрузки постов');
                }
            }
        });
    });
});

Данный пример показывает, как через хуки и AJAX реализовать подгрузку постов на страницах с пагинацией без перезагрузки. Вам потребуется адаптировать селекторы под вашу тему.

Советы по работе с хуками пагинации

При использовании хуков пагинации важно помнить:

• Всегда проверяйте контекст выполнения хука, чтобы не повлиять на админ-панель или ненужные запросы;
• Используйте wp_localize_script() для безопасной передачи данных в JavaScript;
• Для сложной логики лучше создавать отдельные функции с префиксом wppagenavi_, чтобы избежать конфликтов с другими плагинами;
• Тестируйте пагинацию на разных типах архивов и страницах, чтобы убедиться в корректной работе;
• Используйте кеширование, если пагинация требует тяжелых запросов.

Дополнительные плагины для расширения пагинации

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

• WP-PageNavi — классический плагин с множеством настроек и хуков;
• Pagination by BestWebSoft — простой и легкий, хорошо подходит для новичков;
• Ajax Pagination and Infinite Scroll — для реализации пагинации с AJAX;
• Custom Pagination — позволяет создавать уникальный дизайн навигации.

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

Итоги

Использование хуков пагинации в WordPress — мощный инструмент, открывающий широкие возможности по кастомизации и улучшению навигации. С помощью фильтров и экшенов можно изменить внешний вид, поведение и даже реализовать AJAX-загрузку страниц без перезагрузки. Главное — внимательно изучить документацию функций пагинации и тестировать изменения в разных условиях. Приведённые примеры помогут вам быстро начать работать с хуками и создавать уникальные решения для вашего сайта.