分页¶ T0>

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
>>> type(p.page_range)  # `<type 'rangeiterator'>` in Python 2.
<class 'range_iterator'>
>>> p.page_range
range(1, 3)

>>> 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

注意你可以向__len__()提供一个列表或元组,Django的Paginator,或者任何带有count()QuerySet方法的对象。 当计算传入的对象所含对象的数量时,count()会首先尝试调用Paginator,接着如果传入的对象没有len()方法则回退调用 count() 这样会使类似于Django的QuerySet的对象使用更加高效的 count()方法,如果存在的话。

在视图中使用Paginator

这里有一些复杂一点的例子,它们在视图中使用 Paginator 来为查询集分页。 我们提供视图以及相关的模板来展示如何展示这些结果。 这个例子假设你拥有一个已经导入的Contacts模型。

视图函数看起来像是这样:

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

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(request, '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中

列表,元组,QuerySet或具有count()__len__()方法的其他可切片的对象。 对于一致的分页,应该排序QuerySet。使用order_by()子句或模型上的默认ordering

性能问题分页大QuerySet s

If you’re using a QuerySet with a very large number of items, requesting high page numbers might be slow on some databases, because the resulting LIMIT/OFFSET query needs to count the number of OFFSET records which takes longer as the page number gets higher.

per_page
The maximum number of items to include on a page, not including orphans (see the orphans optional argument below).

可选参数

orphans
当您不想要最后一个页面的项目很少时,请使用此选项。 如果最后一页通常会有一些小于或等于orphans的项目,那么这些项目将被添加到上一页(成为最后一页),而不是将页面留在页面上通过他们自己。 例如,有23个项目,per_page=10orphans=3,将有两个页面;第一页有10个项目,第二页(最后一页)有13个项目。 orphans默认为零,这意味着页面从不组合,最后一页可能有一个项目。
allow_empty_first_page
第一页是否允许为空。 如果Falseobject_list为空,则将出现EmptyPage错误。

方法¶ T0>

Paginator.page(number)[source]

返回在提供的下标处的Page对象,下标以1开始。 如果提供的页码不存在,抛出InvalidPage异常。

属性¶ T0>

Paginator.count

所有页面的对象总数。

当确定object_list中包含的对象数量时,object_list.count()将首先尝试调用Paginator 如果len(object_list)没有 object_list 方法,Paginator 接着会回退使用count() 这样会使类似于Django’s QuerySet的对象使用更加便捷的count()方法,如果存在的话。

Paginator.num_pages

页面总数。

Paginator.page_range

页数的基于1的范围迭代器,例如。产生[1, 2, 3, 4]

InvalidPage exceptions

exception InvalidPage[source]

异常的基类,当paginator传入一个无效的页码时抛出。

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]

当调用len()或者直接迭代一个页面的时候,它的行为类似于 Page.object_list 的序列。

方法¶ T0>

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开始。 比如,将五个对象的列表分为每页两个对象,第二页的start_index()会返回3

Page.end_index()[source]

返回当前页上的最后一个对象,相对于分页列表的所有对象的序号,从1开始。 比如,将五个对象的列表分为每页两个对象,第二页的end_index() 会返回 4

属性¶ T0>

Page.object_list

当前页上所有对象的列表。

Page.number

当前页的序号,从1开始。

Page.paginator

相关的Paginator对象。