Django-分页
这篇讲什么
- 分页的核心是
Paginator:给它一个可切片的列表和每页条数,它负责按页切片并处理越界。 - 这篇覆盖签名与默认值、一个完整的手工分页视图、页码异常家族、模板里的分页导航,以及
ListView自带的分页。文中特别标出哪些参数是 6.x 才有的——在 5.2.19 上传了会直接报错。
Paginator 的签名与默认值
-
Django 5.2.19 实测:
1
Paginator 签名: (self, object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)
object_list通常是查询集,也可以是任何可切片、能len()的序列。per_page每页条数;orphans是「零头容忍数」;allow_empty_first_page控制空列表是否允许有第 1 页。
-
网上教程里的
max_per_page/error_out_of_range/last_index_unfilled是 6.x 才有的参数,在 5.2 上传了会直接报错,实测:1
2
3Paginator 不接受 max_per_page -> Paginator.__init__() got an unexpected keyword argument 'max_per_page'
Paginator 不接受 error_out_of_range -> ... unexpected keyword argument 'error_out_of_range'
Paginator 不接受 last_index_unfilled -> ... unexpected keyword argument 'last_index_unfilled'
手工分页:一个完整视图
1 | from django.core.paginator import EmptyPage, PageNotAnInteger, Paginator |
-
造 11 条数据后实测各种页码:
请求 实测结果 无 pagecount=11 num_pages=3 page_range=[1,2,3],走PageNotAnInteger回第 1 页,items=5?page=2&size=4number=2,items=4,has_prev/has_next都 True?page=99&size=4走 EmptyPage回最后一页,number=3,items=3?page=abc&size=4走 PageNotAnInteger回第 1 页?page=1&size=4&orphans=3num_pages=2(零头 3 条被并进上一页)?page=3&size=4&orphans=3EmptyPage -> 回最后一页 2,items=7 -
orphans直观理解(实测):1
211 条 / 每页 4:num_pages 3 最后一页条数 3
orphans=3: num_pages 2 最后一页条数 7- 含义是「如果最后一页的条数 ≤ orphans,就不单独成页,并进上一页」。
-
常用属性方法一览:
p.count、p.num_pages、p.page_range、p.get_page(n)(自动兜异常,推荐);page.number、page.object_list、page.has_previous()、page.previous_page_number()、page.has_next()、page.next_page_number()、page.has_other_pages()、page.start_index()/end_index()。
页码异常家族
1 | InvalidPage 家族关系: PageNotAnInteger -> InvalidPage, EmptyPage -> InvalidPage |
PageNotAnInteger(页码不是整数)和EmptyPage(页码越界)都继承InvalidPage。InvalidPage不再是Http404的子类(实测 False),所以别指望它自动变成 404 页面;想返回 404 要自己raise Http404。- 想少写 try/except 就用
p.get_page(raw):它内部把上面两种异常都兜成「第 1 页 / 最后一页」。
模板里的分页导航
1 | <ul> |
-
页码很多时不要一次渲染 200 个链接,自己截一个窗口:
1
2
3
4
5{% for n in paginator.page_range %}
{% if n >= page_obj.number|add:-3 and n <= page_obj.number|add:3 %}
<a href="?page={{ n }}">{{ n }}</a>
{% endif %}
{% endfor %}|add:-3这种负数写法要用add:"-3",直接写add:-3会解析失败。
ListView 自带分页
1 | from django.views.generic.list import ListView |
-
上下文里会多出三个键,实测:
1
2ListView 第一页: 200 t0 t1 t2 t3 |is_paginated=True|page_obj=1|paginator=3|queryset=11
ListView 越界页: 200 t8 t9 t10 |is_paginated=True|page_obj=3|paginator=3|queryset=11-
也就是
is_paginated、page_obj、paginator,数据在object_list里;页码参数固定是?page=。 -
越界页被自动夹到最后一页(
page_obj=3),非数字页码则一路冒到异常处理,实测被中间件的process_exception接住时看到的是:1
process_exception 接住了: Page is not “last”, nor can it be converted to an int.
-
-
不排序就分页会报警,实测原文:
1
2UnorderedObjectListWarning: Pagination may yield inconsistent results with an
unordered object_list: <class 'myapp.models.Article'> QuerySet.- 因为数据库不保证无
ORDER BY时的行序,同一页可能重复或漏数据。给模型加Meta.ordering或在视图里order_by()都能消掉。
- 因为数据库不保证无
关系图

- 老笔记这里写的是
/images/Django/page.png,站点里没有这个路径(图实际在static/img/Django/下),这一版改成正确地址。
新手卡点清单
-
都是实测过的:
卡点 症状 正确做法 查询集不排序 UnorderedObjectListWarning,翻页数据重复/缺失order_by()或Meta.ordering直接 p.page(request.GET["page"])页码为空时 PageNotAnInteger500用 p.get_page(...)或自己兜两个异常以为 InvalidPage会 404实测它不是 Http404子类需要 404 就自己 raise Http404抄 6.x 的 error_out_of_range等参数TypeError: unexpected keyword argument5.2 只有 orphans/allow_empty_first_page/error_messages模板里写 add:-3(负数没引号)过滤器参数解析失败 写成 add:"-3"一次渲染全部 page_range几百个页码链接 用窗口过滤 把 page_range当整数用for里拿到的是页号它是 range(1, num_pages+1)
参考
- Django 分页参考:
Paginator/Page的属性方法与异常。 ListView的分页属性:paginate_by、get_paginated_by。Paginator.get_page:官方推荐的兜异常写法。- Django 6.0 release notes:
max_per_page、error_out_of_range这些新参数的出处(5.2 没有)。