文档章节

Pages 方法

在 Page 对象集合上使用这些方法。

这一章解决什么问题

模板里凡是要「列出多个页面」的地方,拿到的都是页面集合(page.Pages):.Pages、site.RegularPages、collections.Where 的结果、分页器里的 .Pages。本章的方法都在这个集合上工作,解决四类问题:

你要做的事 用哪些方法
换一个顺序 ByDate、ByWeight、ByTitle、ByParam 等
倒过来 Reverse,可接在任意排序方法后面
分组(按月归档、按颜色分栏) GroupBy、GroupByDate、GroupByParam 等,返回的是「分组」切片,每组有自己的 .Key 与 .Pages
限量、计数、定位、导航 Limit、Len、IndexOf、Next、Prev、Related

本章的方法不筛选(要筛选用 collections.Where),也不产生分页(分页用分页器)。

读完本章你应该能够

  • 看着签名选方法:ByXxx 返回同类型的页面集合,GroupByXxx 返回分组切片,Len/IndexOf 返回整数;
  • 说清「默认顺序」是什么,以及为什么 .Pages 与 .ByWeight 常常看起来一样;
  • 知道空集合不会报错:range 得到空输出,Len 得 0,GroupBy 得空切片(在 if 里判为假);
  • 知道 Next/Prev 在集合首尾返回 nil,并用 with 包住以免输出空链接;
  • 知道 ByParam/GroupByParam 遇到「没有这个参数」的页面时行为不同(一个保留、一个丢弃),并在用之前先补默认值。

示例站点结构

本章各页的「实测」输出都来自下面这个最小站点(Hugo 0.167.0 extended,locale = 'en-US'、timeZone = 'UTC',hugo --source <目录> --ignoreCache)。要自己复现,照着建即可。

tree
content/
├── books/
│   ├── _index.md
│   ├── book-1.md   <-- weight = 10, date = 2023-03-03, linkTitle = "book-one", color = "green"
│   └── book-2.md   <-- weight = 20, date = 2023-04-04, linkTitle = "book-two", color = "blue"
├── empty/
│   └── _index.md   <-- 没有任何子页面,用来观察空集合
├── posts/
│   ├── _index.md   <-- title = "Posts Section", linkTitle = "Posts"
│   ├── post-1.md   <-- weight = 10, date = 2023-01-10, lastmod = 2024-03-01, expiryDate = 2027-01-01, publishDate = 2023-01-05, linkTitle = "alpha",   color = "red",   rank = 2, eventDate = 2024-05-01, author = { last_name = "Zulu" }
│   ├── post-2.md   <-- weight = 20, date = 2023-02-15, lastmod = 2024-01-15, expiryDate = 2027-03-01, publishDate = 2023-02-10, linkTitle = "bravo",   color = "blue",             eventDate = 2024-06-01, author = { last_name = "Alpha" }
│   ├── post-3.md   <-- weight = 30, date = 2022-12-01, lastmod = 2024-02-20, expiryDate = 2028-02-01, publishDate = 2022-11-25, linkTitle = "charlie", color = "red",   rank = 1, eventDate = 2024-05-15, author = { last_name = "Mike" }
│   └── post-4.md   <-- 未设置 weight, date = 2024-01-01, lastmod = 2024-04-01, expiryDate = 2028-01-01, publishDate = 2024-01-02, linkTitle = "delta", color = "green", eventDate = 2024-07-01, author = { last_name = "Bravo" }
└── _index.md

四条 posts 的正文分别有 3、10、1、6 个英文单词,用于 ByLength 的实测。后文所有「实测」数字都用 .Pages(posts 这个 section 的页面集合)或 site.RegularPages 跑出来,模板一律写清楚放在哪个文件里。

建议阅读顺序

  1. Len —— 先确认集合里有几个页面,后面的数字才有参照。
  2. 排序组:ByWeight → ByDate → ByTitle / ByLinkTitle → ByLength → ByParam → 其余 ByXxxDate。
  3. Reverse —— 一行实现降序,不必记每个方法的反向版本。
  4. 限量:Limit。
  5. 分组:GroupBy → GroupByParam → 各 GroupByXxxDate。
  6. 导航与定位:IndexOf → Next / Prev → Related → ByLanguage。

本章内容

  • ByDate 返回给定页面集合按日期升序排序后的结果。 (今天)
  • ByExpiryDate 返回给定页面集合按过期日期升序排序后的结果。 (今天)
  • ByLanguage 返回给定页面集合按语言排序后的结果。 (今天)
  • ByLastmod 返回给定页面集合按最后修改日期升序排序后的结果。 (今天)
  • ByLength 返回给定页面集合按内容长度升序排序后的结果。 (今天)
  • ByLinkTitle 返回给定页面集合按链接标题升序排序后的结果;未定义链接标题时回退到标题。 (今天)
  • ByParam 返回给定页面集合按指定参数升序排序后的结果。 (今天)
  • ByPublishDate 返回给定页面集合按发布日期升序排序后的结果。 (今天)
  • ByTitle 返回给定页面集合按标题升序排序后的结果。 (今天)
  • ByWeight 返回给定页面集合按权重升序排序后的结果。 (今天)
  • GroupBy 返回给定页面集合按指定字段升序分组后的结果。 (今天)
  • GroupByDate 返回给定页面集合按日期降序分组后的结果。 (今天)
  • GroupByExpiryDate 返回给定页面集合按过期日期降序分组后的结果。 (今天)
  • GroupByLastmod 返回给定页面集合按最后修改日期降序分组后的结果。 (今天)
  • GroupByParam 返回给定页面集合按指定参数升序分组后的结果。 (今天)
  • GroupByParamDate 返回给定页面集合按指定日期参数降序分组后的结果。 (今天)
  • GroupByPublishDate 返回给定页面集合按发布日期降序分组后的结果。 (今天)
  • IndexOf 返回给定页面在给定页面集合中从零开始的索引。 (今天)
  • Len 返回给定页面集合中的页面数量。 (今天)
  • Limit 返回给定页面集合中的前 N 个页面。 (今天)
  • Next 返回页面集合中相对于给定页面的下一个页面。 (今天)
  • Prev 返回页面集合中相对于给定页面的上一个页面。 (今天)
  • Related 返回与给定页面相关的一组页面。 (今天)
  • Reverse 返回给定页面集合的反序结果。 (今天)