База данных · Постраничная навигация

Введение

В других фреймворках постраничная навигация может быть очень болезненной. Мы надеемся, что подход Laravel к разбиению на страницы станет глотком свежего воздуха. Пагинатор Laravel интегрирован с построителем запросов и Eloquent ORM и обеспечивает удобную, простую в использовании разбивку на страницы записей базы данных с нулевой конфигурацией.

По умолчанию HTML, генерируемый пагинатором, совместим с фреймворком Tailwind CSS; однако, также доступна поддержка разбивки на страницы с использованием Bootstrap.

Tailwind JIT

Если вы используете стандартные представления Laravel для разбивки на страницы Tailwind и механизм JIT Tailwind, вы должны убедиться, что ключ content файла tailwind.config.js вашего приложения ссылаются на представления разбиения на страницы Laravel, чтобы их классы Tailwind не удалялись:

content: [
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue',
    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
],

Основы использования

Разбиение результатов построителя запросов

Есть несколько способов разбить элементы на страницы. Самый простой – использовать метод paginate построителя запросов или в запросе Eloquent. Метод paginate автоматически устанавливает «предел» и «смещение» в запросе на основе текущей страницы, просматриваемой пользователем. По умолчанию текущая страница определяется значением аргумента page строки HTTP-запроса. Это значение автоматически определяется Laravel, а также автоматически вставляется в ссылки, генерируемые пагинатором.

В этом примере единственный аргумент, переданный методу paginate – это количество элементов, которые вы хотите отображать «на каждой странице». В этом случае давайте укажем, что мы хотели бы отображать 15 элементов на странице:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\DB;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Показать всех пользователей приложения.
     */
    public function index(): View
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

Простая пагинация

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

Следовательно, если вам нужно отображать только простые ссылки «Далее» и «Назад» в пользовательском интерфейсе вашего приложения, вы можете использовать метод simplePaginate для выполнения одного рационального запроса:

$users = DB::table('users')->simplePaginate(15);

Разбиение результатов Eloquent

Вы также можете разбивать запросы Eloquent на страницы. В этом примере мы разобьем модель App\Models\User на страницы и укажем, что мы планируем отображать 15 записей на странице. Как видите, синтаксис почти идентичен разбивке на страницы результатов построителя запросов:

use App\Models\User;

$users = User::paginate(15);

Конечно, вы можете вызвать метод paginate после указания других ограничений для запроса, таких как выражения where:

$users = User::where('votes', '>', 100)->paginate(15);

Вы также можете использовать метод simplePaginate при разбиении на страницы моделей Eloquent:

$users = User::where('votes', '>', 100)->simplePaginate(15);

Точно так же вы можете использовать метод cursorPaginate для курсорной пагинации моделей Eloquent:

$users = User::where('votes', '>', 100)->cursorPaginate(15);

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

Иногда вам может потребоваться отобразить два отдельных модуля пагинации на одном экране, который отображается вашим приложением. Однако, если оба экземпляра пагинации используют параметр строки запроса page для хранения текущей страницы, они будут конфликтовать. Чтобы разрешить этот конфликт, вы можете передать имя параметра строки запроса, который вы хотите использовать для хранения текущей страницы, через третий аргумент, предоставленный методам paginate, simplePaginate и cursorPaginate:

use App\Models\User;

$users = User::where('votes', '>', 100)->paginate(
    $perPage = 15, $columns = ['*'], $pageName = 'users'
);

Cursor-пагинация

В то время как paginate и simplePaginate создают запросы с использованием SQL-оператора “offset”, Cursor-пагинация работает путем создания конструкции “where”, которая сравнивает значения упорядоченных столбцов, содержащихся в запросе, обеспечивая наиболее эффективную производительность базы данных среди всех возможных, доступную среди всех методов пагинации Laravel. Этот метод пагинации особенно хорошо подходит для больших наборов данных и пользовательских интерфейсов с “бесконечной” прокруткой.

В отличие от пагинации на основе смещения, которая включает номер страницы в строке запроса URL-адресов, сгенерированных средством постраничной навигации, Cursor-пагинация помещает «cursor» в строку запроса. Курсор представляет собой закодированную строку, содержащую место, с которого следующий запрос с пагинацией должен начать постраничную навигацию, и направление, в котором он должен разбиваться на страницы:

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

Вы можете создать экземпляр Cursor-пагинации с помощью метода cursorPaginate, предлагаемого построителем запросов. Этот метод возвращает экземпляр Illuminate\Pagination\CursorPaginator:

$users = DB::table('users')->orderBy('id')->cursorPaginate(15);

После того как вы получили экземпляр Cursor-пагинации, вы можете отобразить результаты постраничной навигации как обычно при использовании методов paginate и simplePaginate. Для получения дополнительной информации о методах экземпляра, предлагаемых средством Cursor-пагинации, обратитесь к документации по методам экземпляра Cursor Paginator.

Ваш запрос должен содержать “order by”, чтобы использовать Cursor-пагинацию. Кроме того, столбцы, по которым осуществляется сортировка запроса, должны принадлежать таблице, для которой вы используете пагинацию.

"Cursor" против "Offset" пагинации

Чтобы проиллюстрировать различия между “Cursor” и “Offset” постраничной навигацией, давайте рассмотрим несколько примеров SQL-запросов. Оба следующих запроса будут отображать “вторую страницу” результатов для таблицы users, упорядоченных по id:

# Offset пагинация...
select * from users order by id asc limit 15 offset 15;

# Cursor пагинация...
select * from users where id > 15 order by id asc limit 15;

Cursor-пагинация предлагает следующие преимущества перед Offset-пагинацией:

• Для больших наборов данных Cursor-пагинация обеспечивать лучшую производительность, если столбцы “order by” проиндексированы. Это связано с тем, что предложение “offset” сканирует все ранее сопоставленные данные.
• Для наборов данных с частыми записями Offset-пагинация может пропускать записи или отображать дубликаты, если результаты были недавно добавлены или удалены со страницы, которую пользователь просматривает в данный момент.

Однако, Cursor-пагинация имеет следующие ограничения:

• Как и simplePaginate, Cursor-пагинация может использоваться только для отображения ссылок “Далее” и “Назад” и не поддерживает создание ссылок с номерами страниц.
• Требуется, чтобы порядок был основан как минимум на одном уникальном столбце или на комбинации уникальных столбцов. Столбцы с null – значениями не поддерживаются.
• Выражения запросов c “order by” поддерживаются только в том случае, если они имеют псевдоним и также добавлены в “select”.
• Выражения запросов с параметрами не поддерживаются.

Самостоятельное создание пагинатора

По желанию можно вручную создать экземпляр пагинатора, передав ему массив элементов, которые у вас уже есть в памяти. Вы можете сделать это, создав экземпляр Illuminate\Pagination\Paginator, Illuminate\Pagination\LengthAwarePaginator или Illuminate\Pagination\CursorPaginator, в зависимости от ваших потребностей.

Классам Paginator и CursorPaginator не требуется знать общее количество элементов в результирующем наборе; однако, из-за этого у классов нет методов для получения индекса последней страницы. Класс LengthAwarePaginator принимает почти те же аргументы, что и Paginator; однако, для этого требуется подсчет общего количества элементов в результирующем наборе.

Другими словами, Paginator соответствует методу simplePaginate построителя запросов, CursorPaginator соответствует методу cursorPaginate, а LengthAwarePaginator соответствует методу paginate.

При ручном создании экземпляра пагинатора вы должны самостоятельно «разрезать» массив результатов, который вы передаете в пагинатор. Если вы не знаете, как это сделать, ознакомьтесь с функцией PHP array_slice.

Настройка URL-адресов постраничной навигации

По умолчанию ссылки, созданные пагинатором, будут соответствовать URI текущего запроса. Однако метод withPath пагинатора позволяет вам скорректировать URI, используемый пагинатором при генерации ссылок. Например, если вы хотите, чтобы пагинатор генерировал ссылки типа http://example.com/admin/users?page=N, вы должны передать /admin/users withPath:

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->withPath('/admin/users');

    // ...
});

Добавление значений в строку запроса

Вы можете добавить параметр в строку запроса навигационных ссылок с помощью метода appends. Например, чтобы добавить sort=votes к каждой ссылке пагинации, вы должны сделать следующий вызов appends:

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->appends(['sort' => 'votes']);

    // ...
});

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

$users = User::paginate(15)->withQueryString();

Добавление фрагментов хеша

Если вам нужно добавить «хеш-фрагмент» к URL-адресам, сгенерированным пагинатором, вы можете использовать метод fragment. Например, чтобы добавить #users в конец каждой навигационной ссылки, вы должны вызвать метод fragment следующим образом:

$users = User::paginate(15)->fragment('users');

Отображение результатов постраничной навигации

При вызове метода paginate вы получите экземпляр Illuminate\Pagination\LengthAwarePaginator, вызов метода simplePaginate возвращает экземпляр Illuminate\Pagination\Paginator. И, наконец, вызов метода cursorPaginate возвращает экземпляр Illuminate\Pagination\CursorPaginator.

Эти объекты содержат несколько методов, описывающих результирующий набор. В дополнение к этим вспомогательным методам, экземпляры пагинатора являются итераторами и могут быть перебраны как массив. Итак, как только вы получили результаты, вы можете отобразить результаты и отрисовать ссылки на страницы, используя Blade:

<div class="container">
    @foreach ($users as $user)
        {{ $user->name }}
    @endforeach
</div>

{{ $users->links() }}

Метод links отрисует ссылки на остальные страницы в результирующем наборе. Каждая из этих ссылок уже будет содержать соответствующую строковую переменную запроса page. Помните, что HTML, сгенерированный методом links, совместим с фреймворком Tailwind CSS.

Регулирование количества отображаемых ссылок

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

{{ $users->onEachSide(5)->links() }}

Преобразование результатов в JSON

Классы пагинатора Laravel реализуют контракт интерфейса Illuminate\Contracts\Support\Jsonable и содержат метод toJson, поэтому очень легко преобразовать результаты в JSON. Вы также можете преобразовать экземпляр пагинатора в JSON, вернув его из маршрута или действия контроллера:

use App\Models\User;

Route::get('/users', function () {
    return User::paginate();
});

JSON из пагинатора будет включать метаинформацию, такую как total, current_page, last_page и другие. Записи результатов доступны через ключ data в массиве JSON. Вот пример JSON, созданного путем возврата экземпляра пагинатора из маршрута:

{
   "total": 50,
   "per_page": 15,
   "current_page": 1,
   "last_page": 4,
   "first_page_url": "http://laravel.app?page=1",
   "last_page_url": "http://laravel.app?page=4",
   "next_page_url": "http://laravel.app?page=2",
   "prev_page_url": null,
   "path": "http://laravel.app",
   "from": 1,
   "to": 15,
   "data":[
        {
            // Запись ...
        },
        {
            // Запись ...
        }
   ]
}

Настройка вида пагинации

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

{{ $paginator->links('view.name') }}

// Передача дополнительных данных в шаблон ...
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

Однако, самый простой способ отредактировать шаблоны постраничной навигации – это экспортировать их в каталог resources/views/vendor с помощью команды vendor:publish:

php artisan vendor:publish --tag=laravel-pagination

Эта команда поместит шаблоны в каталог resources/views/vendor/pagination вашего приложения. Файл tailwind.blade.php в этом каталоге соответствует шаблону постраничной навигации по умолчанию. Вы можете отредактировать этот файл для изменения HTML-кода навигации.

Если вы хотите назначить другой файл в качестве шаблона постраничной навигации по умолчанию, вы можете вызвать методы defaultView и defaultSimpleView пагинатора в методе boot вашего класса App\Providers\AppServiceProvider:

<?php

namespace App\Providers;

use Illuminate\Pagination\Paginator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Загрузка любых служб приложения.
     */
    public function boot(): void
    {
        Paginator::defaultView('view-name');

        Paginator::defaultSimpleView('view-name');
    }
}

Использование Bootstrap

Laravel содержит шаблоны постраничной навигации, созданные с использованием Bootstrap CSS. Чтобы использовать эти шаблоны вместо шаблонов Tailwind по умолчанию, вы можете вызвать метод пагинатора useBootstrapFour или useBootstrapFive в методе boot класса App\Providers\AppServiceProvider:

use Illuminate\Pagination\Paginator;

/**
 * Загрузка любых служб приложения.
 */
public function boot(): void
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Методы экземпляра Paginator и LengthAwarePaginator

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

Методы экземпляра Cursor Paginator

Каждый экземпляр Cursor-пагинатора предоставляет дополнительную информацию о постраничной навигации с помощью следующих методов: