文档章节
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 跑出来,模板一律写清楚放在哪个文件里。
建议阅读顺序
本章内容
- 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 返回给定页面集合的反序结果。 (今天)