HasMenuCurrent
报告给定 Page 对象是否匹配某个菜单项下的子菜单项所关联的 Page 对象。
这一页解决什么问题
导航栏要区分三种状态:当前项(active)、当前页所属栏目的祖先项(ancestor)、以及普通项。HasMenuCurrent 负责第二种:当前页面是某个菜单项所关联页面的后代。它与 IsMenuCurrent 是一对,通常写在同一个 if / else if 链里。
什么时候用,什么时候别用
该用:
- 导航里给「当前栏目」加高亮(例如访问
/docs/guide/alpha/时高亮菜单项的「指南」或「文档」); - 需要区分「当前页就是菜单页」与「当前页属于菜单页之下」。
别用:
- 判断「当前页就是菜单项页面」→ 用
IsMenuCurrent; - 菜单项没有关联页面(只写了
url而没有pageRef)→ 两个方法都无法匹配(上游 NOTE); - 只是想给当前页加高亮 → 比较
.RelPermalink更直接。
用法
如果菜单项关联的 Page 对象是一个 section,那么对该 section 的任何后代页面,这个方法同样返回 true。
go-html-template
{{ $currentPage := . }}
{{ range site.Menus.main }}
{{ if $currentPage.IsMenuCurrent .Menu . }}
<a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
{{ else if $currentPage.HasMenuCurrent .Menu . }}
<a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a>
{{ else }}
<a href="{{ .URL }}">{{ .Name }}</a>
{{ end }}
{{ end }}完整示例见菜单模板。
完整示例:导航高亮当前栏目
最小站点:hugo.toml 里定义三个菜单项(pageRef 分别是 /docs/guide、/docs、/posts),页面 content/docs/guide/alpha.md。导航模板:
layouts/_partials/nav.htmlgo-html-template
{{ $currentPage := . }}
<ul>
{{ range site.Menus.main }}
{{ if $currentPage.IsMenuCurrent .Menu . }}<li class="active"><a aria-current="page" href="{{ .URL }}">{{ .Name }}</a></li>
{{ else if $currentPage.HasMenuCurrent .Menu . }}<li class="ancestor"><a aria-current="true" href="{{ .URL }}">{{ .Name }}</a></li>
{{ else }}<li><a href="{{ .URL }}">{{ .Name }}</a></li>
{{ end }}
{{ end }}
</ul>hugo --source <站点目录> --ignoreCache 构建后,在 alpha(位于 /docs/guide/ 下)上输出:
html
<ul>
<li class="ancestor"><a aria-current="true" href="/docs/guide/">指南</a></li>
<li class="ancestor"><a aria-current="true" href="/docs/">文档</a></li>
<li><a href="/posts/">文章</a></li>
</ul>你应当看到什么:alpha 不是任何一个菜单项页面,但它是「指南」与「文档」两个 section 页的后代,所以两项都是 ancestor;「文章」既不是祖先也不是当前页。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;菜单项 pageRef 为 /docs/guide、/docs、/posts。
| 调用位置 | 指南 | 文档 | 文章 |
|---|---|---|---|
页面 /docs/guide/alpha/ |
true |
true |
false |
section 页 /docs/guide/ |
false |
true |
false |
section 页 /docs/ |
false |
false |
false |
规律:当前页就是菜单项页面时 HasMenuCurrent 为 false(那是 IsMenuCurrent 的职责);当前页位于菜单项页面之下时为 true。返回类型是 bool。
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 高亮不生效 | 所有菜单项都是普通样式 | 菜单项只配了 url,没有 pageRef,无法关联页面 |
在 hugo.toml 或前置元数据里加 pageRef(上游 NOTE) |
| 高亮层级不对 | 当前页所在栏目没有高亮 | 菜单里没有对应祖先 section 的菜单项 | 为祖先 section 建菜单项 |
| 没报错但结果不对 | 在 range 里用 . 调用,结果全错 |
循环改变了上下文 | 循环前存 {{ $currentPage := . }}(如上游示例) |
| 两个方法都返回 true | 判断顺序导致样式混乱 | IsMenuCurrent 与 HasMenuCurrent 同时成立的情况(例如同一页面配了两项) |
先判断 IsMenuCurrent,再用 else if |
更多排查入口见故障排查。