Paginator

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

Примеры см. в Pagination topic guide.

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 в модели.

Проблемы с производительностью при пагинации больших QuerySets

Если вы используете 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)[исходный код]

Возвращает основанный на 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)[исходный код]

Страница ведет себя как последовательность 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.

Функции базы данных
Объекты запроса и ответа
Вернуться на верх