Пагинатор

Django предоставляет несколько классов, которые помогают управлять данными, разбитыми на несколько страниц, с ссылками «Предыдущая/Следующая». Эти классы находятся в django/core/paginator.py.

Примеры см. в руководстве по пагинации.

Paginator класс

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)

Пагинатор ведет себя как последовательность Page при использовании len() или при прямом итерировании.

Paginator.object_list

Обязательный параметр. Список, кортеж, QuerySet, или другой разрезаемый объект с методами count() или __len__(). Для согласованной пагинации элементы QuerySet должны быть отсортированы, например, с помощью условия order_by() или с помощью полей ordering в модели.

Проблемы производительности при пагинации больших QuerySet

Если вы используете QuerySet с очень большим количеством элементов, запрос к высоким страницам может быть медленным на некоторых базах данных, потому что полученный LIMIT/OFFSET запрос должен подсчитать количество OFFSET записей, что занимает больше времени по мере увеличения номера страницы.

Paginator.per_page

Обязательный параметр. Максимальное количество элементов на странице, не включая сироты (см. необязательный аргумент orphans ниже).

Paginator.orphans

Необязательный параметр. Используйте его, когда вы не хотите, чтобы последняя страница имела очень мало элементов. Если последняя страница обычно содержит число элементов меньше или равно orphans, то эти элементы будут добавлены к предыдущей странице (которая становится последней), вместо того, чтобы оставлять их на отдельной странице. Например, с 23 элементами, per_page=10, и orphans=3, будет две страницы; первая страница с 10 элементами, а вторая (и последняя) — с 13 элементами. Значение orphans по умолчанию равно нулю, что означает, что страницы никогда не объединяются, и последняя страница может содержать один элемент.

Paginator.allow_empty_first_page

Необязательный параметр. Разрешено ли, чтобы первая страница была пустой. Если False и object_list пуста, то будет поднято исключение EmptyPage.

Paginator.error_messages

Добавлено в Django 5.0.

Аргумент error_messages позволяет переопределить стандартные сообщения, которые будет выводить пагинатор. Передайте словарь с ключами, соответствующими сообщениям об ошибках, которые вы хотите переопределить. Доступные ключи сообщений об ошибках: invalid_page, min_page, и no_results.

Например, вот сообщение об ошибке по умолчанию:

>>> from django.core.paginator import Paginator
>>> paginator = Paginator([1, 2, 3], 2)
>>> paginator.page(5)
Traceback (most recent call last):
  ...
EmptyPage: That page contains no results

А вот настраиваемое сообщение об ошибке:

>>> paginator = Paginator(
...     [1, 2, 3],
...     2,
...     error_messages={"no_results": "Page does not exist"},
... )
>>> paginator.page(5)
Traceback (most recent call last):
  ...
EmptyPage: Page does not exist

Методы

Paginator.get_page(number)

Возвращает объект Page с заданным индексом (с учётом нумерации с 1), обрабатывая также некорректные и вне диапазона номера страниц.

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

Возвращает исключение EmptyPage только если вы указали Paginator(..., allow_empty_first_page=False) и object_list пуста.

Paginator.page(number)

Возвращает объект Page с заданным индексом (с учётом нумерации с 1). Поднимает PageNotAnInteger, если number нельзя преобразовать в целое число, вызвав int(). Поднимает EmptyPage, если указанной страницы не существует.

Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)

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

Количество страниц по обе стороны от текущего номера страницы определяется аргументом on_each_side, по умолчанию равным 3.

Количество страниц в начале и конце диапазона страниц определяется аргументом on_ends, по умолчанию равным 2.

Например, при значениях по умолчанию для on_each_side и on_ends, если текущая страница — 10, а общее число страниц — 50, диапазон страниц будет [1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]. Это приведет к страницам 7, 8 и 9 слева и 11, 12 и 13 справа от текущей страницы, а также страницам 1 и 2 в начале и 49 и 50 в конце.

Поднимает InvalidPage, если указанной страницы не существует.

Атрибуты

Paginator.ELLIPSIS

Строка, используемая для замены пропущенных номеров страниц в диапазоне страниц, возвращаемом get_elided_page_range(). По умолчанию '…'.

Paginator.count

Общее количество элементов на всех страницах.

Примечание

При определении количества элементов, содержащихся в object_list, Paginator сначала попытается вызвать object_list.count(). Если у object_list нет метода count(), то Paginator вернётся к использованию len(object_list). Это позволяет объектам, таким как QuerySet, использовать более эффективный метод count() при его наличии.

Paginator.num_pages

Общее количество страниц.

Paginator.page_range

Итератор диапазона страниц с нумерацией с 1, например, возвращая [1, 2, 3, 4].

Page класс

Обычно вы не создаёте объекты Page вручную — вы получаете их, итерируя Paginator, или используя Paginator.page().

class Page(object_list, number, paginator)

Страница ведет себя как последовательность Page.object_list при использовании len() или при прямом итерировании.

Методы

Page.has_next()

Возвращает True если следующая страница существует.

Page.has_previous()

Возвращает True если предыдущая страница существует.

Page.has_other_pages()

Возвращает True если существует следующая или предыдущая страница.

Page.next_page_number()

Возвращает номер следующей страницы. Поднимает InvalidPage если следующая страница не существует.

Page.previous_page_number()

Возвращает номер предыдущей страницы. Поднимает InvalidPage если предыдущая страница не существует.

Page.start_index()

Возвращает индекс первой записи на странице, отсчитываемый с 1 относительно всего списка объектов в пагинаторе. Например, при пагинации списка из 5 объектов с 2 объектами на странице, start_index() второй страницы вернёт 3.

Page.end_index()

Возвращает индекс последней записи на странице, отсчитываемый с 1 относительно всего списка объектов в пагинаторе. Например, при пагинации списка из 5 объектов с 2 объектами на странице, end_index() второй страницы вернёт 4.

Атрибуты

Page.object_list

Список объектов на данной странице.

Page.number

Номер страницы (с 1) для данной страницы.

Page.paginator

Соответствующий объект Paginator.

Исключения

exception InvalidPage

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

Метод Paginator.page() генерирует исключение, если запрошенная страница некорректна (т.е. не является целым числом) или не содержит объектов. Обычно достаточно перехватить исключение InvalidPage, но если вам нужна более детальная информация, вы можете перехватить любое из следующих исключений:

exception PageNotAnInteger

Выбрасывается, когда page() получает значение, которое не является целым числом.

exception EmptyPage

Выбрасывается, когда page() получает корректное значение, но на данной странице нет объектов.

Оба исключения являются подклассами InvalidPage, поэтому вы можете обработать их оба с помощью except InvalidPage.