分页功能是几乎所有的网站上都需要提供的功能,当你要展示的条目比较多时,必须进行分页,不但能减小数据库读取数据压力,也有利于用户浏览。Django很贴心的为我们提供了一个分页工具Paginator
。
Paginator类位于django.core.paginator
模块。
向Paginator
提供包含分页对象的列表(通常是Queryset),以及你想每一页显示几条,比如每页5条、10条、20条、100条等等,它就会为你提供一系列API方法,示例如下:
>>> from django.core.paginator import Paginator >>> objects = ['john', 'paul', 'george', 'ringo'] >>> p = Paginator(objects, 2) # 对objects进行分页,虽然objects只是个字符串列表,但没关系,一样用。每页显示2条。 >>> p.count # 对象个数 4 >>> p.num_pages # 总共几页 2 >>> type(p.page_range) <class 'range_iterator'> >>> p.page_range # 分页范围 range(1, 3) >>> page1 = p.page(1) # 获取第一页 >>> page1 <Page 1 of 2> >>> page1.object_list # 获取第一页的对象 ['john', 'paul'] >>> page2 = p.page(2) >>> page2.object_list ['george', 'ringo'] >>> page2.has_next() # 判断是否有下一页 False >>> page2.has_previous()# 判断是否有上一页 True >>> page2.has_other_pages() # 判断是否有其它页 True >>> page2.next_page_number() # 获取下一页的页码 Traceback (most recent call last): ... EmptyPage: That page contains no results >>> page2.previous_page_number() # 获取上一页的页码 1 >>> page2.start_index() # 从1开始计数的当前页的第一个对象 3 >>> page2.end_index() # 从1开始计数的当前页最后1个对象 4 >>> p.page(0) # 访问不存在的页面 Traceback (most recent call last): ... EmptyPage: That page number is less than 1 >>> p.page(3) # 访问不存在的页面 Traceback (most recent call last): ... EmptyPage: That page contains no results
简单地说,使用Paginator分四步走:
下面的例子假设你拥有一个Contacts模型。
在函数视图中使用Paginator,参考下面的代码:
from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger from django.shortcuts import render from myapp.models import Contact def listing(request): contact_list = Contacts.objects.all() paginator = Paginator(contact_list, 25) # 每页显示25条 page_number = request.GET.get("page") # 从请求中获取用户希望查看第几页 # 拿到分页后的contacts子集,这时候它被包装成了Paginator的实例,增加了分页相关的属性 page_obj = paginator.get_page(page_number) return render(request, "list.html", {"page_obj": page_obj})
在list.html
模板中,使用下面的范例来展示每个要显示的contact,以及最后的一个分页栏:
{% for obj in page_obj %} {# 每个"obj"都是一个Contact模型对象. #} {{ obj.full_name|upper }}<br /> ... {% endfor %} {# 分页标签的HTML代码 #} <div class="pagination"> <span class="step-links"> {% if page_obj.has_previous %} <a href="?page={{ page_obj.previous_page_number }}">previous</a> {% endif %} <span class="current"> Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}. </span> {% if page_obj.has_next %} <a href="?page={{ page_obj.next_page_number }}">next</a> {% endif %} </span> </div>
对于Django内置的通用列表视图类django.views.generic.list.ListView
,它和paginator结合得比较好,只需要简单的提供一个属性即可,如下所示:
from django.views.generic import ListView from myapp.models import Contact class ContactList(ListView): paginate_by = 2 model = Contact
paginate_by
指示每页显示的对象数量,并同时将page_obj
和paginator
对象添加到context
上下文中,供模板渲染使用。下面是一个典型的模板页面:
{% for contact in page_obj %} {# Each "contact" is a Contact model object. #} {{ contact.full_name|upper }}<br> ... {% endfor %} <div class="pagination"> <span class="step-links"> {% if page_obj.has_previous %} <a href="?page=1">« first</a> <a href="?page={{ page_obj.previous_page_number }}">previous</a> {% endif %} <span class="current"> Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}. </span> {% if page_obj.has_next %} <a href="?page={{ page_obj.next_page_number }}">next</a> <a href="?page={{ page_obj.paginator.num_pages }}">last »</a> {% endif %} </span> </div>
class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)
参数说明:
object_list
是空的,则会出现 EmptyPage 错误。orphans
参数的用途:当你不希望最后一页的项目数量很少时,可以使用这个选项。如果最后一页的条目数量小于或等于 orphans,那么这些条目将被添加到前一页(成为最后一页),而不是让这些条目单独留在一页上。例如,假设有 23 个条目,per_page
=10,orphans
=3,则会有两页;第一页有 10 个条目,第二页(也是最后一页)有 13 个条目。orphans 默认为 0,这意味着页面永远不会合并,最后一页可能只有一个条目。
error_messages
是Django 5.0新增的参数,通过它可以自定义错误信息。它接收一个字典类型的值。字典的键只能是 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类拥有以下主要方法和属性:
方法:
Paginator.page(number)
返回指定页面的对象列表,比如第7页的所有内容,下标以1开始。如果提供的页码不存在,抛出InvalidPage
异常。
Paginator.get_page(number)
上面方法的安全版本,不会弹出异常。如果输入的参数不是数字,返回第一页。如果输入的数字大于最大页码,返回最后一页。
属性:
Paginator.count
:对象总数。Paginator.num_pages
:页面总数。Paginator.page_range
:基于1的页数范围迭代器。比如:[1, 2, 3, 4]要注意区分Paginator对象和Page对象,后者是前者的某一页内容。
Paginator.page(num)
返回一个Page对象,我们主要的操作都是基于Page对象的,它具有下面的方法和属性:
方法:
Page.start_index()
:返回当前页上的第一个对象,相对于分页列表的所有对象的序号,从1开始计数。 比如,将五个对象的列表分为每页两个对象,第二页的start_index()
会返回3。Page.end_index()
:返回当前页上的最后一个对象,相对于分页列表的所有对象的序号,从1开始。 比如,将五个对象的列表分为每页两个对象,第二页的end_index()
会返回4。属性:
Page.paginator
:当前Page对象所属的Paginator对象。在实际使用中,可能恶意也可能不小心,用户请求的页面号码,可能千奇百怪。
正常我们希望是个合法的1,2,3之类的数字,但真实的请求可能是‘apple’、‘1000000’、‘#’之类,这就有可能导致异常,需要特别处理。
Django为我们内置了下面几个Paginator相关的异常。
后面两个异常都是InvalidPage的子类,所以你可以通过简单的except InvalidPage来处理它们。
如果用类视图的话会非常简单,只要在视图那里设置好,然后 template直接引用就行。