稳定易用的 Django 分页库，完善分页功能

作者：HelloGitHub-追梦人物[1]

文中所涉及的示例代码，已同步更新到 HelloGitHub-Team 仓库[2] 点击本文最下方的“阅读原文”即可获取

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

分页效果概述

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

• 始终显示第一页和最后一页。
• 当前页码高亮显示。
• 显示当前页码前后几个连续的页码。
• 如果两个页码号间还有其它页码，中间显示省略号以提示用户。

分页思路

如果需要自己来实现分页效果，我们会怎么做呢？先来分析一下导航条的组成部分，可以看到整个分页导航条其实可以分成 7 个部分：

1. 第 1 页页码，这一页需要始终显示。
2. 第 1 页页码后面的省略号部分。但要注意如果第 1 页的页码号后面紧跟着页码号 2，那么省略号就不应该显示。
3. 当前页码的左边部分，比如这里的 3-4。
4. 当前页码，比如这里的 5。
5. 当前页码的右边部分，比如这里的 6-7。
6. 最后一页页码前面的省略号部分。但要注意如果最后一页的页码号前面跟着的页码号是连续的，那么省略号就不应该显示。
7. 最后一页的页码号。

因此我们的思路是，在视图中依据上述规则生成页码列表，然后在模板中循环显示页码列表就可以了。有了思路，实现起来其实也并不很难。不过对于这类常见需求，别人早就帮我们实现好了，本着不重复造轮子的原则，直接拿来用就好。

第一个 Django 第三方拓展：django-pure-pagination

我们第一次开始接触 django 第三方拓展，在此之前我们一直都基于 django 本身我们提供的功能在开发，然而 django 强大的地方就在于海量的第三方应用供我们挑选，几乎大部分 web 开发中的需求，django 都能找到他人已经写好的第三方应用，拿来即用。

事实上，正确的 django 开发姿势应该是这样的：

1. 充分理解你的需求，想一想，如果自己实现，我会怎么做？
2. 通过 Google、GitHub、开发者社区论坛等调研已有的实现类似需求的应用
3. 拿来即用，并尝试理解他人是如何实现这个功能的

以我们的分页功能举例：

首先我们上面分析了分页需求的实现。然后我在 GitHub 上通过 django pagination 关键词进行搜索，在比较了多个 star 数比较高的项目后，发现 django-pure-pagination 文档最清晰，使用最简单，因此决定将这个应用集成到我们的博客来。值得一提的是，尽管这个应用显示作者最后一次更新代码在 4 年前，但我粗略浏览了一下源码，发现其依赖的 django api 4 年来异常稳定，所以确保能在 django 2.2 中使用。

接下来我们就来使用它，首先安装它：

$ pipenv install django-pure-pagination

然后将它注册到 INSTALLED_APPS 里：

INSTALLED_APPS = [
	# ...
    'pure_pagination',  # 分页

    'blog.apps.BlogConfig',  # 注册 blog 应用
    'comments.apps.CommentsConfig',  # 注册 comments 应用
]

修改一下 IndexView，让它继承 django-pure-pagination 提供的 PaginationMixin，这个混入类将为我们提供上述提到的分页功能。

class IndexView(PaginationMixin, ListView):
    model = Post
    template_name = 'blog/index.html'
    context_object_name = 'post_list'
    paginate_by = 10

然后我们可以在 common.py 配置中配置一下分页的效果，这是 django-pure-pagination 提供的配置项，用于个性化配置分页效果：

# django-pure-pagination 分页设置
PAGINATION_SETTINGS = {
    'PAGE_RANGE_DISPLAYED': 4, # 分页条当前页前后应该显示的总页数（两边均匀分布，因此要设置为偶数），
    'MARGIN_PAGES_DISPLAYED': 2, # 分页条开头和结尾显示的页数
    'SHOW_FIRST_PAGE_WHEN_INVALID': True, # 当请求了不存在页，显示第一页
}

在模板中需要分页的地方，调用分页对象的 render 方法就可以了，比如在 index.html 中：

{% if is_paginated %}
	{{ page_obj.render }}
{% endif %}

注意这里 page_obj 是分页后的对象列表，具体请参考上一篇文章的讲解。render 方法会自动帮我们渲染一个预先定义好的分页条，至此，分页功能就完成了。

自定义模板

有时候预定义的分页条并不能满足我们的需求，我们可以通过自定义的模板来覆盖预定义的模板。django 查找模板的顺序是，首先在项目配置的模板根路径寻找（我们项目中配的是 templates 文件夹），没有找到的话，再去应用的 templates 目录下寻找。分页模板预定义的路径为 pure_pagination/pagination.html，所以我们可以在项目模板根路径下建立一个一模一样的文件结构，这样 django 就会首先找到我们的模板，从而应用我们自定义的模板，而不是预定义的模板。

在 templates 目录下新建一个 pure_pagination\ 目录，然后建立一个 pagination.html 文件。

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

<div class="text-center pagination" style="width: 100%">
  <ul>
    {% if page_obj.has_previous %}
      <li><a href="?{{ page_obj.previous_page_number.querystring }}"
             class="prev">&lsaquo;&lsaquo; </a></li>
    {% else %}
      <li><span class="disabled prev">&lsaquo;&lsaquo; </span></li>
    {% endif %}
    {% for page in page_obj.pages %}
      {% if page %}
        {% ifequal page page_obj.number %}
          <li class="current"><a href="#">{{ page }}</a></li>
        {% else %}
          <li><a href="?{{ page.querystring }}" class="page">{{ page }}</a></li>
        {% endifequal %}
      {% else %}
        ...
      {% endif %}
    {% endfor %}
    {% if page_obj.has_next %}
      <li><a href="?{{ page_obj.next_page_number.querystring }}" class="next"> &rsaquo;&rsaquo;</a>
      </li>
    {% else %}
      <li><span class="disabled next"> &rsaquo;&rsaquo;</span></li>
    {% endif %}
  </ul>
</div>

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

参考资料

[1]HelloGitHub-追梦人物: https://www.zmrenwu.com

[2]HelloGitHub-Team 仓库: https://github.com/HelloGitHub-Team/HelloDjango-blog-tutorial

[3]通过 Django Pagination 实现简单分页: https://www.zmrenwu.com/courses/hellodjango-blog-tutorial/materials/81/