文档章节
Shortcode 方法
在你的短代码模板中使用这些方法。
这一页解决什么问题
短代码(shortcode)的模板放在 layouts/_shortcodes/ 下,它渲染时拿到的上下文(点号 .)不是页面,而是一个短代码对象。本章列出的就是「在这个上下文里能做什么」:读调用方传进来的参数、拿到标签之间的内容、知道自己是第几次被调用、访问所在的页面与站点、在嵌套调用里找到父级、以及保存本次调用的临时数据。
不熟悉短代码本身(模板放哪、两种记法有什么区别)的读者,请先读短代码一章,再回来查具体方法的边界。
读完本章你应该能够
- 在短代码模板里按位置和名称取参数,并写出同时兼容两种调用方式的模板;
- 理解
{{< >}}(标准记法)与{{% %}}(Markdown 记法)下.Inner的差别,知道何时需要RenderString、何时需要InnerDeindent; - 用
.Name与.Position写出「一眼能定位到出错文件与行号」的错误消息; - 用
.Ordinal为重复调用的短代码生成唯一 ID,并分清嵌套调用的序号规则; - 用
.Parent让子短代码继承父短代码的参数; - 用
.Store(或已弃用的.Scratch)在两次短代码调用之间保持隔离的状态。
阅读顺序
本章内容
- Get 返回给定参数的值。 (今天)
- Inner 返回短代码开始标签与结束标签之间的内容,适用于短代码调用包含结束标签的情况。 (今天)
- InnerDeindent 返回短代码开始标签与结束标签之间的内容,并移除缩进,适用于短代码调用包含结束标签的情况。 (今天)
- IsNamedParams 报告短代码调用是否使用命名参数。 (今天)
- Name 返回短代码文件名,不含文件扩展名。 (今天)
- Ordinal 返回短代码相对于其父级的从零开始的序号。 (今天)
- Page 返回调用该短代码的 Page 对象。 (今天)
- Params 返回短代码参数的集合。 (今天)
- Parent 在嵌套短代码中返回父短代码的上下文。 (今天)
- Position 返回调用该短代码的文件名和位置。 (今天)
- Ref 返回具有给定路径、语言和输出格式的页面的绝对 URL。 (今天)
- RelRef 返回具有给定路径、语言和输出格式的页面的相对 URL。 (今天)
- Scratch 返回一个持久化的数据结构,用于存储和操作带 key 的值,作用域为当前短代码。 (今天)
- Site 返回 Site 对象。 (今天)
- Store 返回一个持久化的数据结构,用于存储和操作带 key 的值,作用域为当前短代码。 (今天)