Get
返回给定参数的值。
参数可以按位置或按名称指定。在 Markdown 中调用短代码时,位置参数和命名参数只能用其中一种,不能混用。
这一页解决什么问题
Get 是短代码模板读取调用方参数的入口:{{< img src="a.jpg" >}} 里的 src、{{< quote "Hello" >}} 里的 "Hello",都靠它取出来。
它同时支持两套参数空间——位置(ARG 是整数)和名称(ARG 是字符串)——并在取不到时不报错,返回空值。所以「参数到底是哪一种」「取不到会怎样」是这一页的重点,也是短代码模板出错最集中的地方。
什么时候用,什么时候别用
该用:
- 模板知道调用方怎么传参(自己的短代码自己定规矩):位置用
.Get 0,命名用.Get "name"; - 想同时兼容两种写法 → 先用
IsNamedParams判断,再分别取(见本页示例); - 需要取全部参数 → 用
Params更直接。
别用:
- 想给参数设默认值 → 别指望
Get,要自己用with/default:{{ $src := .Get "src" | default "images/placeholder.jpg" }}; - 想校验「必填参数缺失」并报错 →
Get不会报错,要自己errorf(见Name与Position); - 想读短代码调用之外的数据(页面前置元数据)→ 用
Page。
位置参数
下面这个短代码调用使用位置参数:
content/about.mdmd
{{< myshortcode "Hello" "world" >}}要按位置获取参数:
layouts/_shortcodes/myshortcode.htmlgo-html-template
{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.命名参数
下面这个短代码调用使用命名参数:
content/about.mdmd
{{< myshortcode greeting="Hello" firstName="world" >}}要按名称获取参数:
layouts/_shortcodes/myshortcode.htmlgo-html-template
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.完整示例(实测)
测量条件:Hugo 0.167.0 extended,Windows,最小站点。同一个短代码被两种方式各调用一次。
模板 layouts/_shortcodes/myshortcode.html:
layouts/_shortcodes/myshortcode.htmlgo-html-template
<p>IsNamedParams:{{ .IsNamedParams }}</p>
<p>位置 0:{{ .Get 0 }}</p>
<p>位置 1:{{ .Get 1 }}</p>
<p>命名 greeting:{{ .Get "greeting" }}</p>
<p>命名 firstName:{{ .Get "firstName" }}</p>内容 content/about.md 里的两次调用:
content/about.mdmd
{{< myshortcode "Hello" "world" >}}
{{< myshortcode greeting="Hello" firstName="world" >}}Hugo 渲染为:
html
<!-- 第一次调用:位置参数 -->
<p>IsNamedParams:false</p>
<p>位置 0:Hello</p>
<p>位置 1:world</p>
<p>命名 greeting:</p>
<p>命名 firstName:</p>
<!-- 第二次调用:命名参数 -->
<p>IsNamedParams:true</p>
<p>位置 0:</p>
<p>位置 1:</p>
<p>命名 greeting:Hello</p>
<p>命名 firstName:world</p>你应当看到什么:同一个模板、两种调用方式,只有对应的那种取法有值——位置参数调用时命名取法全空,反之亦然。取不到时不会报错、也不会提示「你取错了空间」,所以在写模板时要么固定一种传参方式,要么按 IsNamedParams 分支。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
位置参数调用,.Get 0 / .Get 1 |
对应参数值(实测 Hello / world) |
否 |
命名参数调用,.Get "greeting" |
对应参数值(实测 Hello) |
否 |
命名参数调用,.Get "不存在的键" |
空字符串(实测 printf "%T" 为 string,eq … nil 为 false) |
否 |
位置参数调用,.Get "不存在的键" |
nil(实测 printf "%T" 为 <nil>,eq … nil 为 true) |
否 |
位置参数调用,.Get 9(越界) |
空字符串(实测 printf "%T" 为 string) |
否 |
命名参数调用,.Get 9 |
nil |
否 |
| 没有传任何参数 | 全部取到空值,len .Params 为 0 |
否 |
| 同一次调用里混用位置与命名 | —— | 是:got named parameter 'b'. Cannot mix named and positional parameters |
| 键名大小写不同 | 取不到(上游说明:名称区分大小写) | 否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 命名参数写了却取不到值 | 模板用 .Get 0 去取命名参数(两套空间不互通) |
用 .Get "键名",或用 IsNamedParams 分支 |
| 没报错但结果不对 | 参数值总是空 | 键名大小写不一致(firstName 与 firstname) |
保持调用方与模板一致 |
| 构建失败 | got named parameter 'b'. Cannot mix named and positional parameters |
同一个调用里既有 "a" 又有 b="c" |
只用其中一种;需要同时给两类信息就改用字典传参 |
| 报错看不懂 | 短代码参数里写了 {{< x "a" b >}} 之类 |
位置参数必须是带引号的字符串或可解析的值 | 检查引号 |
更多排查入口见故障排查。