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

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

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

Paginator класс

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True) [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.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

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

Примечание

При определении количества объектов, содержащихся в 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) [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.