Разделитель страниц

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

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

Paginator класс

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

Разделитель страниц ведет себя как последовательность 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) [source]

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

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

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

Paginator.page(number) [source]

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

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

Возвращает список номеров страниц (от 1) аналогичный 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 [source]

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

Примечание

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

Paginator.num_pages [source]

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

Paginator.page_range [source]

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

Page класс

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

class Page(object_list, number, paginator) [source]

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

Методы

Page.has_next() [source]

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

Page.has_previous() [source]

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

Page.has_other_pages() [source]

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

Page.next_page_number() [source]

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

Page.previous_page_number() [source]

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

Page.start_index() [source]

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

Page.end_index() [source]

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

Атрибуты

Page.object_list

Список записей на этой странице.

Page.number

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

Page.paginator

Связанный объект Paginator.

Исключения

exception InvalidPage [source]

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

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

exception PageNotAnInteger [source]

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

exception EmptyPage [source]

Генерируется, когда page() получает допустимое значение, но на этой странице нет записей.

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