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
    3
    Paginator 不接受 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'

手工分页:一个完整视图

myapp/views.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from django.core.paginator import EmptyPage, PageNotAnInteger, Paginator
from django.http import JsonResponse

from myapp.models import Article


def pager(request):
page_size = int(request.GET.get("size", 5))
orphans = int(request.GET.get("orphans", 0))
arts = Article.objects.order_by("pk") # 一定要排序,否则结果不稳定
p = Paginator(arts, page_size, orphans=orphans)

raw = request.GET.get("page")
try:
page = p.page(raw)
except PageNotAnInteger:
page = p.page(1) # 页码不是数字 -> 回第 1 页
except EmptyPage:
page = p.page(p.num_pages) # 页码越界 -> 回最后一页
return JsonResponse({
"count": p.count, "num_pages": p.num_pages, "page_range": list(p.page_range),
"number": page.number, "items": len(page.object_list),
"has_prev": page.has_previous(), "has_next": page.has_next(),
})
  • 造 11 条数据后实测各种页码:

    请求 实测结果
    无 page count=11 num_pages=3 page_range=[1,2,3],走 PageNotAnInteger 回第 1 页,items=5
    ?page=2&size=4 number=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=3 num_pages=2(零头 3 条被并进上一页)
    ?page=3&size=4&orphans=3 EmptyPage -> 回最后一页 2,items=7
  • orphans 直观理解(实测):

    1
    2
    11 条 / 每页 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
2
3
InvalidPage 家族关系: PageNotAnInteger -> InvalidPage, EmptyPage -> InvalidPage
InvalidPage 是 Exception 子类: True
InvalidPage 是 Http404 的子类: False
  • PageNotAnInteger(页码不是整数)和 EmptyPage(页码越界)都继承 InvalidPage。
  • InvalidPage 不再是 Http404 的子类(实测 False),所以别指望它自动变成 404 页面;想返回 404 要自己 raise Http404。
  • 想少写 try/except 就用 p.get_page(raw):它内部把上面两种异常都兜成「第 1 页 / 最后一页」。

模板里的分页导航

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<ul>
{% for o in page_obj.object_list %}
<li>{{ o.title }}</li>
{% empty %}
<li>没有数据</li>
{% endfor %}
</ul>

<div class="pager">
{% if page_obj.has_previous %}
<a href="?page={{ page_obj.previous_page_number }}">上一页</a>
{% endif %}

<span>第 {{ page_obj.number }} / {{ paginator.num_pages }} 页</span>

{% for n in paginator.page_range %}
{% if n == page_obj.number %}
<b>{{ n }}</b>
{% else %}
<a href="?page={{ n }}">{{ n }}</a>
{% endif %}
{% endfor %}

{% if page_obj.has_next %}
<a href="?page={{ page_obj.next_page_number }}">下一页</a>
{% endif %}
</div>
  • 页码很多时不要一次渲染 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 自带分页

urls.py
1
2
3
4
5
6
7
8
from django.views.generic.list import ListView

from myapp.models import Article

urlpatterns = [
path("lv/", ListView.as_view(model=Article, paginate_by=4,
template_name="myapp/lv.html")),
]
  • 上下文里会多出三个键,实测:

    1
    2
    ListView 第一页: 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
    2
    UnorderedObjectListWarning: 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"]) 页码为空时 PageNotAnInteger 500 用 p.get_page(...) 或自己兜两个异常
    以为 InvalidPage 会 404 实测它不是 Http404 子类 需要 404 就自己 raise Http404
    抄 6.x 的 error_out_of_range 等参数 TypeError: unexpected keyword argument 5.2 只有 orphans / allow_empty_first_page / error_messages
    模板里写 add:-3(负数没引号) 过滤器参数解析失败 写成 add:"-3"
    一次渲染全部 page_range 几百个页码链接 用窗口过滤
    把 page_range 当整数用 for 里拿到的是页号 它是 range(1, num_pages+1)

参考

本文结束 感谢您的阅读
正在加载今日诗词....