TEMPLATES

分页

在列表页显示大量的页面集合并不友好：

  • 巨大的列表可能令人望而生畏且难以浏览。用户可能会迷失在海量信息中。
  • 大型页面加载时间更长，这可能会让用户感到沮丧并导致他们放弃网站。
  • 如果没有任何过滤或组织，查找特定项目将变成一项乏味的滚动练习。

通过对 home 、 section 、 taxonomy 和 term 页面进行分页来改进可用性。

术语

分页
将 列表页 分成两个或多个子集。
分页过程
对列表页进行分页的过程。
分页器
在分页过程中创建，分页器包含列表页的一个子集以及到其他分页器的导航链接。
分页器集合
分页器的集合。

配置

在您的站点配置中控制分页行为。这些是默认设置：

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 方法创建自定义导航组件：

First
返回翻页器集合中的第一个翻页器。
HasNext
报告当前分页器之后是否存在分页器。
HasPrev
报告当前分页器之前是否存在分页器。
Last
返回分页器集合中的最后一个分页器。
Next
返回分页器集合中的下一个分页器。
NumberOfElements
返回当前分页器中的页面数量。
PageGroups
返回当前分页器中的页面组。
PageNumber
返回分页器集合中当前分页器的编号。
PagerSize
返回每页显示的页面数量。
PageSize
返回每页分页器的页面数量。
Prev
返回翻页器集合中的上一页翻页器。
TotalNumberOfElements
返回分页器集合中的页面数量。
TotalPages
返回分页器集合中的分页器数量。
URL
返回当前分页器相对于站点根目录的 URL。
分页器
返回分页器集合。
页面
返回当前分页器中的页面。

结构

下面的示例描述了对列表页进行分页时的已发布站点结构。

使用此内容：

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  <-- 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

See also

Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page