{"title":"分页器","version":"4.2","locale":"zh-hans","docname":"ref/paginator","url":"/zh-hans/4.2/ref/paginator/","canonical":"https://djangodocs.dev/zh-hans/4.2/ref/paginator/","summary":"Django 提供了一些类来帮助你管理分页数据 ——也就是说，数据被分割在几个页面上，并带有 “上一页／下一页” 的链接。这些类位于 django/core/paginator.py 中。 有关示例，请参阅 分页主题指南 。 Paginator 类 Link to this heading # class Paginator…","html":"

分页器Link to this heading#

\n

Django 提供了一些类来帮助你管理分页数据 ——也就是说，数据被分割在几个页面上，并带有 “上一页／下一页” 的链接。这些类位于 django/core/paginator.py 中。

\n

有关示例，请参阅 分页主题指南。

\n
\n

Paginator 类Link to this heading#

\n
\n
\nclass Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)Link to this definition#
\n

当使用 len() 或直接迭代时，分页器的作用就像一个 Page 的序列。

\n
\n\n
\n
\nPaginator.object_listLink to this definition#
\n

必要的。一个列表、元组、QuerySet 或其他具有 count() 或 __len__() 方法的可切片对象。为了实现一致的分页，QuerySet 应该是有序的，例如使用 order_by() 子句或使用模型上的默认 ordering。

\n\n
\n\n
\n
\nPaginator.per_pageLink to this definition#
\n

必要的。一个页面中包含的最大项目数，不包括 orphans（参见下面的 orphans 可选参数）。

\n
\n\n
\n
\nPaginator.orphansLink to this definition#
\n

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

\n
\n\n
\n
\nPaginator.allow_empty_first_pageLink to this definition#
\n

可选的。是否允许第一页为空。 如果 False 并且 object_list 是空的，则会出现 EmptyPage 错误。

\n
\n\n
\n

方法Link to this heading#

\n
\n
\nPaginator.get_page(number)Link to this definition#
\n

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

\n

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

\n

只有当你指定了 Paginator(..., allow_empty_first_page=False) 并且 object_list 为空时，才会引发 EmptyPage 异常。

\n
\n\n
\n
\nPaginator.page(number)Link to this definition#
\n

返回一个带有给定的基于 1 的索引的 Page 对象。如果 number 无法通过调用 int() 转换为整数，则引发 PageNotAnInteger。如果给定的页数不存在，则引发 EmptyPage。

\n
\n\n
\n
\nPaginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)Link to this definition#
\n

返回一个基于 1 的页码列表，类似于 Paginator.page_range，但在 Paginator.num_pages 很大时，可能会在当前页码的一侧或两侧添加省略号。

\n

每个当前页码两侧包括的页数由 on_each_side 参数决定，默认为 3。

\n

在页码范围的开头和结尾包括的页数由 on_ends 参数决定，默认为 2。

\n

例如，如果 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。

\n

如果给定的页码不存在，则引发 InvalidPage 异常。

\n
\n\n
\n
\n

属性Link to this heading#

\n
\n
\nPaginator.ELLIPSISLink to this definition#
\n

一个可翻译的字符串，用作 get_elided_page_range() 返回的页面范围中省略的页码的替代物。默认值是 '…'。

\n
\n\n
\n
\nPaginator.countLink to this definition#
\n

所有页面的对象总数。

\n\n
\n\n
\n
\nPaginator.num_pagesLink to this definition#
\n

总页数。

\n
\n\n
\n
\nPaginator.page_rangeLink to this definition#
\n

以 1 为基础的页码范围迭代器，例如产生 [1，2，3，4]。

\n
\n\n
\n
\n
\n

Page 类Link to this heading#

\n

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

\n
\n
\nclass Page(object_list, number, paginator)Link to this definition#
\n

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

\n
\n\n
\n

方法Link to this heading#

\n
\n
\nPage.has_next()Link to this definition#
\n

如果有下一页，返回 True。

\n
\n\n
\n
\nPage.has_previous()Link to this definition#
\n

如果有上一页，返回 True。

\n
\n\n
\n
\nPage.has_other_pages()Link to this definition#
\n

如果有下一页 或 上一页，返回 True。

\n
\n\n
\n
\nPage.next_page_number()Link to this definition#
\n

返回下一页的页码。如果下一页不存在，则引发 InvalidPage。

\n
\n\n
\n
\nPage.previous_page_number()Link to this definition#
\n

返回上一页的页码。如果上一页不存在，则引发 InvalidPage。

\n
\n\n
\n
\nPage.start_index()Link to this definition#
\n

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

\n
\n\n
\n
\nPage.end_index()Link to this definition#
\n

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

\n
\n\n
\n
\n

属性Link to this heading#

\n
\n
\nPage.object_listLink to this definition#
\n

此页上的对象列表。

\n
\n\n
\n
\nPage.numberLink to this definition#
\n

此页的基于 1 的页码。

\n
\n\n
\n
\nPage.paginatorLink to this definition#
\n

关联的 Paginator 对象。

\n
\n\n
\n
\n
\n

异常Link to this heading#

\n
\n
\nexception InvalidPageLink to this definition#
\n

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

\n
\n\n

Paginator.page() 方法在请求的页面无效（即不是整数）或不包含任何对象时引发异常。一般来说，只要捕获 InvalidPage 异常就够了，但如果你想要更细化，你可以捕获以下任何一种异常。

\n
\n
\nexception PageNotAnIntegerLink to this definition#
\n

当 page() 的值不是整数时发生该事件。

\n
\n\n
\n
\nexception EmptyPageLink to this definition#
\n

当 page() 被赋予一个有效的值，但该页面上没有对象存在时，引发该异常。

\n
\n\n

这两个异常都是 InvalidPage 的子类，所以你可以用 except InvalidPage 处理这两个异常。

\n
","rootId":"paginator","toc":[{"title":"Paginator 类","anchor":"paginator-class","children":[{"title":"方法","anchor":"methods","children":[]},{"title":"属性","anchor":"attributes","children":[]}]},{"title":"Page 类","anchor":"page-class","children":[{"title":"方法","anchor":"id1","children":[]},{"title":"属性","anchor":"id2","children":[]}]},{"title":"异常","anchor":"exceptions","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/4.2/ref/"}],"prev":{"docname":"ref/models/database-functions","title":"数据库函数","url":"/zh-hans/4.2/ref/models/database-functions/"},"next":{"docname":"ref/request-response","title":"请求和响应对象","url":"/zh-hans/4.2/ref/request-response/"},"formats":{"html":"/zh-hans/4.2/ref/paginator/","markdown":"/zh-hans/4.2/ref/paginator.md","json":"/zh-hans/4.2/ref/paginator.json"},"source":"https://github.com/django/django/blob/stable/4.2.x/docs/ref/paginator.txt","official":"https://docs.djangoproject.com/zh-hans/4.2/ref/paginator/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}