ページ分割 (Paginator)¶
Django はページ分割されたデータを管理するのに役立ついくつかのクラスを提供しています。これらのクラスは django/core/paginator.py にあります。
例については ページ分割 (Pagination) のトピックガイド を参照してください。
Paginator class¶
-
class
Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)¶ Paginator（ページネーター）は
len()の使用時、または直接イテレートしたときはPageのシーケンスのように動作します。
-
Paginator.object_list¶ 必須です。リスト、タプル、
QuerySet、またはcount()または__len__()メソッドを持つその他のスライス可能なオブジェクト。一貫したページ分割のためには、QuerySetは順序付けされるべきです。たとえば、order_by()句を使用するか、モデル上のデフォルトのorderingで行います。巨大な
QuerySetのページ分割によるパフォーマンス上の問題非常に多数のアイテムを持つ
QuerySetを使用した場合、数の大きいページをリクエストしたときに、データベースによっては速度が低下する場合があります。これは、OFFSET数を数えるために必要なLIMIT/OFFSETクエリの処理時間が、ページ数が増えるにつれて長くなってしまうためです。
-
Paginator.orphans¶ オプション。アイテム数が非常に少ない最終ページを作りたくない場合に使用します。もし最後のページに通常
orphans以下の数のアイテムがある場合、それらのアイテムはそれだけで1ページに残すのではなく、前のページ（これが最後のページ）に追加されます。たとえば、23個のアイテムがあり、per_page=10、orphans=3の場合、最初のページには10個のアイテムが表示され、2ページ目（最後のページ）には13個のアイテムが表示されます。orphansのデフォルトは0です。つまり、ページが結合されることはなく、最後のページには1つのアイテムしか表示されないかもしれません。
-
Paginator.allow_empty_first_page¶ オプション。最初のページが空であることを許可するかどうか。 もし
Falseでobject_listが空の場合、EmptyPageエラーが発生します。
-
Paginator.error_messages¶ - New in Django 5.0.
error_messages引数を指定すると、paginator がデフォルトで返すメッセージを上書きできます。オーバーライドしたいエラーメッセージにマッチするキーを持つ辞書を渡します。使用可能なエラーメッセージのキーは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
メソッド¶
-
Paginator.get_page(number)¶ 1から始まるインデックスをもつ
Pageオブジェクトを返します。このオブジェクトは、範囲外のページ数や無効なページ数もハンドリングします。与えられた値が数字でなかった場合は、最初のページを返します。ページ数が負の数や全体のページ数より大きかった場合は、最後のページを返します。
Paginator(..., allow_empty_first_page=False)を指定し、object_listが空の場合にのみEmptyPage例外を発生させます。
-
Paginator.page(number)¶ 1から始まるインデックスを持つ
Pageオブジェクトを返します。数値numberがint()を呼び出して整数に変換できない場合、PageNotAnIntegerを発生させます。指定されたページ番号が存在しない場合、EmptyPageを発生させます。
-
Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)¶ Paginator.page_rangeに似た1から始まるページ番号のリストを返しますが、Paginator.num_pagesが大きい場合は、現在のページ番号のどちらか一方または両方に省略記号を追加します。現在のページ番号の両側に含めるページ数は
on_each_side引数で決まり、デフォルトは3です。ページ範囲の最初と最後に含めるページ数は
on_ends引数で指定します。デフォルトは2です。たとえば、
on_each_sideとon_endsをデフォルトの値で設定した場合、現在のページが10で50ページある場合、ページ範囲は[1, 2, '...', 7, 8, 9, 10, 11, 12, 13, '...', 49, 50]となります。これにより、現在のページの左側に7、8、9ページ、右側に11、12、13ページが、また、最初に1、2ページ、最後に49、50ページが表示されます。指定されたページ番号が存在しない場合は
InvalidPageを発生させます。
属性¶
-
Paginator.ELLIPSIS¶ get_elided_page_range()によって返されるページ範囲において、ページ番号の代わりに使用される翻訳可能な文字列です。デフォルトは'...'です。
-
Paginator.count¶ 全ページにわたるオブジェクトの総数。
注釈
オブジェクトリスト
object_listに含まれるオブジェクトの数を決定する場合、Paginatorはまずobject_list.count()を呼び出します。もしobject_listにcount()メソッドがなければ、Paginatorはlen(object_list)を使用します。これにより、QuerySetなどのオブジェクトは、より効率的なcount()メソッドを使用できます。
-
Paginator.num_pages¶ トータルのページ数
-
Paginator.page_range¶ 1から始まるページ数の範囲のイテレータです。たとえば、
[1, 2, 3, 4]を生成します。
Page クラス¶
通常は Page オブジェクトを手動で構築することはありません。 Paginator をイテレートするか、 Paginator.page() を使ってオブジェクトを取得します。
-
class
Page(object_list, number, paginator)¶ 1つのページは、
len()を使ったり直接イテレーションした時、Page.object_listのシーケンスのように動作します。
メソッド¶
-
Page.has_next()¶ 次のページが存在する時、
Trueを返します。
-
Page.has_previous()¶ 前のページが存在する時、
Trueを返します。
-
Page.has_other_pages()¶ 次のページ または 前のページがある場合、
Trueを返します。
-
Page.next_page_number()¶ 次のページ数を返します。次のページが存在しないときは
InvalidPage例外を起こします。
-
Page.previous_page_number()¶ 前のページ数を返します。前のページが存在しないときは
InvalidPage例外を起こします。
-
Page.start_index()¶ ページ上の最初のオブジェクトに対する、1から始まるインデックスを返します。これは、ページネータのリストに含まれる全オブジェクトに対するインデックスです。たとえば、5個のオブジェクトのリストを各ページ2オブジェクトでページ分割している場合、2ページ目の
start_index()は3を返すでしょう。
-
Page.end_index()¶ ページ上の最後のオブジェクトに対する、1から始まるインデックスを返します。これは、ページネータのリストに含まれる全オブジェクトに対するインデックスです。たとえば、5個のオブジェクトのリストを各ページ2オブジェクトでページ分割している場合、2ページ目の
end_index()は4を返すでしょう。
例外¶
-
exception
InvalidPage¶ pagenator に無効なページ数が渡された時に発生する例外のベースクラスです。
Paginator.page() メソッドは、リクエストされたページが無効 (つまり整数ではない) か、オブジェクトが含まれていない場合に例外を発生させます。通常、 InvalidPage 例外をキャッチすれば十分ですが、より詳細に例外をキャッチしたい場合は、以下のいずれかの例外をキャッチします：
どちらの例外も InvalidPage のサブクラスなので、 except InvalidPage で処理できます。
