Pagination

<sf-pagination> — подвал длинного списка или таблицы: сколько всего записей, на какой странице читатель, как перейти на другую и сколько записей показывать. Он собирает раскладку обычной пагинации с полем номера между стрелками, как в табличном представлении. Данные компонент не загружает: приложение передаёт числа и по событиям загружает нужную страницу.

Пример

HTML

<div class="flex flex-col gap-2" data-pagination-demo>
  <sf-pagination aria-label="Страницы заказов" current="3" total="240" page-size="20" top="false"></sf-pagination>
  <p class="m-0" role="status" data-pagination-result>Открыта страница 3.</p>
</div>

JavaScript

document.querySelectorAll('[data-pagination-demo]').forEach((demo) => {
  const result = demo.querySelector('[data-pagination-result]');
  demo.addEventListener('sf-page-change', (event) => {
    result.textContent = `Открыта страница ${event.detail.current}.`;
  });
  demo.addEventListener('sf-page-size-change', (event) => {
    result.textContent = `На странице ${event.detail.pageSize} записей, открыта страница ${event.detail.current}.`;
  });
});

Применение

Числа

total — сколько записей всего, page-size — сколько на странице, current — номер текущей страницы, начиная с единицы. Число страниц компонент считает сам и держит current в его пределах. При total="0" переходы и выбор размера не показываются.

Состав подвала

В начале строки — общее количество. В середине — подпись «Страницы:», стрелки «В начало» и «Предыдущая страница», поле с номером текущей страницы и стрелки «Следующая страница» и «Последняя». Стрелки назад видны со второй страницы, стрелки вперёд — пока следующая страница есть. В поле можно набрать любой номер и нажать Enter; номер за пределами списка приводится к первой или последней странице.

В конце строки — кнопка «Показать ещё» и выбор размера страницы. Кнопку убирает top="false", выбор размера — show-page-size="false"; варианты размера задаёт page-sizes, по умолчанию 10,20,30,40. show-more-busy делает кнопку «Показать ещё» занятой, пока приложение догружает записи. middle="false" убирает всю строку подвала.

Переход и события

Компонент сам меняет current и page-size и сообщает об изменении всплывающим событием; приложение по нему загружает записи. В event.detail каждого события есть также component.

Событие	Когда	Поля `event.detail`
`sf-page-change`	открыта другая страница	`previous`, `current`, `total`, `pageCount`, `pageSize`
`sf-page-size-change`	выбран другой размер страницы	`previous`, `pageSize`, `current`, `total`, `pageCount`
`sf-show-more`	нажата «Показать ещё»	`current`, `total`, `pageSize`, `pageCount`, `hasNext`, `item`
`sf-count-request`	запрошено общее количество	`reason`, `current`, `pageSize`

При смене размера current остаётся в пределах нового числа страниц. goToPage(n), setPageSize(n) и showMore() делают то же из кода, onPageChange(handler) передаёт обработчику номер новой страницы первым аргументом.

Количество неизвестно

Список, который не считает записи на каждом запросе, задаёт count-known="false" и сообщает has-next, есть ли следующая страница. Тогда вместо числа в начале строки стоит ссылка «Показать количество» — если задан can-count. Нажатие на неё, на стрелку «Последняя» и отметка «Для всех» отправляют sf-count-request с причиной в detail.reason: total, last-page или action-for-all. Пока приложение считает, компонент показывает короткое ожидание; ответ приходит атрибутами total, count-known и снятым counting.

HTML

<sf-pagination aria-label="Страницы журнала событий" count-known="false" can-count has-next current="4" page-size="50" top="false" show-page-size="false" data-pagination-count-demo></sf-pagination>

JavaScript

document.querySelectorAll('[data-pagination-count-demo]').forEach((pagination) => {
  pagination.addEventListener('sf-count-request', (event) => {
    setTimeout(() => {
      pagination.setState({counting: false, countKnown: true, total: 1234});
      if (event.detail.reason === 'last-page') pagination.goToPage(Math.ceil(1234 / 50));
    }, 800);
  });
});

Действия с отмеченными

actions и selected-count добавляют панель действий с отмеченными строками: сколько отмечено, список действий, «Применить» и сброс выделения. Панель видна, пока selected-count больше нуля. Действия задаются строкой значение:Подпись через |, флаги disabled и selected идут после ::. Действие по умолчанию не выбрано, поэтому «Применить» недоступна, пока пользователь не выберет его сам. show-action-for-all добавляет отметку «Для всех» — применить действие ко всем записям под фильтром.

Компонент не хранит выделение: selected-count передаёт приложение, а sf-action-change (previous, action), sf-action-for-all-change (previous, actionForAll), sf-action-apply (action, actionForAll, current, total, pageSize, pageCount) и sf-selection-clear (selectedCount, total) сообщают ему о выборе пользователя. bottom="false" убирает панель, если действия показывает соседний компонент.

HTML

<sf-pagination
  aria-label="Страницы заказов"
  current="1"
  total="240"
  page-size="20"
  selected-count="3"
  actions="archive:Архивировать|export:Выгрузить|delete:Удалить"
></sf-pagination>

JavaScript

const pagination = document.querySelector('sf-pagination');

pagination.addEventListener('sf-page-change', async (event) => {
  const {current, pageSize} = event.detail;
  renderRows(await loadOrders({page: current, size: pageSize}));
});

pagination.addEventListener('sf-action-apply', async (event) => {
  await applyToSelected(event.detail.action);
  pagination.setAttribute('selected-count', '0');
});

Подписи

Все подписи — «Всего:», «Страницы:», «Показать ещё», «На странице:» и доступные имена стрелок — берутся из языка страницы: на русской странице они русские. Атрибуты total-label, pages-label, previous-label, next-label, first-label, last-label, page-field-label и другие из справочника заменяют отдельные слова.

Доступность

Корень — ориентир nav. Имя по умолчанию — «Страницы результатов»; если на странице несколько списков, задайте каждому своё в aria-label.
Стрелки — кнопки-иконки с доступными именами и подсказками. Поле номера подписано «Страница:» и переходит по Enter; стрелки и поле — обычные остановки Tab.
Переход сам ничего не объявляет. Сообщите о загрузке новых записей в области с role="status", если они появляются не рядом с подвалом.
Панель действий с отмеченными — область с именем «Действия с отмеченными»; у кнопки сброса выделения есть имя «Снять выделение».

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.


Тег	`<sf-pagination>`
Назначение	Навигация по коллекции, разбитой на пронумерованные страницы, на основе источника данных.
Контракт	`smart.pagination`, версия `1.0.1`
Поставка	выпуск Framework `ui-106d5901f8c3`
Жизненный цикл	экспериментальный: API может меняться между выпусками
Готовность	принят в продукт
Заготовка до прихода кода	сервер пишет `data-sf-skeleton="block"`; своего скелетона при загрузке данных нет (Заготовка до прихода кода)

Атрибуты

template — string, по умолчанию default. Имя шаблона.
top — boolean, по умолчанию true. Показывает совместимый блок «показать ещё».
middle — boolean, по умолчанию true. Показывает навигацию по страницам и сводку по коллекции.
bottom — boolean, по умолчанию true. Разрешает совместимый раздел пакетных действий.
top-class — string, по умолчанию пусто. Утилитарные классы Framework для раздела «показать ещё».
main-class — string, по умолчанию пусто. Утилитарные классы Framework для раздела навигации.
bottom-class — string, по умолчанию пусто. Утилитарные классы Framework для раздела пакетных действий.
aria-label — string, по умолчанию пусто. Доступное имя области навигации. Пусто — текст на языке страницы (по-английски «Result pages»).
pages-label — string, по умолчанию пусто. Видимая подпись перед элементами страниц. Пусто — текст на языке страницы (по-английски «Pages:»).
page-label — string, по умолчанию пусто. Доступная приставка к номеру страницы. Пусто — текст на языке страницы (по-английски «Page»).
previous-label — string, по умолчанию пусто. Доступное имя действия «предыдущая страница». Пусто — текст на языке страницы (по-английски «Previous page»).
next-label — string, по умолчанию пусто. Доступное имя действия «следующая страница». Пусто — текст на языке страницы (по-английски «Next page»).
last-label — string, по умолчанию пусто. Видимая подпись действия «последняя страница» для совместимости. Пусто — текст на языке страницы (по-английски «Last»).
total-label — string, по умолчанию пусто. Видимая подпись общего числа записей. Пусто — текст на языке страницы (по-английски «Total:»).
selected-label — string, по умолчанию пусто. Видимая подпись числа выбранных записей. Пусто — текст на языке страницы (по-английски «Selected:»).
selected-count — integer, по умолчанию 0, значения: от 0. Количество выбранных элементов, ограниченное диапазоном от нуля до общего количества.
show-more-text — string, по умолчанию пусто. Подпись действия «показать ещё» для совместимости. Пусто — текст на языке страницы (по-английски «Show more»).
current — integer, по умолчанию 1, значения: от 1. Текущий номер страницы, начиная с единицы.
total — integer, по умолчанию 10, значения: от 0. Неотрицательное общее число элементов.
page-size — integer, по умолчанию 10, значения: от 1. Положительное число элементов на странице.
page-sizes — string, по умолчанию 10,20,30,40. Варианты размера страницы — положительные числа через запятую.
show-page-size — boolean, по умолчанию true. Показывает выбор размера страницы для непустой коллекции.
page-size-label — string, по умолчанию пусто. Видимая и доступная подпись выбора размера страницы. Пусто — текст на языке страницы (по-английски «Per page:»).
show-actions — boolean, по умолчанию true. Показывает групповые действия, если они переданы.
actions — string, по умолчанию пусто. Определения совместимых пакетных действий, разделённые вертикальной чертой.
action — string, по умолчанию пусто. Значение выбранного группового действия.
action-apply-text — string, по умолчанию пусто. Подпись кнопки, которая применяет действие к выбранному. Пусто — текст на языке страницы (по-английски «Apply»).
show-action-for-all — boolean, по умолчанию false. Показывает совместимый переключатель «все элементы».
action-for-all — boolean, по умолчанию false. Текущее значение переключателя «все элементы».
action-for-all-label — string, по умолчанию пусто. Подпись переключателя «для всех». Пусто — текст на языке страницы (по-английски «For all»).
actions-label — string, по умолчанию пусто. Доступное имя списка действий над выбранным. Пусто — текст на языке страницы (по-английски «Action for the selected records»).
action-choose-label — string, по умолчанию пусто. Подсказка в списке действий над выбранным, пока действие не выбрано. Пусто — текст на языке страницы (по-английски «Choose an action»).
actions-region-label — string, по умолчанию пусто. Доступное имя панели, которая появляется, пока строки отмечены. Пусто — текст на языке страницы (по-английски «Actions for the selected»).
clear-selection-label — string, по умолчанию пусто. Доступное имя и подсказка элемента, который снимает выбор. Пусто — текст на языке страницы (по-английски «Clear the selection»).
count-known — boolean, по умолчанию true. Известно ли количество записей. Хост, который не считает каждый ответ, задаёт false, и представление предлагает подсчитать количество вместо того, чтобы показывать его.
can-count — boolean, по умолчанию false. Может ли хост подсчитать количество по запросу. Без этого представление ничего не предлагает и ничего не запрашивает.
counting — boolean, по умолчанию false. Счётчик загружается; вместо числа отображается короткое ожидание.
has-next — boolean, по умолчанию false. Существует ли следующая страница. Определяет переход вперёд и «Показать ещё», когда общее количество не передано.
show-count-label — string, по умолчанию пусто. Текст элемента, который просит хост посчитать записи. Пусто — текст на языке страницы (по-английски «Show the number»).
counting-label — string, по умолчанию пусто. Доступное имя короткого ожидания, пока число записей в пути. Пусто — текст на языке страницы (по-английски «Counting»).
first-label — string, по умолчанию пусто. Доступное имя и подсказка элемента, который переходит на первую страницу. Пусто — текст на языке страницы (по-английски «First»).
page-field-label — string, по умолчанию пусто. Подпись поля, в которое вводят номер страницы. Пусто — текст на языке страницы (по-английски «Page:»).
show-more-busy — boolean, по умолчанию false. Отмечает кнопку «Показать ещё» как занятую, пока хост загружает следующую порцию; она отключена и показывает индикатор загрузки.
size — string, по умолчанию 1, значения: 1/2, 1. Ступень лестницы размеров для полей, кнопок, подписей и номеров страниц: 1 или плотная 1/2, как в админке.

Методы

getTopSection() — возвращает object | null. Возвращает элемент верхней секции (.sf-pagination-top) или null, если она не отрисована.
getMainSection() — возвращает object | null. Возвращает элемент основной секции (.sf-pagination-main) или null, если она не отрисована.
getBottomSection() — возвращает object | null. Возвращает элемент нижней секции (.sf-pagination-bottom) или null, если она не отрисована.
goToPage(page: number|string) — возвращает object. Переходит на страницу: номер разбирается как целое число и ограничивается диапазоном 1..pageCount, если количество известно (иначе только снизу значением 1). Отправляет sf-page-change, когда страница действительно меняется; ничего не делает, если известно, что всего страниц ноль.
showMore(item?: object) — возвращает object. Отправляет sf-show-more с текущими параметрами пагинации и переданным пунктом; не выполняет запрос и не меняет состояние.
setPageSize(size: number|string) — возвращает object. Устанавливает положительный размер страницы, удерживает текущую страницу в пределах нового числа страниц и отправляет sf-page-size-change. Неположительный, нечисловой или неизменный размер игнорируется.
setAction(action: string) — возвращает object. Выбирает групповое действие по значению (пустое значение сбрасывает выбор) и отправляет sf-action-change, если оно отличается от текущего.
setActionForAll(value: boolean) — возвращает object. Задаёт, применяется ли групповое действие ко всем записям под фильтром, и отправляет sf-action-for-all-change. При включении также запрашивает количество (sf-count-request с reason action-for-all), если оно ещё неизвестно.
setState(nextState: object) — возвращает object. Записывает каждый ключ как атрибут в kebab-case: false, null, undefined или пустая строка удаляет атрибут, true устанавливает его пустым, всё остальное приводится к строке.
onPageChange(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик sf-page-change; обработчик вызывается с (current, detail, event). Обработчик, не являющийся функцией, игнорируется.
onShowMore(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик sf-show-more; обработчик вызывается с (detail, event). Обработчик, не являющийся функцией, игнорируется.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

sf-action-apply — detail: { component: object, tagName: string, template: string, action: string, actionForAll: boolean, current: number, total: number, pageSize: number, pageCount: number|null }.
sf-action-change — detail: { component: object, tagName: string, template: string, previous: string, action: string }.
sf-action-for-all-change — detail: { component: object, tagName: string, template: string, previous: boolean, actionForAll: boolean }.
sf-count-request — detail: { component: object, tagName: string, template: string, reason: string, current: number, pageSize: number }.
sf-page-change — detail: { component: object, tagName: string, template: string, previous: number, current: number, total: number, pageCount: number|null, pageSize: number }.
sf-page-size-change — detail: { component: object, tagName: string, template: string, previous: number, pageSize: number, current: number, total: number, pageCount: number }.
sf-selection-clear — detail: { component: object, tagName: string, template: string, selectedCount: number, total: number }.
sf-show-more — detail: { component: object, tagName: string, template: string, current: number, total: number, pageSize: number, pageCount: number|null, hasNext: boolean, item: object|null }.

Доступность

Роль: навигация (navigation).
Доступное имя: обязательно.
Клавиши: Tab.
Фокус: Tab переходит только к включённым нативным действиям. Фокус использует общее оформление focus-visible только для клавиатуры и остаётся видимым в режиме forced colors; пропущенные страницы не получают фокус.

Минимальная разметка

HTML

<sf-pagination aria-label="Страницы результатов поиска" current="2" total="96" page-size="10" top="false" bottom="false" show-page-size="false"></sf-pagination>

Источник

simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/pagination
simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-pagination

См. также

Dropdown — выбор размера страницы устроен так же.

Навигация

Главное

Документация

Содержание

Пример

Применение

Числа

Состав подвала

Переход и события

Количество неизвестно

Действия с отмеченными

Подписи

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

Минимальная разметка

Источник

См. также

Настройки

Pagination

Пример

Применение

Числа

Состав подвала

Переход и события

Количество неизвестно

Действия с отмеченными

Подписи

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

Минимальная разметка

Источник

См. также

Поиск по документации