Как добавить пагинацию в WP REST API

WP REST API — мощный инструмент для создания современных приложений на WordPress, но по умолчанию он возвращает все записи без удобной пагинации. Это может привести к большим нагрузкам и неудобствам при работе с большими объемами данных. В этой статье мы подробно разберем, как добавить пагинацию в WP REST API, сделать её настраиваемой и удобной для фронтенд-разработчиков.

Что такое пагинация в WP REST API и зачем она нужна

Пагинация — это способ разбить большой набор данных на страницы, чтобы возвращать только часть записей за один запрос. В WP REST API это особенно важно, потому что возвращать сразу все записи — плохая практика. Это замедляет работу сайта и усложняет обработку данных на клиенте.

WP REST API поддерживает базовую пагинацию через параметры page и per_page, но их поведение и возможности можно расширить. Давайте разберемся, как это сделать правильно.

Стандартная пагинация в WP REST API: параметры page и per_page

По умолчанию в запросах к REST API можно использовать два параметра:

• page — номер страницы, начиная с 1;
• per_page — количество элементов на страницу, максимум 100.

Пример запроса к REST API, который возвращает вторую страницу по 10 записей:

https://example.com/wp-json/wp/v2/posts?page=2&per_page=10

Однако, эти параметры не всегда покрывают все потребности. Например, может потребоваться более гибкая пагинация, или собственный формат ответа с данными о страницах. Для этого можно расширить REST API.

Расширение WP REST API для кастомной пагинации

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

Добавление дополнительных данных пагинации в ответ API

Мы создадим функцию wppagenavi_add_pagination_data, которая добавит в REST API данные о максимальном количестве страниц, общем количестве записей и текущей странице.

function wppagenavi_add_pagination_data( $response, $object, $request ) {
    $max_pages = (int) $response->get_headers()['X-WP-TotalPages'];
    $total = (int) $response->get_headers()['X-WP-Total'];
    $current_page = (int) $request->get_param('page') ?: 1;
    $response->data['pagination'] = [
        'max_pages' => $max_pages,
        'total' => $total,
        'current_page' => $current_page,
    ];
    return $response;
}
add_filter( 'rest_post_collection_response', 'wppagenavi_add_pagination_data', 10, 3 );

Этот код добавляет в JSON-ответ блок pagination с ключевой информацией. Теперь фронтенд сможет легко ориентироваться в страницах.

Настройка максимального количества записей на странице

По умолчанию максимальное значение per_page — 100. Если нужно увеличить или уменьшить это число, можно использовать фильтр rest_post_collection_params:

function wppagenavi_custom_per_page_limit( $params ) {
    $params['per_page']['maximum'] = 50; // например, максимум 50
    return $params;
}
add_filter( 'rest_post_collection_params', 'wppagenavi_custom_per_page_limit', 10, 1 );

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

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

Если у вас есть кастомные типы записей (Custom Post Types), их пагинацию можно также расширить. Рассмотрим пример для типа product.

function wppagenavi_register_custom_post_type() {
    register_post_type( 'product', [
        'public' => true,
        'show_in_rest' => true,
        'rest_base' => 'products',
        'supports' => [ 'title', 'editor', 'thumbnail' ],
    ] );
}
add_action( 'init', 'wppagenavi_register_custom_post_type' );

function wppagenavi_add_pagination_to_products( $response, $object, $request ) {
    $max_pages = (int) $response->get_headers()['X-WP-TotalPages'];
    $total = (int) $response->get_headers()['X-WP-Total'];
    $current_page = (int) $request->get_param('page') ?: 1;
    $response->data['pagination'] = [
        'max_pages' => $max_pages,
        'total' => $total,
        'current_page' => $current_page,
    ];
    return $response;
}
add_filter( 'rest_products_collection_response', 'wppagenavi_add_pagination_to_products', 10, 3 );

Теперь запрос https://example.com/wp-json/wp/v2/products?page=1&per_page=10 вернет продукты с дополнительными данными пагинации.

Использование плагинов для расширения пагинации WP REST API

Если не хочется писать код вручную, можно использовать готовые решения. Вот несколько популярных плагинов:

• WP REST API Controller — позволяет гибко настраивать эндпоинты и параметры, включая пагинацию.
• WP-API Pagination — расширяет стандартную пагинацию, добавляя больше информации в ответ.
• REST API Helper — набор инструментов для улучшения REST API, включая пагинацию и фильтры.

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

Советы по оптимизации пагинации в WP REST API

Правильная пагинация — залог производительности и удобства вашего приложения. Вот несколько рекомендаций:

• Используйте параметры page и per_page для разбивки данных.
• Добавляйте в ответ дополнительные метаданные о пагинации, чтобы фронтенд мог строить навигацию.
• Ограничивайте максимальное количество записей на страницу, чтобы избежать перегрузки сервера.
• Кэшируйте ответы REST API, если данные не меняются часто.
• Используйте фильтры и хуки для кастомизации пагинации под свои задачи.

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