Django提供了一些類來幫助你管理分頁的數(shù)據(jù) -- 也就是說,數(shù)據(jù)被分在不同頁面中,并帶有“上一頁/下一頁”標(biāo)簽。這些類位于django/core/paginator.py
中。
向Paginator
提供對(duì)象的列表,以及你想為每一頁分配的元素?cái)?shù)量,它就會(huì)為你提供訪問每一頁上對(duì)象的方法:
>>> 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
提供一個(gè)列表或元組,Django的QuerySet
,或者任何帶有count()
或__len__()
方法的對(duì)象。當(dāng)計(jì)算傳入的對(duì)象所含對(duì)象的數(shù)量時(shí),Paginator
會(huì)首先嘗試調(diào)用count()
,接著如果傳入的對(duì)象沒有count()
方法則回退調(diào)用 len()
。這樣會(huì)使類似于Django的QuerySet
的對(duì)象使用更加高效的 count()
方法,如果存在的話。
Paginator
這里有一些復(fù)雜一點(diǎn)的例子,它們?cè)谝晥D中使用 Paginator
來為查詢集分頁。我們提供視圖以及相關(guān)的模板來展示如何展示這些結(jié)果。這個(gè)例子假設(shè)你擁有一個(gè)已經(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
模板中,你會(huì)想要包含頁面之間的導(dǎo)航,以及來自對(duì)象本身的任何有趣的信息:
<div class="pagination">
<span class="step-links">
<span class="current">
Page of .
</span>
</span>
</div>
Paginator
類擁有以下構(gòu)造器:
class Paginator
(_objectlist, _perpage, orphans=0, _allow_empty_firstpage=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)[source]
返回在提供的下標(biāo)處的Page
對(duì)象,下標(biāo)以1開始。如果提供的頁碼不存在,拋出InvalidPage
異常。
Paginator.``count
所有頁面的對(duì)象總數(shù)。
注意
當(dāng)計(jì)算object_list
所含對(duì)象的數(shù)量時(shí), Paginator
會(huì)首先嘗試調(diào)用object_list.count()
。如果object_list
沒有 count()
方法,Paginator
接著會(huì)回退使用len(object_list)
。這樣會(huì)使類似于Django’s QuerySet
的對(duì)象使用更加便捷的count()
方法,如果存在的話。
Paginator.``num_pages
頁面總數(shù)。
Paginator.``page_range
頁碼的范圍,從1開始,例如[1, 2, 3, 4]
。
exception InvalidPage
[source]
異常的基類,當(dāng)paginator傳入一個(gè)無效的頁碼時(shí)拋出。
Paginator.page()
放回在所請(qǐng)求的頁面無效(比如不是一個(gè)整數(shù))時(shí),或者不包含任何對(duì)象時(shí)拋出異常。通常,捕獲InvalidPage
異常就夠了,但是如果你想更加精細(xì)一些,可以捕獲以下兩個(gè)異常之一:
exception PageNotAnInteger
[source]
當(dāng)向page()
提供一個(gè)不是整數(shù)的值時(shí)拋出。
exception EmptyPage
[source]
當(dāng)向page()
提供一個(gè)有效值,但是那個(gè)頁面上沒有任何對(duì)象時(shí)拋出。
這兩個(gè)異常都是InvalidPage
的子類,所以你可以通過簡單的except InvalidPage
來處理它們。
你通常不需要手動(dòng)構(gòu)建 Page
對(duì)象 -- 你可以從Paginator.page()
來獲得它們。
class Page
(_objectlist, number, paginator)[source]
當(dāng)調(diào)用len()
或者直接迭代一個(gè)頁面的時(shí)候,它的行為類似于 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)前頁上的第一個(gè)對(duì)象,相對(duì)于分頁列表的所有對(duì)象的序號(hào),從1開始。比如,將五個(gè)對(duì)象的列表分為每頁兩個(gè)對(duì)象,第二頁的start_index()
會(huì)返回3
。
Page.``end_index
()[source]
返回當(dāng)前頁上的最后一個(gè)對(duì)象,相對(duì)于分頁列表的所有對(duì)象的序號(hào),從1開始。 比如,將五個(gè)對(duì)象的列表分為每頁兩個(gè)對(duì)象,第二頁的end_index()
會(huì)返回 4
。
Page.``object_list
當(dāng)前頁上所有對(duì)象的列表。
Page.``number
當(dāng)前頁的序號(hào),從1開始。
Page.``paginator
相關(guān)的Paginator
對(duì)象。
譯者:Django 文檔協(xié)作翻譯小組,原文:Pagination。
本文以 CC BY-NC-SA 3.0 協(xié)議發(fā)布,轉(zhuǎn)載請(qǐng)保留作者署名和文章出處。
Django 文檔協(xié)作翻譯小組人手緊缺,有興趣的朋友可以加入我們,完全公益性質(zhì)。交流群:467338606。