文档章节
Pager 方法
为分页列表页构建导航时,在 Pager 对象上使用这些方法。
这一页解决什么问题
列表页文章一多就要分页:/posts/、/posts/page/2/、/posts/page/3/……Paginate 方法把页面集合切成若干个分页器(pager),本章讲的就是分页器对象上的方法:取当前页的页面、算总数、生成「首页 / 上一页 / 下一页 / 末页」和数字页码条。
上游这些页每页只有一个同名方法的小例子,本站为每页补上了「什么时候用 / 什么时候别用」「一个可直接粘贴的实测示例」与「返回值边界(空、nil、取不到时)」三部分。全章示例统一在同一个最小站点上实测:7 篇 posts、[pagination] pagerSize = 3、baseURL = "https://example.org/",因此首页 3 条、/page/2/ 3 条、/page/3/ 1 条。
读完本章你应该能够
- 分清分页器与页面:
Pages是当前分页器里的页面集合,Pagers是全部 pager 的集合; - 用
PageNumber/TotalPages/PagerSize/NumberOfElements/TotalNumberOfElements五个数字回答「第几页 / 共几页 / 每页几条 / 本页几条 / 一共几条」; - 用
HasPrev/HasNext配Prev/Next生成导航,并知道首尾两页的Prev/Next是 nil,必须用with或Has*保护,否则整个构建失败; - 用
First/Last生成「首页 / 末页」链接——它们永远有值; - 用
PageGroups在分页的同时按月分组,并知道此时.Pages会是空的。
什么时候用本章的方法,什么时候别用
该用:
- 在
home/section/taxonomy/term模板里做分页; - 分页器一旦拿到(
{{ $paginator := .Paginate $pages }}),本章所有方法都以它为上下文。
别用:
- 在普通内容页上分页:实测直接构建失败——
error calling Paginate: pagination not supported for this page; - 想排序或筛选:那是
Paginate之前的事(用where、ByDate等); - 想换个集合再分页一次:实测同一页面上第二次
Paginate调用被静默忽略,沿用它缓存的 pager(PagerSize仍是第一次的值),不报错、不警告; - 把 pager 的
Prev/Next与 Page 的Prev/Next混为一谈:前者是「页码相邻」,后者是「文章上下篇」。
建议阅读顺序
- 先看当前页有什么:Pages → NumberOfElements → PageNumber → TotalPages → TotalNumberOfElements;
- 再生成导航:URL → Prev / Next → HasPrev / HasNext;
- 首末跳转:First → Last;
- 完整页码条:Pagers → PagerSize;
- 分页 + 分组:PageGroups。
每页条数与分页 URL 的配置见分页,Paginate 自身的用法见 methods/page/paginate。
本章内容
- First 返回分页器集合中的第一个分页器。 (今天)
- HasNext 报告当前分页器之后是否还有分页器。 (今天)
- HasPrev 报告当前分页器之前是否还有分页器。 (今天)
- Last 返回分页器集合中的最后一个分页器。 (今天)
- Next 返回分页器集合中的下一个分页器。 (今天)
- NumberOfElements 返回当前分页器中的页面数量。 (今天)
- PageGroups 返回当前分页器中的页面分组。 (今天)
- PageNumber 返回当前分页器在分页器集合中的编号。 (今天)
- Pagers 返回分页器集合。 (今天)
- PagerSize 返回每个分页器的页面数量。 (今天)
- Pages 返回当前分页器中的页面。 (今天)
- Prev 返回分页器集合中的上一个分页器。 (今天)
- TotalNumberOfElements 返回分页器集合中的页面数量。 (今天)
- TotalPages 返回分页器集合中的分页器数量。 (今天)
- URL 返回当前分页器相对于站点根目录的 URL。 (今天)