# 分頁
Django提供了一些類來幫助你管理分頁的數據 -- 也就是說,數據被分在不同頁面中,并帶有“上一頁/下一頁”標簽。這些類位于`django/core/paginator.py`中。
## 示例
向[`Paginator`](#django.core.paginator.Paginator "django.core.paginator.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`](#django.core.paginator.Paginator "django.core.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`](#django.core.paginator.Paginator "django.core.paginator.Paginator")類擁有以下構造器:
_class _`Paginator`(_object_list_, _per_page_, _orphans=0_, _allow_empty_first_page=True_)[[source]](../_modules/django/core/paginator.html#Paginator)
### 所需參數
`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]](../_modules/django/core/paginator.html#Paginator.page)
返回在提供的下標處的[`Page`](#django.core.paginator.Page "django.core.paginator.Page")對象,下標以1開始。如果提供的頁碼不存在,拋出[`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.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`[[source]](../_modules/django/core/paginator.html#InvalidPage)
異常的基類,當paginator傳入一個無效的頁碼時拋出。
[`Paginator.page()`](#django.core.paginator.Paginator.page "django.core.paginator.Paginator.page")放回在所請求的頁面無效(比如不是一個整數)時,或者不包含任何對象時拋出異常。通常,捕獲`InvalidPage`異常就夠了,但是如果你想更加精細一些,可以捕獲以下兩個異常之一:
_exception _`PageNotAnInteger`[[source]](../_modules/django/core/paginator.html#PageNotAnInteger)
當向`page()`提供一個不是整數的值時拋出。
_exception _`EmptyPage`[[source]](../_modules/django/core/paginator.html#EmptyPage)
當向`page()`提供一個有效值,但是那個頁面上沒有任何對象時拋出。
這兩個異常都是[`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.InvalidPage")的子類,所以你可以通過簡單的`except InvalidPage`來處理它們。
## Page objects
你通常不需要手動構建 `Page`對象 -- 你可以從[`Paginator.page()`](#django.core.paginator.Paginator.page "django.core.paginator.Paginator.page")來獲得它們。
_class _`Page`(_object_list_, _number_, _paginator_)[[source]](../_modules/django/core/paginator.html#Page)
當調用`len()`或者直接迭代一個頁面的時候,它的行為類似于 [`Page.object_list`](#django.core.paginator.Page.object_list "django.core.paginator.Page.object_list") 的序列。
### 方法
`Page.``has_next`()[[source]](../_modules/django/core/paginator.html#Page.has_next)
Returns `True` if there’s a next page.
`Page.``has_previous`()[[source]](../_modules/django/core/paginator.html#Page.has_previous)
如果有上一頁,返回 `True`。
`Page.``has_other_pages`()[[source]](../_modules/django/core/paginator.html#Page.has_other_pages)
如果有上一頁_或_下一頁,返回`True`。
`Page.``next_page_number`()[[source]](../_modules/django/core/paginator.html#Page.next_page_number)
返回下一頁的頁碼。如果下一頁不存在,拋出[`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.InvalidPage")異常。
`Page.``previous_page_number`()[[source]](../_modules/django/core/paginator.html#Page.previous_page_number)
返回上一頁的頁碼。如果上一頁不存在,拋出[`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.InvalidPage")異常。
`Page.``start_index`()[[source]](../_modules/django/core/paginator.html#Page.start_index)
返回當前頁上的第一個對象,相對于分頁列表的所有對象的序號,從1開始。比如,將五個對象的列表分為每頁兩個對象,第二頁的[`start_index()`](#django.core.paginator.Page.start_index "django.core.paginator.Page.start_index")會返回`3`。
`Page.``end_index`()[[source]](../_modules/django/core/paginator.html#Page.end_index)
返回當前頁上的最后一個對象,相對于分頁列表的所有對象的序號,從1開始。 比如,將五個對象的列表分為每頁兩個對象,第二頁的[`end_index()`](#django.core.paginator.Page.end_index "django.core.paginator.Page.end_index") 會返回 `4`。
### 屬性
`Page.``object_list`
當前頁上所有對象的列表。
`Page.``number`
當前頁的序號,從1開始。
`Page.``paginator`
相關的[`Paginator`](#django.core.paginator.Paginator "django.core.paginator.Paginator")對象。
> 譯者:[Django 文檔協作翻譯小組](http://python.usyiyi.cn/django/index.html),原文:[Pagination](https://docs.djangoproject.com/en/1.8/topics/pagination/)。
>
> 本文以 [CC BY-NC-SA 3.0](http://creativecommons.org/licenses/by-nc-sa/3.0/cn/) 協議發布,轉載請保留作者署名和文章出處。
>
> [Django 文檔協作翻譯小組](http://python.usyiyi.cn/django/index.html)人手緊缺,有興趣的朋友可以加入我們,完全公益性質。交流群:467338606。
- 新手入門
- 從零開始
- 概覽
- 安裝
- 教程
- 第1部分:模型
- 第2部分:管理站點
- 第3部分:視圖和模板
- 第4部分:表單和通用視圖
- 第5部分:測試
- 第6部分:靜態文件
- 高級教程
- 如何編寫可重用的應用
- 為Django編寫首個補丁
- 模型層
- 模型
- 模型語法
- 元選項
- 模型類
- 查詢集
- 執行查詢
- 查找表達式
- 模型的實例
- 實例方法
- 訪問關聯對象
- 遷移
- 模式編輯器
- 編寫遷移
- 高級
- 管理器
- 原始的SQL查詢
- 聚合
- 多數據庫
- 自定義查找
- 條件表達式
- 數據庫函數
- 其它
- 遺留的數據庫
- 提供初始數據
- 優化數據庫訪問
- 視圖層
- 基礎
- URL配置
- 視圖函數
- 快捷函數
- 裝飾器
- 參考
- 內建的視圖
- TemplateResponse 對象
- 文件上傳
- 概覽
- File 對象
- 儲存API
- 管理文件
- 自定義存儲
- 基于類的視圖
- 概覽
- 內建顯示視圖
- 內建編輯視圖
- API參考
- 分類索引
- 高級
- 生成 CSV
- 生成 PDF
- 中間件
- 概覽
- 內建的中間件類
- 模板層
- 基礎
- 面向設計師
- 語言概覽
- 人性化
- 面向程序員
- 表單
- 基礎
- 概覽
- 表單API
- 內建的Widget
- 高級
- 整合媒體
- 開發過程
- 設置
- 概覽
- 應用程序
- 異常
- 概覽
- django-admin 和 manage.py
- 添加自定義的命令
- 測試
- 介紹
- 部署
- 概述
- WSGI服務器
- 部署靜態文件
- 通過email追蹤代碼錯誤
- Admin
- 管理操作
- 管理文檔生成器
- 安全
- 安全概述
- 說明Django中的安全問題
- 點擊劫持保護
- 加密簽名
- 國際化和本地化
- 概述
- 本地化WEB UI格式化輸入
- “本地特色”
- 常見的網站應用工具
- 認證
- 概覽
- 使用認證系統
- 密碼管理
- 日志
- 分頁
- 會話
- 數據驗證
- 其它核心功能
- 按需內容處理
- 重定向
- 信號
- 系統檢查框架