django 1.8 官方文檔翻譯：13-6 分頁

分頁

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

提供一個清單或元組，Django的

QuerySet

，或者任何帶有

count()

或

__len__()

方法的對象。當計算傳入的對象所含對象的數量時，

Paginator

會首先嘗試調用

count()

，接着如果傳入的對象沒有

count()

方法則回退調用 

len()

。這樣會使類似于Django的

QuerySet

的對象使用更加高效的

count()

方法，如果存在的話。

使用

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

模闆中，你會想要包含頁面之間的導航，以及來自對象本身的任何有趣的資訊：

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

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

    </span>
</div>
           

Paginator objects

Paginator

類擁有以下構造器：

class

Paginator

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

[source]

所需參數

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

可選參數

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)

傳回在提供的下标處的

Page

對象，下标以1開始。如果提供的頁碼不存在，抛出

InvalidPage

異常。

屬性

Paginator.``count

所有頁面的對象總數。

當計算

object_list

所含對象的數量時，

Paginator

object_list.count()

。如果

object_list

沒有

count()

方法，

Paginator

接着會回退使用

len(object_list)

。這樣會使類似于Django’s

QuerySet

的對象使用更加便捷的

count()

Paginator.``num_pages

頁面總數。

Paginator.``page_range

頁碼的範圍，從1開始，例如

[1, 2, 3, 4]

。

InvalidPage exceptions

exception

InvalidPage

異常的基類，當paginator傳入一個無效的頁碼時抛出。

Paginator.page()

放回在所請求的頁面無效（比如不是一個整數）時，或者不包含任何對象時抛出異常。通常，捕獲

InvalidPage

異常就夠了，但是如果你想更加精細一些，可以捕獲以下兩個異常之一：

PageNotAnInteger

當向

page()

提供一個不是整數的值時抛出。

EmptyPage

page()

提供一個有效值，但是那個頁面上沒有任何對象時抛出。

這兩個異常都是

InvalidPage

的子類，是以你可以通過簡單的

except InvalidPage

來處理它們。

Page objects

你通常不需要手動建構

Page

對象 – 你可以從

Paginator.page()

來獲得它們。

Page

(object_list, number, paginator)

當調用

len()

或者直接疊代一個頁面的時候，它的行為類似于

Page.object_list

的序列。

Page.``has_next

()

Returns

True

if there’s a next page.

Page.``has_previous

如果有上一頁，傳回 

True

Page.``has_other_pages

如果有上一頁或下一頁，傳回

True

Page.``next_page_number

傳回下一頁的頁碼。如果下一頁不存在，抛出

InvalidPage

Page.``previous_page_number

傳回上一頁的頁碼。如果上一頁不存在，抛出

InvalidPage

Page.``start_index

傳回目前頁上的第一個對象，相對于分頁清單的所有對象的序号，從1開始。比如，将五個對象的清單分為每頁兩個對象，第二頁的

start_index()

會傳回

3

Page.``end_index

傳回目前頁上的最後一個對象，相對于分頁清單的所有對象的序号，從1開始。 比如，将五個對象的清單分為每頁兩個對象，第二頁的

end_index()

會傳回 

4

Page.``object_list

目前頁上所有對象的清單。

Page.``number

目前頁的序号，從1開始。

Page.``paginator

相關的

Paginator

對象。

譯者： Django 文檔協作翻譯小組 ，原文： Pagination 本文以 CC BY-NC-SA 3.0 協定釋出，轉載請保留作者署名和文章出處。 人手緊缺，有興趣的朋友可以加入我們，完全公益性質。交流群：467338606。