TEMPLATES

分頁

顯示大量頁面集合於列表頁並不符合使用者友善設計：

  • 巨大的列表可能會讓使用者感到困惑且難以瀏覽，使用者可能會迷失在大量資訊中。
  • 大型頁面需要較長的載入時間，這可能會讓使用者感到沮喪，進而離開網站。
  • 沒有過濾或組織的情況下，查找特定項目會變成一個冗長的滾動操作。

透過為 home、section、taxonomy 和 term 頁面加上分頁功能，可以改善使用者體驗。

術語

paginate
將 [列表頁] 分割成兩個或更多子集。
pagination
將列表頁進行分頁的過程。
pager
在分頁過程中產生的物件，包含了列表頁的某個子集以及通向其他分頁的導航連結。
paginator
由一組 pager 組成的集合。

配置

可在網站配置中控制分頁行為。以下為預設設定：

hugo.
      
pagination:
  disableAliases: false
  pagerSize: 10
  path: page

[pagination]
  disableAliases = false
  pagerSize = 10
  path = 'page'

{
   "pagination": {
      "disableAliases": false,
      "pagerSize": 10,
      "path": "page"
   }
}
disableAliases
(bool) 是否禁用對第一個分頁產生別名。預設為 false。
pagerSize
(int) 每個分頁的頁面數量。預設為 10。
path
(string) 每個分頁 URL 中用來指示目標頁面為分頁的部分。預設為 page。

在多語言網站中，您可以為每個語言定義不同的分頁行為：

hugo.
      
languages:
  de:
    contentDir: content/de
    languageCode: de-DE
    languageDirection: ltr
    languageName: Deutsch
    pagination:
      disableAliases: true
      pagerSize: 20
      path: blatt
    weight: 2
  en:
    contentDir: content/en
    languageCode: en-US
    languageDirection: ltr
    languageName: English
    pagination:
      disableAliases: true
      pagerSize: 10
      path: page
    weight: 1

[languages]
  [languages.de]
    contentDir = 'content/de'
    languageCode = 'de-DE'
    languageDirection = 'ltr'
    languageName = 'Deutsch'
    weight = 2
    [languages.de.pagination]
      disableAliases = true
      pagerSize = 20
      path = 'blatt'
  [languages.en]
    contentDir = 'content/en'
    languageCode = 'en-US'
    languageDirection = 'ltr'
    languageName = 'English'
    weight = 1
    [languages.en.pagination]
      disableAliases = true
      pagerSize = 10
      path = 'page'

{
   "languages": {
      "de": {
         "contentDir": "content/de",
         "languageCode": "de-DE",
         "languageDirection": "ltr",
         "languageName": "Deutsch",
         "pagination": {
            "disableAliases": true,
            "pagerSize": 20,
            "path": "blatt"
         },
         "weight": 2
      },
      "en": {
         "contentDir": "content/en",
         "languageCode": "en-US",
         "languageDirection": "ltr",
         "languageName": "English",
         "pagination": {
            "disableAliases": true,
            "pagerSize": 10,
            "path": "page"
         },
         "weight": 1
      }
   }
}

方法

要為 home、section、taxonomy 或 term 頁面進行分頁，可以在對應模板中的 Page 物件上調用以下方法之一：

Paginate 方法更加靈活，允許您：

  • 分頁任何頁面集合
  • 過濾、排序並分組頁面集合
  • 覆蓋在網站配置中定義的每個分頁的頁面數量

相比之下，Paginator 方法對模板中傳遞的頁面集合進行分頁，並且無法覆蓋每個分頁的頁面數量。

範例

使用 Paginate 方法為列表頁進行分頁：

{{ $pages := where site.RegularPages "Type" "posts" }}
{{ $paginator := .Paginate $pages.ByTitle 7 }}

{{ range $paginator.Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

{{ template "_internal/pagination.html" . }}

在上面的範例中，我們：

  1. 建立一個頁面集合
  2. 按標題對頁面集合進行排序
  3. 為頁面集合進行分頁，每個分頁顯示 7 頁
  4. 遍歷已分頁的頁面集合，為每一頁渲染一個連結
  5. 呼叫嵌入的分頁模板來創建分頁之間的導航連結

使用 Paginator 方法為列表頁進行分頁：

{{ range .Paginator.Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

{{ template "_internal/pagination.html" . }}

在上面的範例中，我們：

  1. 對模板中傳遞的頁面集合進行分頁，使用預設的每個分頁頁面數量
  2. 遍歷已分頁的頁面集合，為每一頁渲染一個連結
  3. 呼叫嵌入的分頁模板來創建分頁之間的導航連結

快取

無論使用哪種分頁方法，首次調用會被快取並且無法更改。如果對同一列表頁調用分頁多次，隨後的調用將使用快取結果，這意味著隨後的調用不會如預期般運行。

當根據條件進行分頁時，請勿使用 compare.Conditional 函數，因為它會提前評估參數。請使用 if-else 結構來代替。

分組

可以將分頁與任何 [分組方法] 一起使用。例如：

{{ $pages := where site.RegularPages "Type" "posts" }}
{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}

{{ range $paginator.PageGroups }}
  <h2>{{ .Key }}</h2>
  {{ range .Pages }}
    <h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
  {{ end }}
{{ end }}

{{ template "_internal/pagination.html" . }}

導航

如上所示，最簡單的方式是使用 Hugo 的嵌入分頁模板來添加分頁之間的導航：

{{ template "_internal/pagination.html" . }}

嵌入的分頁模板有兩種格式：default 和 terse。上述代碼等同於：

{{ template "_internal/pagination.html" (dict "page" . "format" "default") }}

terse 格式的控件和頁面插槽較少，當樣式為水平列表時，佔用的空間更小。要使用 terse 格式：

{{ template "_internal/pagination.html" (dict "page" . "format" "terse") }}

使用任何 Pager 方法創建自訂的導航組件：

list-pages-in-section path=/methods/pager

結構

以下範例顯示了在分頁列表頁時，已發佈網站的結構。

此內容：

content/
├── posts/
│   ├── _index.md
│   ├── post-1.md
│   ├── post-2.md
│   ├── post-3.md
│   └── post-4.md
└── _index.md

此網站配置：

hugo.
      
pagination:
  disableAliases: false
  pagerSize: 2
  path: page

[pagination]
  disableAliases = false
  pagerSize = 2
  path = 'page'

{
   "pagination": {
      "disableAliases": false,
      "pagerSize": 2,
      "path": "page"
   }
}

此部分模板：

{{ range (.Paginate .Pages).Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

{{ template "_internal/pagination.html" . }}

已發佈網站將擁有如下結構：

public/
├── posts/
│   ├── page/
│   │   ├── 1/
│   │   │   └── index.html  <-- alias to public/posts/index.html
│   │   └── 2/
│   │       └── index.html
│   ├── post-1/
│   │   └── index.html
│   ├── post-2/
│   │   └── index.html
│   ├── post-3/
│   │   └── index.html
│   ├── post-4/
│   │   └── index.html
│   └── index.html
└── index.html

若要禁用第一個分頁的別名生成，請更改您的網站配置：

hugo.
      
pagination:
  disableAliases: true
  pagerSize: 2
  path: page

[pagination]
  disableAliases = true
  pagerSize = 2
  path = 'page'

{
   "pagination": {
      "disableAliases": true,
      "pagerSize": 2,
      "path": "page"
   }
}

這樣已發佈網站的結構將如下：

public/
├── posts/
│   ├── page/
│   │   └── 2/
│   │       └── index.html
│   ├── post-1/
│   │   └── index.html
│   ├── post-2/
│   │   └── index.html
│   ├── post-3/
│   │   └── index.html
│   ├── post-4/
│   │   └── index.html
│   └── index.html
└── index.html
Embedded templates Menus