Shortcode

Ordinal

返回短代码相对于其父级的从零开始的序号。

签名
SHORTCODE.Ordinal
返回类型
int

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>

你应当看到什么——两个容易误解的地方:

  1. 序号是整页累计的,跟短代码类型无关:ord、outer 是完全不同的短代码,仍共用同一个计数器(6 → 7 → 8)。同一页面里第一个短代码是 0(在另一个页面上实测:三个 myshortcode 依次得到 0、1、2);
  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 该页前面还有其他短代码 这是预期行为;需要「本类第几个」就自己计数

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