摘要：本教程內(nèi)容已過時(shí)，更新版教程請(qǐng)?jiān)L問博客開發(fā)入門教程。當(dāng)分頁(yè)較多時(shí)，總是顯示當(dāng)前頁(yè)及其前幾頁(yè)和后幾頁(yè)的頁(yè)碼教程中使用的是兩頁(yè)，其他頁(yè)碼用省略號(hào)代替。

本教程內(nèi)容已過時(shí)，更新版教程請(qǐng)?jiān)L問： django 博客開發(fā)入門教程。

摘要：前兩期教程我們實(shí)現(xiàn)了博客的 Model 部分，以及 Blog 的首頁(yè)視圖 IndexView，詳情頁(yè)面 DetailView，以及分類頁(yè)面 CategoryView，前兩期教程鏈接請(qǐng)戳：
Django 學(xué)習(xí)小組：博客開發(fā)實(shí)戰(zhàn)第一周教程 —— 編寫博客的 Model 與首頁(yè)面
Django 學(xué)習(xí)小組：博客開發(fā)實(shí)戰(zhàn)第二周教程 —— 博客詳情頁(yè)面和分類頁(yè)面

本周我們將繼續(xù)完善我們的個(gè)人博客，來實(shí)現(xiàn)分頁(yè)和代碼高亮的功能。

提示：在閱讀教程的過程中，如有任何問題請(qǐng)?jiān)L問我們項(xiàng)目的 GithHub 或評(píng)論留言以獲取幫助，本教程的相關(guān)代碼已全部上傳在 Github。如果你對(duì)我們的教程或者項(xiàng)目有任何改進(jìn)建議，請(qǐng)您隨時(shí)告知我們。更多交流請(qǐng)加入我們的郵件列表[email protected] 和關(guān)注我們?cè)?Github 上的項(xiàng)目。

本文首發(fā)于編程派微信公眾號(hào)：編程派（微信號(hào)：codingpy）是一個(gè)專注Python編程的公眾號(hào)，每天更新有關(guān)Python的國(guó)外教程和優(yōu)質(zhì)書籍等精選干貨，歡迎關(guān)注。

我們的數(shù)據(jù)庫(kù)中會(huì)有越來越多的文章，把它們?nèi)坑靡粋€(gè)列表顯示在首頁(yè)好像不太合適，如果顯示一定數(shù)量的文章，比如8篇，這就需要用到分頁(yè)功能。
Django提供了一些類來幫助你管理分頁(yè)的數(shù)據(jù) -- 也就是說，數(shù)據(jù)被分在不同頁(yè)面中，并帶有“上一頁(yè)/下一頁(yè)”標(biāo)簽。這些類位于django/core/paginator.py中。

文章過多，為了提高用戶體驗(yàn)，一次只展示部分文章，為用戶提供一個(gè)分頁(yè)功能，就像下面這樣：

比較完善的分頁(yè)效果，應(yīng)該是這樣的：

用戶在哪一頁(yè)，則當(dāng)前頁(yè)號(hào)高亮以提示用戶所在位置，比如上圖顯示用戶正處在第二頁(yè)。

當(dāng)用戶所處的位置還有上一頁(yè)時(shí)，顯示上一頁(yè)按鈕；當(dāng)還有下一頁(yè)時(shí)，顯示下一頁(yè)按鈕，否則不顯示。

當(dāng)分頁(yè)較多時(shí)，總是顯示當(dāng)前頁(yè)及其前幾頁(yè)和后幾頁(yè)的頁(yè)碼（教程中使用的是兩頁(yè)），其他頁(yè)碼用省略號(hào)代替。

總是顯示第一頁(yè)和最后一頁(yè)的頁(yè)碼。

根據(jù)上面的需求，我們開始編寫相應(yīng)代碼。

關(guān)于分頁(yè)需要使用到的的 API ，Django 官方文檔對(duì)此有十分詳細(xì)的介紹，它還給出了一個(gè)完整示例，讀懂它的代碼后仿照它即可實(shí)現(xiàn)基本的分頁(yè)功能。請(qǐng)參考官方文檔對(duì)于分頁(yè)的示例，如果你不習(xí)慣英文的話，也可以參照網(wǎng)友的翻譯版本Django 中文文檔：分頁(yè)。下面就根據(jù)官方的示例來實(shí)現(xiàn)我們的需求。

盡管可以把分頁(yè)邏輯直接寫在視圖內(nèi)，但是為了通用性，我們使用一點(diǎn)點(diǎn) Django 更加高級(jí)的技巧——模板標(biāo)簽（TemplateTags）。分頁(yè)功能的實(shí)現(xiàn)有很多第三方 APP 可以直接使用，但是為了學(xué)習(xí) Django 的知識(shí)，所以我們自己實(shí)現(xiàn)一個(gè)。這些第三方 APP 基本都是使用的模板標(biāo)簽，因此這可能是一種比較好的實(shí)踐。

為了使用模板標(biāo)簽，Django 要求我們先建立一個(gè) templatetags 文件夾，并在里面加上 __init__.py文件以指示 python 這是一個(gè)模塊（python 把含有該問價(jià)的文件夾當(dāng)做一個(gè)模塊，具體請(qǐng)參考任何一個(gè)關(guān)于 python 模塊的教程）。并且 templatetags 文件夾和你的 model.py，views.py 文件是同級(jí)的，也就是說你的目錄結(jié)構(gòu)看起來應(yīng)該是這樣：

polls/
    __init__.py
    models.py
    templatetags/
        __init__.py
        poll_extras.py
    views.py

（這個(gè)目錄結(jié)構(gòu)引自官方文檔，關(guān)于詳細(xì)的模板標(biāo)簽的介紹請(qǐng)參考官方文檔：custom template tags，不一定全部讀懂，但還是推薦花幾十分鐘掃一遍明白其大致說了什么）。

在 templatetags 目錄下建立一個(gè) paginate_tags .py 文件，準(zhǔn)備工作做完，結(jié)合 Django 的模板系統(tǒng)，我們來看看該如何編寫我們的程序。

首先來回顧一下 Django 的模板系統(tǒng)是如何工作的，回想一下視圖函數(shù)的工作流程，視圖函數(shù)接收一個(gè) Http 請(qǐng)求，經(jīng)過一系列處理，通常情況下其會(huì)渲染某個(gè)模板文件，把模板文件中的一些用 {{ }} 包裹的變量替換成從該視圖函數(shù)中相應(yīng)變量的值。事實(shí)上在此過程中 Django 悄悄幫我們做了一些事情，它把視圖函數(shù)中的變量的值封裝在了一個(gè) Context （一般翻譯成上下文）對(duì)象中，只要模板文件中的變量在 Context 中有對(duì)應(yīng)的值，它就會(huì)被相應(yīng)的值替換。因此，我們的程序可以這樣做：首先把取到的文章列表（官方術(shù)語是一個(gè) queryset）分頁(yè)，用戶請(qǐng)求第幾頁(yè)，我們就把第幾頁(yè)的文章列表傳遞給模板文件；另外還要根據(jù)上面的需求傳遞頁(yè)碼值給模板文件，這樣只要把模板文件中的變量替換成我們傳遞過去的值，那么就達(dá)到本文開篇處那樣的分頁(yè)顯示效果了。

開始編寫我們的代碼了，慣例依然是先看代碼，然后我們?cè)僦鹦薪忉專?/p>

paginate_tags.py

from django import template
from django.core.paginator import Paginator, PageNotAnInteger, EmptyPage

register = template.Library()


@register.simple_tag(takes_context=True)
def paginate(context, object_list, page_count):
    left = 3
    right = 3

    paginator = Paginator(object_list, page_count)
    page = context["request"].GET.get("page")

    try:
        object_list = paginator.page(page)
        context["current_page"] = int(page)
        pages = get_left(context["current_page"], left, paginator.num_pages) + get_right(context["current_page"], right,
                                                                                         paginator.num_pages)
    except PageNotAnInteger:
        object_list = paginator.page(1)
        context["current_page"] = 1
        pages = get_right(context["current_page"], right, paginator.num_pages)
    except EmptyPage:
        object_list = paginator.page(paginator.num_pages)
        context["current_page"] = paginator.num_pages
        pages = get_left(context["current_page"], left, paginator.num_pages)

    context["article_list"] = object_list
    context["pages"] = pages
    context["last_page"] = paginator.num_pages
    context["first_page"] = 1
    try:
        context["pages_first"] = pages[0]
        context["pages_last"] = pages[-1] + 1
    except IndexError:
        context["pages_first"] = 1
        context["pages_last"] = 2

    return ""  # 必須加這個(gè)，否則首頁(yè)會(huì)顯示個(gè)None


def get_left(current_page, left, num_pages):
    if current_page == 1:
        return []
    elif current_page == num_pages:
        l = [i - 1 for i in range(current_page, current_page - left, -1) if i - 1 > 1]
        l.sort()
        return l
    l = [i for i in range(current_page, current_page - left, -1) if i > 1]
    l.sort()
    return l


def get_right(current_page, right, num_pages):
    if current_page == num_pages:
        return []
    return [i + 1 for i in range(current_page, current_page + right - 1) if i < num_pages - 1]

首先讓我們來看看整個(gè)分頁(yè)程序的執(zhí)行過程，模板標(biāo)簽本質(zhì)上來說就是一個(gè) python 函數(shù)而已，只是該函數(shù)可以被用在 Django 的模板系統(tǒng)里面。函數(shù)就是接受參數(shù)，返回一個(gè)值。例如我們這里定義的 def paginate(context, object_list, page_count): 分頁(yè)函數(shù)，它接收了這么一些參數(shù)，經(jīng)過各種處理，最終返回了 None 。

逐行解釋：

paginate.py

from django import template
from django.core.paginator import Paginator, PageNotAnInteger, EmptyPage
# 這是分頁(yè)功能涉及的一些類和異常，官方文檔對(duì)此有詳細(xì)介紹。當(dāng)然從命名也可以直接看出它們的用途：Paginator（分頁(yè)），PageNotAnInteger（頁(yè)碼不是一個(gè)整數(shù)異常），EmptyPage（空的頁(yè)碼號(hào)異常）

register = template.Library()
# 這是定義模板標(biāo)簽要用到的

@register.simple_tag(takes_context=True) 
# 這個(gè)裝飾器表明這個(gè)函數(shù)是一個(gè)模板標(biāo)簽，takes_context = True 表示接收上下文對(duì)象，就是前面所說的封裝了各種變量的 Context 對(duì)象。
def paginate(context, object_list, page_count): 
    # context是Context 對(duì)象，object_list是你要分頁(yè)的對(duì)象，page_count表示每頁(yè)的數(shù)量
    
    left = 3 # 當(dāng)前頁(yè)碼左邊顯示幾個(gè)頁(yè)碼號(hào) -1，比如3就顯示2個(gè)
    right = 3 # 當(dāng)前頁(yè)碼右邊顯示幾個(gè)頁(yè)碼號(hào) -1

    paginator = Paginator(object_list, page_count) # 通過object_list分頁(yè)對(duì)象
    page = context["request"].GET.get("page") # 從 Http 請(qǐng)求中獲取用戶請(qǐng)求的頁(yè)碼號(hào)

    try:
        object_list = paginator.page(page) # 根據(jù)頁(yè)碼號(hào)獲取第幾頁(yè)的數(shù)據(jù)
        context["current_page"] = int(page) # 把當(dāng)前頁(yè)封裝進(jìn)context（上下文）中
        pages = get_left(context["current_page"], left, paginator.num_pages) + get_right(context["current_page"], right, paginator.num_pages)
        # 調(diào)用了兩個(gè)輔助函數(shù)，根據(jù)當(dāng)前頁(yè)得到了左右的頁(yè)碼號(hào)，比如設(shè)置成獲取左右兩邊2個(gè)頁(yè)碼號(hào)，那么假如當(dāng)前頁(yè)是5，則 pages = [3,4,5,6,7],當(dāng)然一些細(xì)節(jié)需要處理，比如如果當(dāng)前頁(yè)是2，那么獲取的是pages = [1,2,3,4]
      
    except PageNotAnInteger:
        # 異常處理，如果用戶傳遞的page值不是整數(shù)，則把第一頁(yè)的值返回給他
        object_list = paginator.page(1)
        context["current_page"] = 1 # 當(dāng)前頁(yè)是1
        pages = get_right(context["current_page"], right, paginator.num_pages)
    except EmptyPage:
        # 如果用戶傳遞的 page 值是一個(gè)空值，那么把最后一頁(yè)的值返回給他
        object_list = paginator.page(paginator.num_pages)
        context["current_page"] = paginator.num_pages # 當(dāng)前頁(yè)是最后一頁(yè)，num_pages的值是總分頁(yè)數(shù)
        pages = get_left(context["current_page"], left, paginator.num_pages)

    context["article_list"] = object_list # 把獲取到的分頁(yè)的數(shù)據(jù)封裝到上下文中
    context["pages"] = pages # 把頁(yè)碼號(hào)列表封裝進(jìn)去
    context["last_page"] = paginator.num_pages # 最后一頁(yè)的頁(yè)碼號(hào)
    context["first_page"] = 1 # 第一頁(yè)的頁(yè)碼號(hào)為1
    try:
        # 獲取 pages 列表第一個(gè)值和最后一個(gè)值，主要用于在是否該插入省略號(hào)的判斷，在模板文件中將會(huì)體會(huì)到它的用處。注意這里可能產(chǎn)生異常，因?yàn)閜ages可能是一個(gè)空列表，比如本身只有一個(gè)分頁(yè)，那么pages就為空，因?yàn)槲覀冇肋h(yuǎn)不會(huì)獲取頁(yè)碼為1的頁(yè)碼號(hào)（至少有1頁(yè)，1的頁(yè)碼號(hào)已經(jīng)固定寫在模板文件中）
        context["pages_first"] = pages[0]
        context["pages_last"] = pages[-1] + 1
        # +1的原因是為了方便判斷，在模板文件中將會(huì)體會(huì)到其作用。
        
    except IndexError:
        context["pages_first"] = 1 # 發(fā)生異常說明只有1頁(yè)
        context["pages_last"] = 2 # 1 + 1 后的值 

    return ""  # 必須加這個(gè)，否則首頁(yè)會(huì)顯示個(gè)None


def get_left(current_page, left, num_pages):
    """
    輔助函數(shù)，獲取當(dāng)前頁(yè)碼的值得左邊兩個(gè)頁(yè)碼值，要注意一些細(xì)節(jié)，比如不夠兩個(gè)那么最左取到2，為了方便處理，包含當(dāng)前頁(yè)碼值，比如當(dāng)前頁(yè)碼值為5，那么pages = [3,4,5]
    """
    if current_page == 1:
        return []
    elif current_page == num_pages:
        l = [i - 1 for i in range(current_page, current_page - left, -1) if i - 1 > 1]
        l.sort()
        return l
    l = [i for i in range(current_page, current_page - left, -1) if i > 1]
    l.sort()
    return l


def get_right(current_page, right, num_pages):
    """
    輔助函數(shù)，獲取當(dāng)前頁(yè)碼的值得右邊兩個(gè)頁(yè)碼值，要注意一些細(xì)節(jié)，比如不夠兩個(gè)那么最右取到最大頁(yè)碼值。不包含當(dāng)前頁(yè)碼值。比如當(dāng)前頁(yè)碼值為5，那么pages = [6,7]
    """
    if current_page == num_pages:
        return []
    return [i + 1 for i in range(current_page, current_page + right - 1) if i < num_pages - 1]

把需要變量值都添加到上下文了，看看我們的模板文件該怎么寫：

templates/blog/pagination.html


    {% if article_list.has_previous %} # 判斷是否還有上一頁(yè)，有的話要顯示一個(gè)上一頁(yè)按鈕
        
            上一頁(yè)
        
    {% endif %}

    # 頁(yè)碼號(hào)為1永遠(yuǎn)顯示
    {% if first_page == current_page %} # 當(dāng)前頁(yè)就是第一頁(yè)
        1
    {% else %} # 否則的話，第一頁(yè)是可以點(diǎn)擊的，點(diǎn)擊后通過?page=1的形式把頁(yè)碼號(hào)傳遞給視圖函數(shù)
        1
    {% endif %}

    {% if pages_first > 2 %} # 2以前的頁(yè)碼號(hào)要被顯示成省略號(hào)了
        ...
    {% endif %}

    {% for page in pages %} # 通過for循環(huán)把pages中的值顯示出來
        {% if page == current_page %} # 是否當(dāng)前頁(yè)，按鈕會(huì)顯示不同的樣式
            {{ page }}
        {% else %}
            {{ page }}
        {% endif %}
    {% endfor %}
    
      # pages最后一個(gè)值+1的值小于最大頁(yè)碼號(hào)，說明有頁(yè)碼號(hào)需要被省略號(hào)替換
    {% if pages_last < last_page %}
        ...
    {% endif %}
    
      # 永遠(yuǎn)顯示最后一頁(yè)的頁(yè)碼號(hào)，如果只有一頁(yè)則前面已經(jīng)顯示了1就不用再顯示了
    {% if last_page != 1 %}
        {% if last_page == current_page %}
            {{ last_page }}
        {% else %}
            {{ last_page }}
        {% endif %}
    {% endif %}
    
    # 還有下一頁(yè)，則顯示一個(gè)下一頁(yè)按鈕
    {% if article_list.has_next %}
        
            下一頁(yè)
        
    {% endif %}

至此代碼部分編寫完了，看看如何使用這個(gè)模板標(biāo)簽吧，比如我們要在首頁(yè)對(duì)文章列表進(jìn)行分頁(yè)：

templates/blog/index.html

{% load paginate_tags %} # 首先必須通過load模板標(biāo)簽載入分頁(yè)標(biāo)簽
{% paginate article_list 7 %} 把文章列表傳給paginate函數(shù)，每頁(yè)分7個(gè)，context上下文則自動(dòng)被傳入，無需顯示指定

{% for article in article_list %}
    display the article information
{% endfor %}

{% include "blog/pagination.html" %}
# 這里用到一個(gè) include 技巧，把pagination的模板代碼寫在多帶帶的pagination.html文件中，這樣哪里需要用到哪里就 include 進(jìn)來就行，提高代碼的復(fù)用性。

至此，整個(gè)分頁(yè)功能就完成了，看看效果：

我們的博客文章是支持 markdown 語法標(biāo)記的（使用的是 markdown2 第三方 app），markdown 比較常用的兩個(gè)特性是 fetch code 和語法高亮。由于我們目前沒有對(duì)博客文章的 markdown 標(biāo)記做任何拓展，因此要標(biāo)記一段代碼，我們必須在每行代碼前縮進(jìn) 4 個(gè)空格，這很不方便。而 fetch code 可以讓我們?cè)趯懳恼聲r(shí)只按照下面的輸入就可以標(biāo)記一段代碼，相比每行縮進(jìn)四個(gè)空格要方便很多：

?```
def test_function():
    print("fectch code like this!")
?```

下面來拓展它，很簡(jiǎn)單，把用 markdown 標(biāo)記的語句拓展一下，在 Views.py 中找到 IndexView，其中有一句代碼的作用是來 markdown 我們的博客文章的：

for article in article_list:
    article.body = markdown2.markdown(article.body, )

將 markdown 函數(shù)拓展一下，傳入如下參數(shù)即可：

for article in article_list:
    article.body = markdown2.markdown(article.body, extras=["fenced-code-blocks"], )

這樣，每次要輸入一段代碼時(shí)，按照上面的語法輸入就可以了，比如我輸入下面的代碼段：

?``` # 注意這個(gè)符號(hào)是半角下波浪符號(hào)，即數(shù)字1左邊的那個(gè)鍵對(duì)應(yīng)的符號(hào)
class ArticleDetailView(DetailView):
    model = Article
    template_name = "blog/detail.html"
    context_object_name = "article"
    pk_url_kwarg = "article_id"

    def get_object(self, queryset=None):
        obj = super(ArticleDetailView, self).get_object()
        obj.body = markdown2.markdown(obj.body, extras=["fenced-code-blocks"], )
        return obj
?```

來看看效果：

此外別忘了把其他做了 markdown 標(biāo)記的地方也做相應(yīng)拓展，目前我們一共有三處：IndexView，DetailView，CategoryView。

現(xiàn)在輸入代碼方便了，但是美中不足的是代碼只有一種顏色，我們想要代碼高亮，需要使用到 Pygments 包。先安裝它：pip install pygments，安裝好后別忘了添加到 settings.py 中：

settings.py

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",
    "markdown2",
    "pygments", # 添加進(jìn)來
]

pygments 的工作原理是把代碼切分成一個(gè)個(gè)單詞，然后為這些單詞添加 css 樣式，不同的詞應(yīng)用不同的樣式，這樣就實(shí)現(xiàn)了代碼顏色的區(qū)分，即高亮了語法，因此我們要引入一些 css 樣式文件。在我們的 GitHub 項(xiàng)目的 DjangoBlog/blog/static/blog/css 目錄下有相應(yīng)的文件，拷貝下來添加到你的項(xiàng)目相同目錄下就可以了。之后再模板中引入樣式文件：

templates/base.html


    
    
    ...
    
    引入上面的樣式文件,當(dāng)然里面有很多樣式文件，喜歡哪個(gè)引哪個(gè)，比如我引的是github風(fēng)格的語法高亮
    ...

再次輸入代碼塊看看：

?```python # 注：這里一定要指定相應(yīng)語言，否則無法高亮代碼
class ArticleDetailView(DetailView):
    model = Article
    template_name = "blog/detail.html"
    context_object_name = "article"
    pk_url_kwarg = "article_id"

    def get_object(self, queryset=None):
        obj = super(ArticleDetailView, self).get_object()
        obj.body = markdown2.markdown(obj.body, extras=["fenced-code-blocks"], )
        return obj
?```

看看效果：

這里比較麻煩的是必須指定代碼對(duì)應(yīng)的語言，有人說 pygments 可以自動(dòng)識(shí)別語言的，但是我目前的測(cè)試來看似乎沒有效果。目前沒有找到設(shè)置方法，如有知道的朋友請(qǐng)告知。

整個(gè)完整的 Blog 項(xiàng)目代碼請(qǐng)?jiān)L問我們的 GitHub 組織倉(cāng)庫(kù)獲取。

聲明：本教程只是演示如何實(shí)現(xiàn)分頁(yè)和 markdown 語法高亮功能，在細(xì)節(jié)上處理上還有很多需要斟酌的地方，如果您有更好的實(shí)現(xiàn)方式或者實(shí)踐經(jīng)驗(yàn)，懇請(qǐng)傳授我們。如果您對(duì)本教程有任何不清晰的地方或者其他意見和建議，請(qǐng)及時(shí)通過郵件列表或者 GitHub Issue 或者評(píng)論留言反饋給我們。您的反饋和建議是我們持續(xù)改善本教程的最佳方式。

個(gè)人博客功能逐步完善，接下來的教程我們將繼續(xù)實(shí)現(xiàn)個(gè)人博客常帶的功能：標(biāo)簽云和文章歸檔，敬請(qǐng)期待下一期教程。如果你還有其他想實(shí)現(xiàn)的功能，也請(qǐng)告訴我們，我們會(huì)在教程中陸續(xù)實(shí)現(xiàn)。

django學(xué)習(xí)小組是一個(gè)促進(jìn) django 新手互相學(xué)習(xí)、互相幫助的組織。

小組在一邊學(xué)習(xí) django 的同時(shí)將一起完成幾個(gè)項(xiàng)目，包括：

一個(gè)簡(jiǎn)單的 django 博客，用于發(fā)布小組每周的學(xué)習(xí)和開發(fā)文檔；

django中國(guó)社區(qū)，為國(guó)內(nèi)的 django 開發(fā)者們提供一個(gè)長(zhǎng)期維護(hù)的 django 社區(qū)；

上面所說的這個(gè)社區(qū)類似于 segmentfault 和 stackoverflow ，但更加專注（只專注于 django 開發(fā)的問題）。

目前小組正在完成第一個(gè)項(xiàng)目，本文即是該項(xiàng)目第三周的相關(guān)文檔。

更多的信息請(qǐng)關(guān)注我們的?github 組織，本教程項(xiàng)目的相關(guān)源代碼也已上傳到 github 上。

同時(shí)，你也可以加入我們的郵件列表[email protected]?，隨時(shí)關(guān)注我們的動(dòng)態(tài)。我們會(huì)將每周的詳細(xì)開發(fā)文檔和代碼通過郵件列表發(fā)出。

如有任何建議，歡迎提 Issue，歡迎 fork，pr，當(dāng)然也別忘了 star 哦！