Паджинатор

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). Вызывает InvalidPage, если заданный номер страницы не существует.

Атрибуты

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.