• 3.1
  • 5.0
  • 6.1
  • Версия документации: 3.2

Пагинатор

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

Примеры см. в Справочнике по разбивке на страницы.

Класс Пагинатор

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

Пагинатор действует как последовательность Page при использовании len() или его прямой итерации.

Changed in Django 3.1:

Support for iterating over Paginator was added.

Paginator.object_list

Необходимый. Список, кортеж, QuerySet или другой срезаемый объект с помощью метода count() или __len__(). Для последовательной нумерации страниц следует упорядочить QuerySet, например: с предложением order_by() или со значением по умолчанию ordering для модели.

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

Если вы используете QuerySet с очень большим количеством элементов, запрос больших номеров страниц может быть медленным в некоторых базах данных, поскольку результирующий запрос LIMIT/OFFSET должен подсчитывать количество записей OFFSET, что занимает больше времени по мере увеличения номера страницы.

Paginator.per_page

Необходимый. Максимальное количество элементов, которые можно включить на страницу, не включая потерянные элементы (см. необязательный аргумент orphans ниже).

Paginator.orphans

Необязательный. Используйте это, если вы не хотите, чтобы на последней странице было очень мало элементов. Если на последней странице обычно количество элементов меньше или равно «сиротам», то эти элементы будут добавлены на предыдущую страницу (которая станет последней страницей), а не оставлять элементы на странице сами по себе. Например, при 23 элементах per_page=10 и orphans=3 будет две страницы; первая страница с 10 элементами и вторая (и последняя) страница с 13 элементами. По умолчанию «сироты» равны нулю, что означает, что страницы никогда не объединяются, и последняя страница может содержать один элемент.

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)

Returns a Page object with the given 1-based index. Raises PageNotAnInteger if the number cannot be converted to an integer by calling int(). Raises InvalidPage if the given page number doesn’t exist.

Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)
New in 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
New in 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 вручную — вы получите их путем итерации 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, поэтому вы можете обрабатывать их оба с помощью кроме InvalidPage.

Back to Top