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 来处理它们。