HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
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 方法更灵活,允许您:

  • 对任何页面集合进行分页
  • 过滤、排序和分组页面集合
  • 覆盖站点配置中定义的每页分页器的页面数

相比之下, 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") }}

要覆盖 Hugo 的嵌入式分页模板,请将 源代码 复制到 layouts/partials 目录中具有相同名称的文件中,然后使用 partial 函数从您的模板中调用它:

{{ partial "pagination.html" . }}

使用任何 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

  • EXIF
  • 文件
  • 简介
  • 颜色
  • Git信息

On this page

  • 术语
  • 配置
  • 方法
  • 示例
  • 缓存
  • 分组
  • 导航
  • 结构
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护