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

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