Класс PageNavigation

Класс \Bitrix\Main\UI\PageNavigation рассчитывает границы выборки для постраничного вывода. Объект хранит номер текущей страницы, размер страницы и общее число записей, а по ним вычисляет смещение и ограничение для запроса.

Класс не обращается к базе данных и не выводит разметку. Он считает числа, которые разработчик передает в запрос и в компонент вывода. Поэтому один и тот же объект подходит для выборки через ORM, для массива в памяти и для внешнего источника данных.

Общий сценарий с примерами кода описан в статье Постраничная навигация.

Контракты методовКонтракты методов

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

Класс \Bitrix\Main\Web\Uri разбирает адрес на части и позволяет менять их по отдельности. Он входит в набор объектов HTTP-клиента — о них читайте в статье HTTP-клиент.

Создать объект навигацииСоздать объект навигации

Конструктор принимает единственный аргумент — идентификатор навигации. Этот же идентификатор становится именем параметра в адресе страницы.

use Bitrix\Main\UI\PageNavigation;

$navigation = new PageNavigation('users');

С таким идентификатором адрес третьей страницы выглядит как /company/?users=page-3.

Метод getId() возвращает идентификатор — он нужен шаблонам навигации, чтобы собрать имя параметра.

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

Задать порядок вызововЗадать порядок вызовов

Порядок вызовов важен: метод initFromUri() учитывает только те настройки, которые заданы до его вызова. Из-за нарушенного порядка навигация продолжает работать, но игнорирует часть параметров из адреса.

Задавайте настройки в таком порядке.

1. Разрешите или запретите показ всех записей методом allowAllRecords().

2. Задайте список разрешенных размеров страницы методом setPageSizes().

3. Задайте размер страницы по умолчанию методом setPageSize().

4. Задайте общее число записей методом setRecordCount().

5. Прочитайте параметры из адреса методом initFromUri().

Пример. Настройка объекта перед выборкой.

use Bitrix\Main\UI\PageNavigation;
use Bitrix\Main\UserTable;

$totalCount = UserTable::getCount();

$navigation = new PageNavigation('users');
$navigation
    ->allowAllRecords(false)
    ->setPageSizes([10, 20, 50])
    ->setPageSize(20)
    ->setRecordCount($totalCount)
    ->initFromUri()
;

Метод initFromUri() ничего не возвращает, поэтому он завершает цепочку вызовов. Продолжить цепочку после него нельзя — следующие настройки задавайте отдельными выражениями.

Число записей действует иначе, чем остальные настройки. Если задать его до initFromUri(), метод ограничит номер страницы сверху: запрос страницы 50 при пяти страницах вернет пятую страницу. Если задать после, номер страницы уже не ограничивается — смещение уйдет за пределы выборки, и запрос вернет пустой результат.

Когда число записей заранее неизвестноКогда число записей заранее неизвестно

Иногда общее число приходит из того же запроса, что и данные, — например, при выборке без отдельного подсчета. Задать его до initFromUri() в таком случае невозможно, и ограничение номера страницы сверху не сработает.

Тогда проверяйте номер страницы сами: после выборки сравните getCurrentPage() с getPageCount() и при выходе за границы покажите пустой результат или перенаправьте на последнюю страницу. Готовый прием для больших таблиц описан в разделе Как работает навигация без COUNT.

Задать размер страницыЗадать размер страницы

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

• setPageSize() — задает текущий размер страницы напрямую, без проверки по списку разрешенных значений,

• setPageSizes() — задает список размеров, которые разрешено выбирать через адрес страницы.

Список задает допустимые значения: initFromUri() применит размер из адреса, только если он есть в списке. При списке [10, 20, 50] адрес ?users=page-2-size-1000 изменит номер страницы, но не размер. Так посетитель не сможет запросить произвольно большую выборку одним изменением адреса.

Список доступен компоненту вывода через getPageSizes(). Переключатель размеров по этому списку строит только шаблон admin компонента main.pagenavigation. Остальные системные шаблоны его не выводят.

Задать число записейЗадать число записей

Общее число записей объект не вычисляет — его задает разработчик методом setRecordCount(). По этому числу считается количество страниц.

$navigation->setRecordCount($totalCount);

Метод getPageCount() делит число записей на размер страницы и округляет результат вверх: при 47 записях и размере страницы 20 получается три страницы, последняя из них неполная.

Пока число записей не задано, объект считает, что страниц нет. Компонент вывода в таком случае навигацию не показывает, поэтому ссылки на странице не появляются.

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

if ($navigation->getPageCount() === 0)
{
    // Записей нет: выборку не выполняем, навигацию не выводим
    return [];
}

Задать номер страницы вручнуюЗадать номер страницы вручную

Обычно номер страницы приходит из адреса через initFromUri().

Метод setCurrentPage() нужен, когда номер берется из другого источника — например, из тела запроса или из сохраненного состояния интерфейса.

$navigation->setCurrentPage(3);

Заданное значение объект не проверяет по числу страниц: номер больше числа страниц даст смещение за пределами выборки, и запрос вернет пустой результат. Номер страницы ограничивает сверху только метод initFromUri() на условиях, описанных в разделе Задать порядок вызовов.

Прочитать параметры из адресаПрочитать параметры из адреса

Метод initFromUri() берет адрес текущего запроса и ищет в нем параметры навигации по идентификатору объекта. Объект поддерживает два формата: параметр запроса и ЧПУ.

Сначала объект ищет параметр запроса с именем, равным идентификатору навигации. Формат значения — пары «ключ-значение» через дефис: page-3-size-20. Для навигации с идентификатором users такой адрес выглядит как /company/?users=page-3-size-20.

Если параметра запроса с таким именем нет, объект разбирает путь адреса. Он ищет в пути фрагмент /идентификатор/page-номер/, за которым может идти /size-размер/: в адресе /company/users/page-3/size-20/ объект прочитает третью страницу по 20 записей.

Из адреса объект читает три значения.

• Номер страницы. Значения меньше единицы объект пропускает и оставляет прежний номер.

• Размер страницы. Применяется, только если значение есть в списке setPageSizes().

• Признак показа всех записей page-all. Включает режим, только если он разрешен через allowAllRecords(true).

Рассчитать границы выборкиРассчитать границы выборки

Два метода дают числа для запроса:

• getOffset() — смещение первой записи текущей страницы,

• getLimit() — ограничение на число записей.

use Bitrix\Main\UserTable;

$users = UserTable::query()
    ->setSelect(['ID', 'LOGIN'])
    ->setOffset($navigation->getOffset())
    ->setLimit($navigation->getLimit())
    ->fetchCollection()
;

Объект отсчитывает смещение от нуля: на первой странице getOffset() возвращает 0, на второй при размере страницы 20 — 20.

На последней неполной странице ограничение оказывается больше, чем фактическое число оставшихся записей. При 47 записях и размере страницы 20 на третьей странице getLimit() вернет 20, а запрос выберет семь записей.

Для запроса такое значение безопасно: ограничение задает верхнюю границу. Использовать getLimit() как число записей на странице нельзя. Чтобы вывести, сколько записей показано, берите фактическое число строк результата.

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

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

• allowAllRecords() — разрешает режим, но не включает его,

• allRecordsAllowed() — возвращает разрешение,

• allRecordsShown() — показывает, включен ли режим для текущего запроса.

Сам режим включает метод initFromUri(), когда находит в адресе page-all.

Пример. Включение режима и проверка его состояния перед выборкой.

use Bitrix\Main\UI\PageNavigation;
use Bitrix\Main\UserTable;

$navigation = new PageNavigation('users');
$navigation
    ->allowAllRecords(true)
    ->setPageSize(20)
    ->initFromUri()
;

// Число записей нужно задать до расчета границ выборки
$totalCount = UserTable::getCount();
$navigation->setRecordCount($totalCount);

$users = UserTable::query()
    ->setSelect(['ID', 'LOGIN'])
    ->setOffset($navigation->getOffset())
    ->setLimit($navigation->getLimit())
    ->fetchCollection()
;

Порядок вызовов в этом режиме особенно важен. Метод getLimit() возвращает общее число записей, поэтому задайте число записей до расчета границ выборки. Если оно не задано, метод вернет null и выборка окажется неограниченной.

Сформировать ссылкиСформировать ссылки

Компонент bitrix:main.pagenavigation выводит готовые ссылки на страницы. Собирайте адрес вручную в двух случаях: когда встраиваете навигацию в собственный шаблон и когда строите ссылку вне компонента. За это отвечают два метода:

• addParams() — добавляет в адрес параметры навигации,

• clearParams() — удаляет их и возвращает базовый адрес списка.

У метода addParams() третий аргумент задает номер страницы, четвертый — размер страницы. Без четвертого аргумента в ссылку попадет только номер страницы, а размер останется прежним.

Аргумент $sef выбирает формат ссылки: в режиме ЧПУ метод добавляет параметры в путь адреса, иначе — в строку запроса. Оба формата совместимы с initFromUri(). Готовый пример с обоими форматами есть в статье Постраничная навигация.

Метод clearParams() затрагивает только параметры текущей навигации, остальные параметры адреса остаются на месте. Так вы получите базовый адрес списка — например, для ссылки на первую страницу.

use Bitrix\Main\UI\PageNavigation;
use Bitrix\Main\Web\Uri;

$navigation = new PageNavigation('users');

$uri = new Uri('https://example.com/company/?users=page-3&sort=name');
$isSefMode = false;

echo (string)$navigation->clearParams($uri, $isSefMode);
// https://example.com/company/?sort=name

В режиме ЧПУ метод addParams() сам вызывает clearParams() перед добавлением параметров, поэтому прежний номер страницы в пути не дублируется.

Класс AdminPageNavigationКласс AdminPageNavigation

Класс \Bitrix\Main\UI\AdminPageNavigation наследует PageNavigation и подставляет настройки, принятые в административном разделе. Кроме конструктора, собственных методов у него нет.

Отличий три.

• Список разрешенных размеров страницы содержит значения 10, 20, 50, 100, 200 и 500.

• Режим показа всех записей разрешен.

• Конструктор сам вызывает initFromUri().

use Bitrix\Main\UI\AdminPageNavigation;
use Bitrix\Main\UserTable;

$navigation = new AdminPageNavigation('users');

$totalCount = UserTable::getCount();
$navigation->setRecordCount($totalCount);

Повторно вызывать initFromUri() не нужно: конструктор уже прочитал параметры. По той же причине настройки, заданные после конструктора, на разбор адреса не влияют.

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

Второй наследник — класс ReversePageNavigation. Он считает границы выборки от конца списка и переопределяет расчет страниц, смещения и ограничения.

Получить объект в контроллереПолучить объект в контроллере

Контроллеру объект навигации создавать не нужно: достаточно объявить аргумент типа PageNavigation, и ядро подставит готовый объект. Ядро создает его с идентификатором nav и уже прочитанными параметрами адреса. Разрешенный размер страницы — от 1 до 50.

final class Iblock extends Controller
{
    // ...

    public function paginationAction(\Bitrix\Main\UI\PageNavigation $pagination): array
    {
        return [
            'page' => $pagination->getCurrentPage(),
            'size' => $pagination->getPageSize(),
            'limit' => $pagination->getLimit(),
            'offset' => $pagination->getOffset(),
        ];
    }
}

Из жестко заданного идентификатора и диапазона размеров следуют два ограничения.

• Размер страницы вне диапазона от 1 до 50 не применится.

• Два независимых списка в одном действии получить нельзя: идентификатор задан жестко.

Для этих случаев создавайте объект вручную.

Число записей ядро не задает, поэтому номер страницы из адреса не ограничивается сверху. Задайте число записей после выборки методом setRecordCount() и проверьте номер страницы самостоятельно.

Сценарий целиком с примером действия и ответом описан в статье Контроллеры.