分页器

Django 提供了一些类来帮助您管理分页数据——也就是说，数据被分成多个页面，带有“上一页/下一页”链接。这些类位于 :source:`django/core/paginator.py`。

Paginator 类

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True): 当使用 len() 或直接对其进行迭代时，分页器的作用类似于 Page 的序列。

3.1 版更改：添加了对迭代 Paginator 的支持。

Paginator.object_list: 必需的。列表、元组、QuerySet 或其他具有 count() 或 __len__() 方法的可切片对象。为了一致的分页，应该订购 QuerySets，例如使用 order_by() 子句或模型上的默认 ordering。

分页大 QuerySet 的性能问题

如果您使用包含大量项目的 QuerySet，则在某些数据库上请求高页码可能会很慢，因为生成的 LIMIT/OFFSET 查询需要计算 OFFSET 记录的数量，随着页码变高，这需要更长的时间。

Paginator.orphans: 可选的。当您不希望最后一页的项目很少时，请使用此选项。如果最后一页的项目数通常小于或等于 orphans，那么这些项目将被添加到上一页（成为最后一页），而不是将这些项目单独留在页面上. 例如，有23个条目，per_page=10和orphans=3，就会有两个页面；第一页有 10 个项目，第二页（也是最后一个）有 13 个项目。 orphans 默认为零，这意味着页面永远不会合并，最后一页可能有一个项目。

Paginator.allow_empty_first_page: 可选的。是否允许第一页为空。如果 False 和 object_list 为空，则会引发 EmptyPage 错误。

Paginator.get_page(number)

返回具有给定的基于 1 的索引的 Page 对象，同时还处理超出范围和无效页码。

如果页面不是数字，则返回第一页。如果页码为负数或大于页数，则返回最后一页。

仅当您指定 Paginator(..., allow_empty_first_page=False) 且 object_list 为空时，才会引发 EmptyPage 异常。

Paginator.page(number): 返回具有给定的基于 1 的索引的 Page 对象。如果给定的页码不存在，则引发 InvalidPage。

Paginator.count: 跨所有页面的对象总数。

笔记

在确定 object_list 中包含的对象数量时，Paginator 将首先尝试调用 object_list.count()。如果 object_list 没有 count() 方法，那么 Paginator 将回退到使用 len(object_list)。这允许对象（例如 QuerySet）在可用时使用更有效的 count() 方法。

您通常不会手动构建 Page 对象——您将通过迭代 Paginator 或使用 Paginator.page() 来获得它们。

class Page(object_list, number, paginator): 当使用 len() 或直接对其进行迭代时，页面的作用类似于 Page.object_list 的序列。

Page.start_index(): 返回页面上第一个对象的从 1 开始的索引，相对于分页器列表中的所有对象。例如，当用每页 2 个对象对 5 个对象的列表进行分页时，第二页的 start_index() 将返回 3。

Page.end_index(): 返回页面上最后一个对象的从 1 开始的索引，相对于分页器列表中的所有对象。例如，当用每页 2 个对象对 5 个对象的列表进行分页时，第二页的 end_index() 将返回 4。

Paginator.page() 如果请求的页面无效（即不是整数）或不包含任何对象。通常，捕获 InvalidPage 异常就足够了，但如果您想要更细化，则可以捕获以下任一异常：

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