# Django 5.0.9.dev20240806133106 ドキュメント

# ページ分割 (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.``per_page`

  必須です。ページ上に含めるアイテムの最大数で、孤立アイテムは含みません（以下の `orphans` オプション引数を参照）。

`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` を返すでしょう。

### 属性

`Page.``object_list`

  当該のページに含まれるオブジェクトのリストです。

`Page.``number`

  1から数えた現在のページのページ数です。

`Page.``paginator`

  関連する `Paginator` オブジェクトです。

## 例外

exception `InvalidPage`

  pagenator に無効なページ数が渡された時に発生する例外のベースクラスです。

`Paginator.page()` メソッドは、リクエストされたページが無効 (つまり整数ではない) か、オブジェクトが含まれていない場合に例外を発生させます。通常、 `InvalidPage` 例外をキャッチすれば十分ですが、より詳細に例外をキャッチしたい場合は、以下のいずれかの例外をキャッチします：

exception `PageNotAnInteger`

  `page()` に整数でない値が与えられた時に発生します。

exception `EmptyPage`

  `page()` に有効な値が与えられているが、そのページにオブジェクトが存在しない場合に発生します。

どちらの例外も `InvalidPage` のサブクラスなので、 `except InvalidPage` で処理できます。