翻页机

Django提供了几个类来帮助您管理分层数据--即分裂在多个页面上并带有“上一个/下一个”链接的数据。这些班级生活在 django/core/paginator.py 。

有关示例，请参见 Pagination topic guide 。

Paginator 班级

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)[源代码]

打码器的作用就像一系列 Page 在使用时 len() 或者直接迭代它。

Paginator.object_list

必需的.一个列表、多元组 QuerySet ，或其他具有 count() 或 __len__() 法为了一致的翻页， QuerySet s应该订购，例如带有 order_by() 条款或具有默认值 ordering 关于模型。

页面大的性能问题 QuerySet S

如果您使用的是 QuerySet with a very large number of items, requesting high page numbers might be slow on some databases, because the resulting 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

这个 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

方法

Paginator.get_page(number)[源代码]

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

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

提出了一个 EmptyPage 仅在您指定时才例外 Paginator(..., allow_empty_first_page=False) 以及 object_list 是空的。

Paginator.page(number)[源代码]

返回一个 Page 具有给定的从1开始的索引的。加薪 PageNotAnInteger 如果 number 无法通过调用 int() 。加薪 EmptyPage 如果给定的页码不存在。

Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=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

一个可翻译字符串，用作由返回的页面范围中省略的页面号的替代品 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)[源代码]

一个页面就像一系列 Page.object_list 在使用时 len() 或者直接迭代它。

方法

Page.has_next()[源代码]

退货 True 如果还有下一页。

Page.has_previous()[源代码]

退货 True 如果有上一页。

Page.has_other_pages()[源代码]

退货 True 如果再有下一 or 上一页。

Page.next_page_number()[源代码]

返回下一页号。提出 InvalidPage 如果下一页面不存在。

Page.previous_page_number()[源代码]

返回上一页号。提出 InvalidPage 如果上一页不存在。

Page.start_index()[源代码]

返回页面上第一个对象相对于页面中所有对象的从1开始的索引。例如，当对包含5个对象的列表进行翻页时，每页有2个对象，第二页的 start_index() 会回来 3 。

Page.end_index()[源代码]

返回页面上最后一个对象的从1开始的索引（相对于页面中的所有对象）。例如，当对包含5个对象的列表进行翻页时，每页有2个对象，第二页的 end_index() 会回来 4 。

属性

Page.object_list

此页面上的对象列表。

Page.number

此页面的每页号，从1开始。

Page.paginator

关联的 Paginator 对象。

例外情况

exception InvalidPage[源代码]

当向页面传递无效的页面号时引发的异常的基本类。

这个 Paginator.page() 如果所请求的页面无效（即不是一个整数）或不包含对象，方法会引发异常。一般来说，抓到就足够了 InvalidPage 异常，但如果您想要更多的粒度，您可以捕获以下异常之一：

exception PageNotAnInteger[源代码]

时引发 page() 被赋予一个不是整值的值。

exception EmptyPage[源代码]

时引发 page() 被赋予有效值，但该页面上不存在对象。

这两个例外都是 InvalidPage ，所以您可以用它们来处理它们 except InvalidPage 。

« previous | up | next »