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() или прямой итерации.

Changed in Django 3.1:

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

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

Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)[исходный код]
New in Django Development version.

Возвращает основанный на 1 список номеров страниц, аналогичный Paginator.page_range, но может добавить многоточие к одной или обеим сторонам текущего номера страницы, если Paginator.num_pages большой.

Количество страниц, включаемых с каждой стороны от текущего номера страницы, определяется аргументом on_each_side, который по умолчанию равен 3.

Количество страниц, включаемых в начало и конец диапазона страниц, определяется аргументом on_ends, который по умолчанию равен 2.

For example, with the default values for on_each_side and on_ends, if the current page is 10 and there are 50 pages, the page range will be [1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]. This will result in pages 7, 8, and 9 to the left of and 11, 12, and 13 to the right of the current page as well as pages 1 and 2 at the start and 49 and 50 at the end.

Вызывает сообщение InvalidPage, если заданный номер страницы не существует.

Атрибуты

Paginator.ELLIPSIS
New in Django Development version.

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

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