Paginator 類別¶

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)[原始碼]¶

當使用 len() 或直接迭代時，分頁器的作用類似於 Page 的序列。

Paginator.object_list¶

必要。 列表、元組、QuerySet 或其他具有 count() 或 __len__() 方法的可切片物件。為了保持分頁的一致性，QuerySet 應進行排序，例如使用 order_by() 子句或模型上的預設 ordering。

對大型 QuerySet 進行分頁的效能問題

如果您使用的 QuerySet 具有大量的項目，在某些資料庫上要求較高的頁碼可能會很慢，因為產生的 LIMIT/OFFSET 查詢需要計算 OFFSET 記錄的數量，而這會隨著頁碼的增加而需要更長的時間。

Paginator.per_page¶

必要。每個頁面要包含的最大項目數，不包括孤立項目（請參閱下方的 orphans 可選參數）。

Paginator.orphans¶

選用。當您不希望最後一頁只有非常少的項目時，請使用此參數。如果最後一頁的項目數通常小於或等於 orphans，則這些項目將被添加到前一頁（成為最後一頁），而不是將這些項目單獨留在一個頁面上。例如，如果有 23 個項目，per_page=10 和 orphans=3，則會有兩頁；第一頁有 10 個項目，第二頁（也是最後一頁）有 13 個項目。orphans 預設為零，表示頁面永遠不會合併，並且最後一頁可能只有一個項目。

Paginator.allow_empty_first_page¶

選用。是否允許第一頁為空。如果 False 且 object_list 為空，則會引發 EmptyPage 錯誤。

Paginator.error_messages¶

Django 5.0 的新功能。

error_messages 參數讓您可以覆寫分頁器會引發的預設訊息。傳入一個字典，其鍵與您要覆寫的錯誤訊息相符。可用的錯誤訊息鍵為：invalid_page、min_page 和 no_results。

例如，這是預設的錯誤訊息

>>> from django.core.paginator import Paginator
>>> paginator = Paginator([1, 2, 3], 2)
>>> paginator.page(5)
Traceback (most recent call last):
  ...
EmptyPage: That page contains no results

這是自訂的錯誤訊息

>>> paginator = Paginator(
...     [1, 2, 3],
...     2,
...     error_messages={"no_results": "Page does not exist"},
... )
>>> paginator.page(5)
Traceback (most recent call last):
  ...
EmptyPage: Page does not exist

Page 類別¶

您通常不會手動建構 Page 物件 – 您會透過迭代 Paginator 或使用 Paginator.page() 來取得它們。

class Page(object_list, number, paginator)[原始碼]¶

在使用 len() 或直接迭代時，頁面會像 Page.object_list 的序列一樣運作。

例外¶

exception InvalidPage[原始碼]¶

當分頁器接收到無效的頁碼時引發的異常的基底類別。

如果請求的頁面無效（即不是整數）或不包含任何物件，則 Paginator.page() 方法會引發例外。一般而言，捕獲 InvalidPage 異常就足夠了，但是如果您想要更精細的控制，您可以捕獲以下任一異常

exception PageNotAnInteger[原始碼]¶

當 page() 被賦予非整數的值時引發。

exception EmptyPage[原始碼]¶

當 page() 被賦予有效的值，但該頁面上不存在任何物件時引發。

這兩個例外都是 InvalidPage 的子類別，因此您可以使用 except InvalidPage 來處理它們。