分页器 — Django 文档
分页器
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.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.get_page(number)
返回具有给定的基于 1 的索引的 Page 对象，同时还处理超出范围和无效页码。
如果页面不是数字，则返回第一页。 如果页码为负数或大于页数，则返回最后一页。
仅当您指定
Paginator(..., allow_empty_first_page=False)且object_list为空时，才会引发 EmptyPage 异常。
- Paginator.page(number)
- 返回具有给定的基于 1 的索引的 Page 对象。 如果无法通过调用
int()将number转换为整数，则引发 PageNotAnInteger。 如果给定的页码不存在，则引发 InvalidPage。
- Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)
3.2 版中的新功能。
返回一个从 1 开始的页码列表，类似于 Paginator.page_range，但当 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
3.2 版中的新功能。
一个可翻译字符串，用于替代 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)
- 当使用
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 开始的索引，相对于分页器列表中的所有对象。 例如，当用每页 2 个对象对 5 个对象的列表进行分页时，第二页的 start_index() 将返回
3。
- Page.end_index()
- 返回页面上最后一个对象的从 1 开始的索引，相对于分页器列表中的所有对象。 例如，当用每页 2 个对象对 5 个对象的列表进行分页时，第二页的 end_index() 将返回
4。
例外
- exception InvalidPage
- 当分页器传递无效页码时引发异常的基类。
Paginator.page() 如果请求的页面无效（即 不是整数）或不包含任何对象。 通常，捕获 InvalidPage 异常就足够了，但如果您想要更细化，则可以捕获以下任一异常：
- exception PageNotAnInteger
- 当 page() 被赋予一个不是整数的值时引发。
- exception EmptyPage
- 当 page() 被赋予有效值但该页面上不存在对象时引发。
这两个异常都是 InvalidPage 的子类，因此您可以使用 except InvalidPage 处理它们。
