Django はページ分割されたデータを管理するのに役立ついくつかのクラスを提供しています。これらのクラスは django/core/paginator.py にあります。
例については ページ分割 (Pagination) のトピックガイド を参照してください。
Paginator class¶Paginator（ページネーター）は len() の使用時、または直接イテレートしたときは Page のシーケンスのように動作します。
必須です。リスト、タプル、QuerySet、または count() または __len__() メソッドを持つその他のスライス可能なオブジェクト。一貫したページ分割のためには、QuerySet は順序付けされるべきです。たとえば、order_by() 句を使用するか、モデル上のデフォルトの ordering で行います。
巨大な QuerySet のページ分割によるパフォーマンス上の問題
非常に多数のアイテムを持つ QuerySet を使用した場合、数の大きいページをリクエストしたときに、データベースによっては速度が低下する場合があります。これは、OFFSET 数を数えるために必要な LIMIT/OFFSET クエリの処理時間が、ページ数が増えるにつれて長くなってしまうためです。
Optional. 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. orphans defaults to zero, which means
pages are never combined and the last page may have one item. orphans
should be less than the per_page value.
Deprecated since version 6.0: Support for the orphans argument being larger than or equal to the
per_page argument is deprecated.
Optional. 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.
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
1から始まるインデックスをもつ Page オブジェクトを返します。このオブジェクトは、範囲外のページ数や無効なページ数もハンドリングします。
与えられた値が数字でなかった場合は、最初のページを返します。ページ数が負の数や全体のページ数より大きかった場合は、最後のページを返します。
Paginator(..., allow_empty_first_page=False) を指定し、 object_list が空の場合にのみ EmptyPage 例外を発生させます。
1から始まるインデックスを持つ Page オブジェクトを返します。数値 number が int() を呼び出して整数に変換できない場合、 PageNotAnInteger を発生させます。指定されたページ番号が存在しない場合、 EmptyPage を発生させます。
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 を発生させます。
get_elided_page_range() によって返されるページ範囲において、ページ番号の代わりに使用される翻訳可能な文字列です。デフォルトは '...' です。
AsyncPaginator class¶Asynchronous version of Paginator.
AsyncPaginator has the same attributes and signatures as
Paginator, with the following exceptions:
The attribute Paginator.count is supported as an asynchronous
method AsyncPaginator.acount().
The attribute Paginator.num_pages is supported as an
asynchronous method AsyncPaginator.anum_pages().
The attribute Paginator.page_range is supported as an
asynchronous method AsyncPaginator.apage_range().
AsyncPaginator has asynchronous versions of the same methods as
Paginator, using an a prefix - for example, use
await async_paginator.aget_page(number) rather than
paginator.get_page(number).
Page クラス¶通常は Page オブジェクトを手動で構築することはありません。 Paginator をイテレートするか、 Paginator.page() を使ってオブジェクトを取得します。
1つのページは、len() を使ったり直接イテレーションした時、Page.object_list のシーケンスのように動作します。
次のページ数を返します。次のページが存在しないときは InvalidPage 例外を起こします。
前のページ数を返します。前のページが存在しないときは InvalidPage 例外を起こします。
ページ上の最初のオブジェクトに対する、1から始まるインデックスを返します。これは、ページネータのリストに含まれる全オブジェクトに対するインデックスです。たとえば、5個のオブジェクトのリストを各ページ2オブジェクトでページ分割している場合、2ページ目の start_index() は 3 を返すでしょう。
ページ上の最後のオブジェクトに対する、1から始まるインデックスを返します。これは、ページネータのリストに含まれる全オブジェクトに対するインデックスです。たとえば、5個のオブジェクトのリストを各ページ2オブジェクトでページ分割している場合、2ページ目の end_index() は 4 を返すでしょう。
当該のページに含まれるオブジェクトのリストです。
1から数えた現在のページのページ数です。
AsyncPage class¶Asynchronous version of Page.
AsyncPage has the same attributes and signatures as Page, as
well as asynchronous versions of all the same methods, using an a
prefix - for example, use await async_page.ahas_next() rather than
page.has_next().
AsyncPage has the following additional method:
Returns AsyncPage.object_list as a list. This method must be
awaited before AsyncPage can be treated as a sequence of
AsyncPage.object_list.
Paginator.page() メソッドは、リクエストされたページが無効 (つまり整数ではない) か、オブジェクトが含まれていない場合に例外を発生させます。通常、 InvalidPage 例外をキャッチすれば十分ですが、より詳細に例外をキャッチしたい場合は、以下のいずれかの例外をキャッチします：
どちらの例外も InvalidPage のサブクラスなので、 except InvalidPage で処理できます。
12月 04, 2025