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

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

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

Paginator класс

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

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

Изменено в Django 3.1:

Добавлена поддержка итерирования по Paginator.

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.get_page(number)

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

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

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

Paginator.page(number)

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

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

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

Возвращает список номеров страниц (от 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

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

Переводимая строка, используемая в качестве замены пропущенных номеров страниц в диапазоне страниц, возвращаемом 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.