Ordinal
返回短代码相对于其父级的从零开始的序号。
Ordinal 方法返回短代码相对于其父级的从零开始的序号。如果父级就是页面本身,该序号表示这个短代码在页面内容中的位置。
这一页解决什么问题
同一个短代码在一页里被调用多次时,它会渲染出多份结构相同、但应该互相区分的 HTML——例如多个 <img> 需要不同的 id、多个折叠面板需要不同的锚点、多个标签页需要不同的 aria-controls。Ordinal 就是那份「当前是第几次调用」的编号,用它拼出唯一标识。
页面上的第一个短代码(任意类型)序号是 0,之后每调用一次加一。所以它同时也是「这个短代码在页面里的位置」。
什么时候用,什么时候别用
该用:
- 生成唯一 ID:
{{ printf "img-%03d" .Ordinal }}; - 生成成对的
id/aria-controls/for之类需要前后对应的属性; - 统计「本页第几个某类元素」用于排序或样式。
别用:
- 想表达内容的语义顺序 →
Ordinal只是调用顺序;用你自己的参数(如weight)更可靠; - 想区分「哪个短代码」→ 用
Name; - 想在嵌套里拿全局编号 → 子短代码的
Ordinal是相对父级的,要全局位置只能自己传参。
用法
这个方法的一个用途是:当同一个短代码在同一个页面中被调用两次或更多次时,为元素指定唯一的 ID。例如:
content/about.mdmd
{{< img src="images/a.jpg" >}}
{{< img src="images/b.jpg" >}}这个短代码先做错误检查,然后渲染一个带唯一 id 属性的 HTML img 元素:
layouts/_shortcodes/img.htmlgo-html-template
{{ $src := "" }}
{{ with .Get "src" }}
{{ $src = . }}
{{ with resources.Get $src }}
{{ $id := printf "img-%03d" $.Ordinal }}
<img id="{{ $id }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ else }}
{{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }}
{{ end }}
{{ else }}
{{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }}
{{ end }}Hugo 把页面渲染为:
html
<img id="img-000" src="/images/a.jpg" width="600" height="400" alt="">
<img id="img-001" src="/images/b.jpg" width="600" height="400" alt="">完整示例(实测)
测量条件:Hugo 0.167.0 extended,Windows,最小站点,同一页面。先看顶层调用如何累计——下面这一页在 ord 之前已经用过 6 次其他短代码,所以序号从 6 开始:
layouts/_shortcodes/ord.htmlgo-html-template
<p>ord 序号:{{ .Ordinal }}</p>content/scdoc.mdmd
{{< ord >}}
{{< ord >}}
{{< outer >}}
A {{< inner >}} B {{< inner >}}
{{< /outer >}}
{{< inner >}}Hugo 渲染为(实测):
html
<p>ord 序号:6</p>
<p>ord 序号:7</p>
<p>outer 序号:8,父级为空:true</p>
<p>A <p>inner 序号:0,父级:outer</p>
B <p>inner 序号:1,父级:outer</p></p>
<p>inner 序号:9,父级:(无,父级是页面)</p>你应当看到什么——两个容易误解的地方:
- 序号是整页累计的,跟短代码类型无关:
ord、outer是完全不同的短代码,仍共用同一个计数器(6 → 7 → 8)。同一页面里第一个短代码是0(在另一个页面上实测:三个myshortcode依次得到0、1、2); - 嵌套的子短代码重新从 0 开始:父级
outer是 8,但它内部的两个inner是0和1——子级是相对父级编号的,而且不占用父级计数器(父级之后的下一个顶层inner拿到的是 9,而不是 11)。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 页面上第一个短代码 | 0 |
否 |
| 同页后续顶层调用 | 每调用一次 +1,跨短代码类型累计(实测 6、7、8、然后 9) | 否 |
| 嵌套在父短代码内的子短代码 | 相对父级从 0 开始(实测 0、1),不消耗父级计数器 |
否 |
| 父级为页面本身时 | 表示该短代码在页面内容中的位置(上游说明,与实测一致) | 否 |
| 短代码在循环/条件里被跳过 | 只有实际调用的才计数 | 否 |
| 短代码在不同页面 | 每个页面各自计数 | 否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 以为第一个 ID 是 img-001,结果是 img-000 |
Ordinal 从 0 开始 |
用 printf "img-%03d" 之类补零;要人类可读编号就自己加 1 |
| 没报错但结果不对 | 嵌套时 ID 撞车 | 子短代码的 Ordinal 相对父级,两个父级下都会出现 0 |
拼上父级信息:printf "%s-%d" .Parent.Name .Ordinal,或由父级传参 |
| 没报错但结果不对 | 页面里加了别的短代码后 ID 变了 | 序号是整页累计的 | 把 ID 与其他短代码解耦(用内容参数或哈希),不要依赖绝对数字 |
| 没报错但结果不对 | 序号的起点不是 0 | 该页前面还有其他短代码 | 这是预期行为;需要「本类第几个」就自己计数 |
更多排查入口见故障排查。