Страничный вывод

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

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

Paginator класс

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

Страничный вывод действует как последовательность 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.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)

Добавлен в 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.