Django提供了一些類來幫助你管理分頁的數(shù)據(jù) -- 也就是說，數(shù)據(jù)被分在不同頁面中，并帶有“上一頁/下一頁”標(biāo)簽。這些類位于django/core/paginator.py中。

示例

向Paginator提供對象的列表，以及你想為每一頁分配的元素數(shù)量，它就會為你提供訪問每一頁上對象的方法：

>>> 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提供一個列表或元組，Django的QuerySet，或者任何帶有count()或__len__()方法的對象。當(dāng)計算傳入的對象所含對象的數(shù)量時，Paginator會首先嘗試調(diào)用count()，接著如果傳入的對象沒有count()方法則回退調(diào)用 len()。這樣會使類似于Django的QuerySet的對象使用更加高效的 count()方法，如果存在的話。

使用 Paginator

這里有一些復(fù)雜一點的例子，它們在視圖中使用 Paginator 來為查詢集分頁。我們提供視圖以及相關(guān)的模板來展示如何展示這些結(jié)果。這個例子假設(shè)你擁有一個已經(jīng)導(dǎo)入的Contacts模型。

視圖函數(shù)看起來像是這樣：

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模板中，你會想要包含頁面之間的導(dǎo)航，以及來自對象本身的任何有趣的信息：

<div class="pagination">
    <span class="step-links">

        <span class="current">
            Page  of .
        </span>

    </span>
</div>

Paginator objects

Paginator類擁有以下構(gòu)造器：

class Paginator(_objectlist, _perpage, orphans=0, _allow_empty_firstpage=True)[source]

所需參數(shù)

object_list

A list, tuple, Django QuerySet, or other sliceable object with a count() or __len__() method.

per_page

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

可選參數(shù)

orphans

The minimum number of items allowed on the last page, defaults to zero. Use this when you don’t want to have a last page with very few items. If the last page would normally have a number of items less than or equal to orphans, then those items will be added to the previous page (which becomes the last page) instead of leaving the items on a page by themselves. For example, with 23 items, per_page=10, and orphans=3, there will be two pages; the first page with 10 items and the second (and last) page with 13 items.

allow_empty_first_page

Whether or not the first page is allowed to be empty. If False and object_list is empty, then an EmptyPage error will be raised.

方法

Paginator.``page(number)[source]

返回在提供的下標(biāo)處的Page對象，下標(biāo)以1開始。如果提供的頁碼不存在，拋出InvalidPage異常。

屬性

Paginator.``count

所有頁面的對象總數(shù)。

注意

當(dāng)計算object_list所含對象的數(shù)量時， Paginator會首先嘗試調(diào)用object_list.count()。如果object_list沒有 count() 方法，Paginator 接著會回退使用len(object_list)。這樣會使類似于Django’s QuerySet的對象使用更加便捷的count()方法，如果存在的話。

Paginator.``num_pages

頁面總數(shù)。

Paginator.``page_range

頁碼的范圍，從1開始，例如[1, 2, 3, 4]。

InvalidPage exceptions

exception InvalidPage[source]

異常的基類，當(dāng)paginator傳入一個無效的頁碼時拋出。

Paginator.page()放回在所請求的頁面無效（比如不是一個整數(shù)）時，或者不包含任何對象時拋出異常。通常，捕獲InvalidPage異常就夠了，但是如果你想更加精細(xì)一些，可以捕獲以下兩個異常之一：

exception PageNotAnInteger[source]

當(dāng)向page()提供一個不是整數(shù)的值時拋出。

exception EmptyPage[source]

當(dāng)向page()提供一個有效值，但是那個頁面上沒有任何對象時拋出。

這兩個異常都是InvalidPage的子類，所以你可以通過簡單的except InvalidPage來處理它們。

Page objects

你通常不需要手動構(gòu)建 Page對象 -- 你可以從Paginator.page()來獲得它們。

class Page(_objectlist, number, paginator)[source]

當(dāng)調(diào)用len()或者直接迭代一個頁面的時候，它的行為類似于 Page.object_list 的序列。

方法

Page.``has_next()[source]

Returns True if there’s a next page.

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]

返回當(dāng)前頁上的第一個對象，相對于分頁列表的所有對象的序號，從1開始。比如，將五個對象的列表分為每頁兩個對象，第二頁的start_index()會返回3。

Page.``end_index()[source]

返回當(dāng)前頁上的最后一個對象，相對于分頁列表的所有對象的序號，從1開始。 比如，將五個對象的列表分為每頁兩個對象，第二頁的end_index() 會返回 4。

屬性

Page.``object_list

當(dāng)前頁上所有對象的列表。

Page.``number

當(dāng)前頁的序號，從1開始。

Page.``paginator

相關(guān)的Paginator對象。

譯者：Django 文檔協(xié)作翻譯小組，原文：Pagination。

本文以 CC BY-NC-SA 3.0 協(xié)議發(fā)布，轉(zhuǎn)載請保留作者署名和文章出處。

Django 文檔協(xié)作翻譯小組人手緊缺，有興趣的朋友可以加入我們，完全公益性質(zhì)。交流群：467338606。