15.Django Pagination 简单分页

Posted 2021-05-01 Python编程学习

当博客上发布的文章越来越多时，通常需要进行分页显示，以免所有的文章都堆积在一个页面，影响用户体验。Django 内置的 Pagination 能够帮助我们实现简单的分页功能。

Paginator 类的常用方法

分页功能由 Django 内置的 Paginator 类提供。这个类位于 django/core/paginator.py，需要使用它时，只需在适当的地方导入这个类即可。下面的代码摘自 Django 的官方文档中 Pagination 的示例。

from django.core.paginator import Paginator

只需实例化一个 Paginator 对象，并在实例化时传入一个需要分页的列表对象，就可以得到分页后的对象数据。

# 对 item_list 进行分页，每页包含 2 个数据。>>> item_list = ['john', 'paul', 'george', 'ringo']>>> p = Paginator(item_list, 2)

取特定页的数据：

# 取第 2 页的数据>>> page2 = p.page(2)>>> page2.object_list['george', 'ringo']

查询特定页的当前页码数：

>>> page2.number2

查看分页后的总页数：

>>> p.num_pages2

查看某一页是否还有上一页，以及查询该页上一页的页码：

# 查询第二页是否还有上一页>>> page2.has_previous()True# 查询第二页上一页的页码>>> page2.previous_page_number()1

查看某一页是否还有下一页，以及查询该页下一页的页码：

# 查询第二页是否还有下一页>>> page2.has_next()False# 查询第二页下一页的页码>>> page2.next_page_number()django.core.paginator.EmptyPage: That page contains no results

更多方法和属性请参阅 Django Pagination 的官方文档。

用 Paginator 给文章列表分页

使用上面的一些方法，我们可以实现一个类似于 Django 官方博客一样的简单分页效果，效果如下。

这里，Django 的官方文档中给出了一个在视图函数中对列表进行分页的示例，这个视图函数获取一个联系人列表并对其分页：

from django.core.paginator import Paginator, EmptyPage, PageNotAnIntegerfrom django.shortcuts import renderdef listing(request):
    contact_list = Contacts.objects.all()
    paginator = Paginator(contact_list, 25) # 每页显示 25 个联系人

    page = request.GET.get('page')
    try:
        contacts = paginator.page(page)
    except PageNotAnInteger:
        # 如果用户请求的页码号不是整数，显示第一页
        contacts = paginator.page(1)
    except EmptyPage:
        # 如果用户请求的页码号超过了最大页码号，显示最后一页
        contacts = paginator.page(paginator.num_pages)

    return render(request, 'list.html', {'contacts': contacts})

这就是在视图函数中使用分页的代码逻辑，你可以把它当做一个模板应用于自己的任何需要分页的视图函数。不过在我们的博客项目中，我们不必写这些代码了。回顾在 基于类的通用视图：ListView 和 DetailView 中的内容，我们已将视图函数转换成了类视图。而类视图 ListView 已经帮我们写好了上述的分页逻辑，我们只需通过指定 paginate_by属性来开启分页功能即可，即在类视图中指定 paginate_by 属性的值：

blog/views.pyclass IndexView(ListView):
    model = Post
    template_name = 'blog/index.html'
    context_object_name = 'post_list'
    # 指定 paginate_by 属性后开启分页功能，其值代表每一页包含多少篇文章
    paginate_by = 10

这里我们设置了每 10 篇文章一页，当然你的测试数据可能不够。为了看到分页效果，你可以把这个数值减小。这样首页的文章列表就已经分好页了。

在模板中设置分页导航

接下来便是在模板中设置分页导航，比如上一页、下一页的按钮，以及显示一些页面信息。我们这里设置和 Django 官方博客那样的分页导航样式（具体的样式见上图）。ListView 传递了以下和分页有关的模板变量供我们在模板中使用：

• paginator ，即 Paginator 的实例。

• page_obj ，当前请求页面分页对象。

• is_paginated，是否已分页。只有当分页后页面超过两页时才算已分页。

• object_list，请求页面的对象列表，和 post_list 等价。所以在模板中循环文章列表时可以选 post_list ，也可以选 object_list。

模板中使用示例：

templates/blog/index.html

{% if is_paginated %}<div class="pagination-simple">
  <!-- 如果当前页还有上一页，显示一个上一页的按钮 -->
  {% if page_obj.has_previous %}    <a href="?page={{ page_obj.previous_page_number }}">上一页</a>
  {% endif %}  <!-- 显示当前页面信息 -->
  <span class="current">第 {{ page_obj.number }} 页 / 共 {{ paginator.num_pages }} 页</span>
  <!-- 如果当前页还有下一页，显示一个下一页的按钮 -->
  {% if page_obj.has_next %}    <a href="?page={{ page_obj.next_page_number }}">下一页</a>
  {% endif %}</div>{% endif %}

其中 {{ }} 模板变量中的内容，其含义已在文章开头部分的Paginator 类的常用方法中已有介绍。最终我们得到如下的分页效果：

当然这只是一个简单示例，分页导航处的视觉效果并不是很好看，你可以自行为其添加 CSS 样式使其看上去更加美观。

进一步拓展

使用 Django 内置的 Pagination 只能实现上面的简单分页效果，但通常更加高级的分页效果应该像下图这样：

当前页面高亮显示，且显示当前页面前后几页的页码，始终显示第一页和最后一页的页码，中间可能还有省略号的效果，表示还有未显示的页码。

仅仅使用 Django Pagination 内置的方法无法实现这样的效果，需要我们写一些额外的代码来拓展 Pagination 的功能。接下来我们将详细说明该如何拓展 Pagination 以实现一个完善的分页效果。

在上面，我们实现了一个简单的分页导航效果。但效果有点差强人意，我们只能点上一页和下一页的按钮进行翻页。比较完善的分页效果应该像下面这样，但想实现这样一种效果，Django Pagination 内置的 API 已无能为力。本文将通过拓展 Django Pagination 来实现下图这样比较完善的分页效果。

分页效果概述

一个比较完善的分页效果应该具有以下特性，就像上图展示的那样，很多网站都采用了类似这种的分页导航方式。

• 始终显示第一页和最后一页。

• 当前页码高亮显示。

• 显示当前页码前后几个连续的页码。

• 如果两个页码号间还有其它页码，中间显示省略号以提示用户。

拓展 Pagination

在此之前，我们已将首页文章列表的视图函数转为了类视图，并且使用了类视图 ListView 中已经为我们写好的分页代码来达到分页的目的（详情请查看文章开头处给出的链接）。为了实现如下所展示的分页效果，接下来就需要在 ListView 的基础上进一步拓展分页的逻辑代码。

先来分析一下导航条的组成部分，可以看到整个分页导航条其实可以分成 七个部分：

1. 第 1 页页码，这一页需要始终显示。

2. 第 1 页页码后面的省略号部分。但要注意如果第 1 页的页码号后面紧跟着页码号 2，那么省略号就不应该显示。

3. 当前页码的左边部分，比如这里的 3-6。

4. 当前页码，比如这里的 7。

5. 当前页码的右边部分，比如这里的 8-11。

6. 最后一页页码前面的省略号部分。但要注意如果最后一页的页码号前面跟着的页码号是连续的，那么省略号就不应该显示。

7. 最后一页的页码号。

因此我们的思路是，在视图里将以上七步中所需要的数据生成，然后传递给模板并在模板中渲染显示即可。整个视图的代码如下，由于代码比较长，所以代码实现的功能直接在代码块中注释，就不在文章中进一步说明了。推荐使用大屏幕阅读器获取更好的阅读体验。

blog/views.pyclass IndexView(ListView):
    model = Post
    template_name = 'blog/index.html'
    context_object_name = 'post_list'
    paginate_by = 10

    def get_context_data(self, **kwargs):
        """        在视图函数中将模板变量传递给模板是通过给 render 函数的 context 参数传递一个字典实现的，        例如 render(request, 'blog/index.html', context={'post_list': post_list})，        这里传递了一个 {'post_list': post_list} 字典给模板。        在类视图中，这个需要传递的模板变量字典是通过 get_context_data 获得的，        所以我们复写该方法，以便我们能够自己再插入一些我们自定义的模板变量进去。        """

        # 首先获得父类生成的传递给模板的字典。
        context = super().get_context_data(**kwargs)

        # 父类生成的字典中已有 paginator、page_obj、is_paginated 这三个模板变量，
        # paginator 是 Paginator 的一个实例，
        # page_obj 是 Page 的一个实例，
        # is_paginated 是一个布尔变量，用于指示是否已分页。
        # 例如如果规定每页 10 个数据，而本身只有 5 个数据，其实就用不着分页，此时 is_paginated=False。
        # 关于什么是 Paginator，Page 类在 Django Pagination 简单分页：http://zmrenwu.com/post/34/ 中已有详细说明。
        # 由于 context 是一个字典，所以调用 get 方法从中取出某个键对应的值。
        paginator = context.get('paginator')
        page = context.get('page_obj')
        is_paginated = context.get('is_paginated')

        # 调用自己写的 pagination_data 方法获得显示分页导航条需要的数据，见下方。
        pagination_data = self.pagination_data(paginator, page, is_paginated)

        # 将分页导航条的模板变量更新到 context 中，注意 pagination_data 方法返回的也是一个字典。
        context.update(pagination_data)

        # 将更新后的 context 返回，以便 ListView 使用这个字典中的模板变量去渲染模板。
        # 注意此时 context 字典中已有了显示分页导航条所需的数据。
        return context

    def pagination_data(self, paginator, page, is_paginated):
        if not is_paginated:
            # 如果没有分页，则无需显示分页导航条，不用任何分页导航条的数据，因此返回一个空的字典
            return {}

        # 当前页左边连续的页码号，初始值为空
        left = []

        # 当前页右边连续的页码号，初始值为空
        right = []

        # 标示第 1 页页码后是否需要显示省略号
        left_has_more = False

        # 标示最后一页页码前是否需要显示省略号
        right_has_more = False

        # 标示是否需要显示第 1 页的页码号。
        # 因为如果当前页左边的连续页码号中已经含有第 1 页的页码号，此时就无需再显示第 1 页的页码号，
        # 其它情况下第一页的页码是始终需要显示的。
        # 初始值为 False
        first = False

        # 标示是否需要显示最后一页的页码号。
        # 需要此指示变量的理由和上面相同。
        last = False

        # 获得用户当前请求的页码号
        page_number = page.number

        # 获得分页后的总页数
        total_pages = paginator.num_pages

        # 获得整个分页页码列表，比如分了四页，那么就是 [1, 2, 3, 4]
        page_range = paginator.page_range

        if page_number == 1:
            # 如果用户请求的是第一页的数据，那么当前页左边的不需要数据，因此 left=[]（已默认为空）。
            # 此时只要获取当前页右边的连续页码号，
            # 比如分页页码列表是 [1, 2, 3, 4]，那么获取的就是 right = [2, 3]。
            # 注意这里只获取了当前页码后连续两个页码，你可以更改这个数字以获取更多页码。
            right = page_range[page_number:page_number + 2]

            # 如果最右边的页码号比最后一页的页码号减去 1 还要小，
            # 说明最右边的页码号和最后一页的页码号之间还有其它页码，因此需要显示省略号，通过 right_has_more 来指示。
            if right[-1] < total_pages - 1:
                right_has_more = True

            # 如果最右边的页码号比最后一页的页码号小，说明当前页右边的连续页码号中不包含最后一页的页码
            # 所以需要显示最后一页的页码号，通过 last 来指示
            if right[-1] < total_pages:
                last = True

        elif page_number == total_pages:
            # 如果用户请求的是最后一页的数据，那么当前页右边就不需要数据，因此 right=[]（已默认为空），
            # 此时只要获取当前页左边的连续页码号。
            # 比如分页页码列表是 [1, 2, 3, 4]，那么获取的就是 left = [2, 3]
            # 这里只获取了当前页码后连续两个页码，你可以更改这个数字以获取更多页码。
            left = page_range[(page_number - 3) if (page_number - 3) > 0 else 0:page_number - 1]

            # 如果最左边的页码号比第 2 页页码号还大，
            # 说明最左边的页码号和第 1 页的页码号之间还有其它页码，因此需要显示省略号，通过 left_has_more 来指示。
            if left[0] > 2:
                left_has_more = True

            # 如果最左边的页码号比第 1 页的页码号大，说明当前页左边的连续页码号中不包含第一页的页码，
            # 所以需要显示第一页的页码号，通过 first 来指示
            if left[0] > 1:
                first = True
        else:
            # 用户请求的既不是最后一页，也不是第 1 页，则需要获取当前页左右两边的连续页码号，
            # 这里只获取了当前页码前后连续两个页码，你可以更改这个数字以获取更多页码。
            left = page_range[(page_number - 3) if (page_number - 3) > 0 else 0:page_number - 1]
            right = page_range[page_number:page_number + 2]

            # 是否需要显示最后一页和最后一页前的省略号
            if right[-1] < total_pages - 1:
                right_has_more = True
            if right[-1] < total_pages:
                last = True

            # 是否需要显示第 1 页和第 1 页后的省略号
            if left[0] > 2:
                left_has_more = True
            if left[0] > 1:
                first = True

        data = {
            'left': left,
            'right': right,
            'left_has_more': left_has_more,
            'right_has_more': right_has_more,
            'first': first,
            'last': last,
        }

        return data

模板中设置分页导航

接下来便是在模板中设置分页导航了，将导航条的七个部分的数据一一展现即可，示例代码如下：

{% if is_paginated %}<div class="pagination">
  {% if first %}    <a href="?page=1">1</a>
  {% endif %}
  {% if left %}
    {% if left_has_more %}        <span>...</span>
    {% endif %}
    {% for i in left %}        <a href="?page={{ i }}">{{ i }}</a>
    {% endfor %}
  {% endif %}  <a href="?page={{ page_obj.number }}" style="color: red">{{ page_obj.number }}</a>
  {% if right %}
    {% for i in right %}        <a href="?page={{ i }}">{{ i }}</a>
    {% endfor %}
    {% if right_has_more %}        <span>...</span>
    {% endif %}
  {% endif %}
  {% if last %}    <a href="?page={{ paginator.num_pages }}">{{ paginator.num_pages }}</a>
  {% endif %}</div>{% endif %}

多添加几篇文章，在示例中就可以看到分页效果了。要使分页导航更加美观，通过设置其 CSS 样式即可：