Пейджинг

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

Пример

Передайте Paginator список объектов и количество элементов на каждой странице, и он предоставит методы для доступа к элементам каждой страницы:

>>> from django.core.paginator import Paginator
>>> objects = ['john', 'paul', 'george', 'ringo']
>>> p = Paginator(objects, 2)

>>> p.count
4
>>> p.num_pages
2
>>> p.page_range
[1, 2]

>>> page1 = p.page(1)
>>> page1
<Page 1 of 2>
>>> page1.object_list
['john', 'paul']

>>> page2 = p.page(2)
>>> page2.object_list
['george', 'ringo']
>>> page2.has_next()
False
>>> page2.has_previous()
True
>>> page2.has_other_pages()
True
>>> page2.next_page_number()
Traceback (most recent call last):
...
EmptyPage: That page contains no results
>>> page2.previous_page_number()
1
>>> page2.start_index() # The 1-based index of the first item on this page
3
>>> page2.end_index() # The 1-based index of the last item on this page
4

>>> p.page(0)
Traceback (most recent call last):
...
EmptyPage: That page number is less than 1
>>> p.page(3)
Traceback (most recent call last):
...
EmptyPage: That page contains no results

Использование Paginator в представлении

Вот немного более сложный пример использования Paginator в представлении для разбиения запроса на страницы. Мы предоставляем как представление, так и соответствующую шаблонную страницу, чтобы показать, как вы можете отобразить результаты. Этот пример предполагает, что у вас есть модель Contacts, которая уже импортирована.

Функция представления выглядит следующим образом:

from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger

def listing(request):
    contact_list = Contacts.objects.all()
    paginator = Paginator(contact_list, 25) # Show 25 contacts per page

    page = request.GET.get('page')
    try:
        contacts = paginator.page(page)
    except PageNotAnInteger:
        # If page is not an integer, deliver first page.
        contacts = paginator.page(1)
    except EmptyPage:
        # If page is out of range (e.g. 9999), deliver last page of results.
        contacts = paginator.page(paginator.num_pages)

    return render_to_response('list.html', {"contacts": contacts})

В шаблоне list.html, вы захотите включить навигацию между страницами вместе с любой интересной информацией из самих объектов:

{% for contact in contacts %}
    {# Each "contact" is a Contact model object. #}
    {{ contact.full_name|upper }}<br />
    ...
{% endfor %}

<div class="pagination">
    <span class="step-links">
        {% if contacts.has_previous %}
            <a href="?page={{ contacts.previous_page_number }}">previous</a>
        {% endif %}

        <span class="current">
            Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
        </span>

        {% if contacts.has_next %}
            <a href="?page={{ contacts.next_page_number }}">next</a>
        {% endif %}
    </span>
</div>

Paginator объекты

Класс Paginator имеет такой конструктор:

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

Необходимые аргументы

object_list

Список, кортеж, Django QuerySet, или другой объект с возможностью срезов с методами count() или __len__().

per_page

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

Необязательные аргументы

orphans

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

allow_empty_first_page

Разрешено ли пустое значение на первой странице. Если False и object_list пусто, то будет возбуждено исключение EmptyPage.

Методы

Paginator.page(number) [source]

Возвращает объект Page с заданным индексом (начиная с 1). Возбуждает исключение InvalidPage, если заданный номер страницы не существует.

Атрибуты

Paginator.count

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

Примечание

При определении количества объектов, содержащихся в object_list, Paginator в первую очередь попытается вызвать object_list.count(). Если object_list не имеет метода count(), то Paginator перейдет к использованию len(object_list). Это позволяет объектам, таким как Django QuerySet, использовать более эффективный метод count() при его наличии.

Paginator.num_pages

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

Paginator.page_range

Диапазон номеров страниц (начиная с 1), например, [1, 2, 3, 4].

InvalidPage исключения

exception InvalidPage [source]

Базовый класс исключений, возбуждаемых, когда пагинатор получает неверный номер страницы.

Метод Paginator.page() возбуждает исключение, если запрошенная страница неверна (т.е. не является целым числом) или на ней нет объектов. Обычно достаточно перехватить исключение InvalidPage, но если вам нужна более детальная обработка, вы можете перехватить любое из следующих исключений:

exception PageNotAnInteger [source]

Возбуждается, когда page() получает значение, которое не является целым числом.

exception EmptyPage [source]

Возбуждается, когда page() получает допустимое значение, но на этой странице нет объектов.

Оба исключения являются подклассами InvalidPage, поэтому вы можете обработать их оба с помощью простого except InvalidPage.

Page объекты

Вы обычно не будете создавать объекты Page вручную — вы получите их с помощью 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().

Page.end_index() [source]

Возвращает индекс (начиная с 1) последнего объекта на странице, относительно всех объектов в списке пагинатора. Например, при разбиении списка из 5 объектов на страницы по 2 объекта на страницу, второй странице будет возвращать end_index().

Атрибуты

Page.object_list

Список объектов на этой странице.

Page.number

Номер страницы (начиная с 1) для этой страницы.

Page.paginator

Связанный объект Paginator.