分页
在列表页面上显示大型页面集合不友好
- 大量的列表可能令人望而生畏且难以浏览。用户可能会迷失在海量信息中。
- 大型页面加载时间更长,这可能会让用户感到沮丧并导致他们放弃网站。
- 如果没有任何过滤或组织,查找特定项目就会变成一项乏味的滚动练习。
通过对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" . }}
在上面的示例中,我们
- 构建页面集合
- 按标题对页面集合进行排序
- 对页面集合进行分页,每个分页器 7 页
- 遍历分页的页面集合,渲染到每个页面的链接
- 调用嵌入式分页模板以在分页器之间创建导航链接
要使用Paginator
方法对列表页面进行分页
{{ range .Paginator.Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{ template "_internal/pagination.html" . }}
在上面的示例中,我们
- 对传递到模板中的页面集合进行分页,使用每个分页器的默认页面数
- 遍历分页的页面集合,渲染到每个页面的链接
- 调用嵌入式分页模板以在分页器之间创建导航链接
缓存
无论分页方法如何,初始调用都会被缓存并且无法更改。如果您为给定的列表页面多次调用分页,后续调用将使用缓存的结果。这意味着后续调用将不会按编写的方式执行。
在有条件地进行分页时,不要使用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
方法创建自定义导航组件
- 第一页
- 返回分页器集合中的第一个分页器。
- HasNext
- 报告当前分页器之后是否还有分页器。
- HasPrev
- 报告当前分页器之前是否还有分页器。
- 最后一页
- 返回分页器集合中的最后一个分页器。
- 下一页
- 返回分页器集合中的下一个分页器。
- NumberOfElements
- 返回当前分页器中的页面数。
- PageGroups
- 返回当前分页器中的页面组。
- PageNumber
- 返回当前分页器在分页器集合中的编号。
- Pagers
- 返回分页器集合。
- PagerSize
- 返回每个分页器中的页面数。
- 页面
- 返回当前分页器中的页面。
- PageSize
- 返回每个分页器中的页面数。
- 上一页
- 返回分页器集合中的上一个分页器。
- 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 <-- 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