Page

IsDescendant

报告 PAGE1 是否为 PAGE2 的后代。

签名
PAGE1.IsDescendant PAGE2
返回类型
bool

这一页解决什么问题

IsDescendant 回答「PAGE1 是不是 PAGE2 的后代」。判断「当前页是否在某个栏目之下」——例如给栏目内的文章加不同版式——就用它;它与 IsAncestor 是同一关系的两个方向。

什么时候用,什么时候别用

该用:

  • 判断「当前页是否位于某个 section 之下」(含更深层级);
  • 做继承语义(栏目设置是否作用于本页)。

别用:

  • 判断「是否属于同一层 section」→ 用 InSection(注意它传 Page,不传字符串);
  • 想拿祖先页面本身 → 用 Ancestors;
  • 只是想看路径前缀 → 比较 .RelPermalink 字符串更直观,但跨语言/别名时不如本方法可靠。

基本用法

内容结构如下:

tree
content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md
│   │   ├── auction-1.md
│   │   └── auction-2.md
│   ├── 2023-12/
│   │   ├── _index.md
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md
│   ├── bidding.md
│   └── payment.md
└── _index.md

渲染 auctions 页面时:

go-html-template
{{ with .Site.GetPage "/" }}
  {{ $.IsDescendant . }} → true
{{ end }}

{{ with .Site.GetPage "/auctions" }}
  {{ $.IsDescendant . }} → false
{{ end }}

{{ with .Site.GetPage "/auctions/2023-11" }}
  {{ $.IsDescendant . }} → false
{{ end }}

{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
  {{ $.IsDescendant . }} → false
{{ end }}

上面的示例中,我们用 with 语句做防御式编码:页面不存在时不输出任何内容。再加上一个 else 分支,就可以报告错误:

go-html-template
{{ $path := "/auctions/2023-11" }}
{{ with .Site.GetPage $path }}
  {{ $.IsDescendant . }} → true
{{ else }}
  {{ errorf "Unable to find the section with path %s" $path }}
{{ end }}

理解上下文

在 with 块内部,上下文(即点号)是该 section 的 Page 对象,而不是传入模板的那个 Page 对象。如果写成下面这样:

go-html-template
{{ with .Site.GetPage "/auctions" }}
  {{ .IsDescendant . }} → true
{{ end }}

渲染 auction-1 页面时结果就是错的,因为这是把 section 页面与它自身作比较。

go-html-template
{{ with .Site.GetPage "/auctions" }}
  {{ $.IsDescendant . }} → true
{{ end }}

完整示例:判断当前页是否在某个栏目之下

最小站点:content/docs/guide/alpha.md(页面),逐层的 content/docs/guide/_index.md、content/docs/_index.md,另有 content/posts/。模板放在 layouts/_default/single.html:

layouts/_default/single.htmlgo-html-template
{{ $currentPage := . }}
{{ with .Site.GetPage "/docs" }}{{ $.IsDescendant . }} → true{{ end }}
{{ with .Site.GetPage "/posts" }}{{ $.IsDescendant . }} → false{{ end }}

hugo --source <站点目录> --ignoreCache 构建后,在 /docs/guide/alpha/ 上输出:

html
true → true
false → false

你应当看到什么:即使页面在 /docs/guide/(更深一层),判断「是否在 /docs 之下」依然是 true——这正是它与 InSection 的区别:InSection 在同样场景下为 false(它比较的是同一层)。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,Windows;结构见上;/docs、/docs/guide 为 section 页。

比较 结果 是否报错
页面 alpha 是否为 /docs 的后代 true 否
页面 alpha 是否为 /posts 的后代 false 否
页面是否为自己的后代(.IsDescendant .) false 否
section 页 /docs/guide、/docs 是否为首页的后代 true 否
参数不是 Page(字符串等) false(不报错) 否
返回类型 bool 否

常见坑

类别 症状 真因 怎么修
没报错但结果不对 判断「是否在栏目下」却用了 InSection InSection 只比较同一层 深层判断用 IsDescendant
没报错但结果不对 结果恒为 false 方向写反,或参数传了字符串 用 子页面.IsDescendant 祖先页,参数取 Page
没报错但结果不对 同层页面之间判断为 false 同层不是后代关系 同层用 InSection
没报错但结果不对 在 with 块里上下文弄错 with 改变了点号 用 $ 引用外层页面(上游「理解上下文」一节)

更多排查入口见故障排查。