Paginator 类¶

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

使用 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)[source]¶

使用len()或直接迭代它时，页面就像Page.object_list的序列。

异常¶

exception InvalidPage[source]¶

当分页器传递无效页码时引发的异常的基类。

如果请求的页面无效（即不是整数）或不包含任何对象，则Paginator.page()方法会引发异常。通常，捕获InvalidPage异常就足够了，但如果您需要更细粒度的控制，您可以捕获以下任何异常

exception PageNotAnInteger[source]¶

当page()给定的值不是整数时引发。

exception EmptyPage[source]¶

当page()给定一个有效值，但在该页面上不存在对象时引发。

这两个异常都是InvalidPage的子类，因此您可以使用except InvalidPage来处理它们。