文档章节

Shortcode 方法

在你的短代码模板中使用这些方法。

这一页解决什么问题

短代码(shortcode)的模板放在 layouts/_shortcodes/ 下,它渲染时拿到的上下文(点号 .)不是页面,而是一个短代码对象。本章列出的就是「在这个上下文里能做什么」:读调用方传进来的参数、拿到标签之间的内容、知道自己是第几次被调用、访问所在的页面与站点、在嵌套调用里找到父级、以及保存本次调用的临时数据。

不熟悉短代码本身(模板放哪、两种记法有什么区别)的读者,请先读短代码一章,再回来查具体方法的边界。

读完本章你应该能够

  • 在短代码模板里按位置和名称取参数,并写出同时兼容两种调用方式的模板;
  • 理解 {{< >}}(标准记法)与 {{% %}}(Markdown 记法)下 .Inner 的差别,知道何时需要 RenderString、何时需要 InnerDeindent;
  • 用 .Name 与 .Position 写出「一眼能定位到出错文件与行号」的错误消息;
  • 用 .Ordinal 为重复调用的短代码生成唯一 ID,并分清嵌套调用的序号规则;
  • 用 .Parent 让子短代码继承父短代码的参数;
  • 用 .Store(或已弃用的 .Scratch)在两次短代码调用之间保持隔离的状态。

阅读顺序

  1. 取参数:Get → Params → IsNamedParams——先能用对调用方的写法;
  2. 处理内容:Inner → InnerDeindent——再决定标签之间的 Markdown 怎么渲染;
  3. 拿上下文:Page → Site → Parent——需要页面数据、站点数据或嵌套继承时;
  4. 定位与状态:Name → Position → Ordinal → Store → Scratch(0.139.0 起弃用,改用 Store);
  5. 生成链接:Ref → RelRef——短代码里指向其他页面时(注意它们与内容文件里的 ref / relref 短代码不是一回事)。

本章内容

  • Get 返回给定参数的值。 (今天)
  • Inner 返回短代码开始标签与结束标签之间的内容,适用于短代码调用包含结束标签的情况。 (今天)
  • InnerDeindent 返回短代码开始标签与结束标签之间的内容,并移除缩进,适用于短代码调用包含结束标签的情况。 (今天)
  • IsNamedParams 报告短代码调用是否使用命名参数。 (今天)
  • Name 返回短代码文件名,不含文件扩展名。 (今天)
  • Ordinal 返回短代码相对于其父级的从零开始的序号。 (今天)
  • Page 返回调用该短代码的 Page 对象。 (今天)
  • Params 返回短代码参数的集合。 (今天)
  • Parent 在嵌套短代码中返回父短代码的上下文。 (今天)
  • Position 返回调用该短代码的文件名和位置。 (今天)
  • Ref 返回具有给定路径、语言和输出格式的页面的绝对 URL。 (今天)
  • RelRef 返回具有给定路径、语言和输出格式的页面的相对 URL。 (今天)
  • Scratch 返回一个持久化的数据结构,用于存储和操作带 key 的值,作用域为当前短代码。 (今天)
  • Site 返回 Site 对象。 (今天)
  • Store 返回一个持久化的数据结构,用于存储和操作带 key 的值,作用域为当前短代码。 (今天)