Eleventy(11ty) logo Eleventy
The possum is Eleventy’s mascot
Eleventy 中文文档
Menu
Eleventy 1.93s
Next.js 70.65s

快捷码(Shortcodes)

Contents

各种模板引擎都支持通过快捷码(shortcodes)实现内容重用。快捷码(shortcodes)是模板语言(Template Language)基于 自定义标签(Custom Tags) 提供的一种语法糖。JavaScript、Liquid、Nunjucks、Handlebars 模板语言是支持 快捷码(Shortcodes)的。

以下是几个示例:

View this example in: Liquid Nunjucks 11ty.js Handlebars
Filename sample.liquid
{% user firstName, lastName %}

在 Liquid 模板中,参数间的逗号是 可有可无的

Filename sample.liquid
{% user firstName lastName %}
Filename sample.njk
{% user firstName, lastName %}

在 Nunjucks 模板中,参数间的逗号是 必须的

Filename sample.11ty.js
module.exports = function({ firstName, lastName }) {
return `<h1>${this.user(firstName, lastName)}</h1>`;
};
Filename sample.hbs
<!-- Note the three opening and closing curly brackets (the triple-stash) -->
{{{ user firstName lastName }}}
INFO:
请注意,如果你在 Handlebars 快捷码中返回 HTML,你需要使用 Handlebars 的 triple-stash 语法(三个开头和三个结尾的花括号,例如 {{{ shortcodeName }}})以避免对 HTML 进行二次转义。如果被二次转义了,HTML 的段落标签将会被输出为 &lt;p&gt; 形式
Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Shortcodes added in this way are available in:
// * Markdown
// * Liquid
// * Nunjucks
// * Handlebars (not async)
// * JavaScript

eleventyConfig.addShortcode("user", function(firstName, lastName) {});

// Async support for `addShortcode` is new in Eleventy v2.0.0
eleventyConfig.addShortcode("user", async function(myName) { /* … */ });

// Async method available
eleventyConfig.addAsyncShortcode("user", async function(myName) { /* … */ });
};

A shortcode returns content (a JavaScript string or template literal) that is used in the template. You can use these however you’d like—you could even think of them as reusable components.

INFO:
Markdown files are pre-processed as Liquid templates by default—any shortcodes available in Liquid templates are also available in Markdown files. Likewise, if you change the template engine for Markdown files, the shortcodes available for that templating language will also be available in Markdown files.

请阅读各个模板语言关于快捷码(shortcodes)的文档以了解更多信息:

配对快捷码(Paired Shortcodes) Jump to heading

从上面所了解到的快捷码(shortcodes)信息来看,它还是挺不错的。但实际上,快捷码和过滤器(filter)没有什么不同。其实,当快捷码(Shortcodes)配对使用时才能体现出它的强大之处。配对快捷码(Paired Shortcodes)由一个开始标签和一个结束标签组成,并且允许你在其中嵌套其它模板内容!

View this example in: Liquid Nunjucks 11ty.js Handlebars
Syntax Liquid
{% user firstName, lastName %}
Hello {{ someOtherVariable }}.

Hello {% anotherShortcode %}.
{% enduser %}

在 Liquid 模板中,参数之间的逗号是 可有可无的

Syntax Nunjucks
{% user firstName, lastName %}
Hello {{ someOtherVariable }}.

Hello {% anotherShortcode %}.
{% enduser %}

在 Nunjucks 模板中,参数之间的逗号是 必须的

Syntax Handlebars
{{# user firstName lastName }}
Hello {{ someOtherVariable }}.

Hello {{ anotherShortcode }}.
{{/ user }}
module.exports = function(data) {
let userContent = `Hello ${data.someOtherVariable}

Hello
${this.anotherShortCode()}`
;

// pass the content as the first parameter.
return `<h1>${this.user(userContent, data.firstName, data.lastName)}</h1>`;
};

当使用 Eleventy 的 API 添加配对快捷码(paired shortcodes)时,第一个参数是配对快捷码的起止标签之间所嵌入的内容。

Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Shortcodes added in this way are available in:
// * Markdown
// * Liquid
// * Nunjucks
// * Handlebars (not async)
// * JavaScript

eleventyConfig.addPairedShortcode("user", function(content, firstName, lastName) {});

// Async support for `addPairedShortcode` is new in Eleventy v2.0.0
eleventyConfig.addPairedShortcode("user", async function(content, myName) { /* … */ });

// Async method available
eleventyConfig.addPairedAsyncShortcode("user", async function(content, myName) { /* … */ });
};
INFO:
Markdown files are pre-processed as Liquid templates by default—any shortcodes available in Liquid templates are also available in Markdown files. Likewise, if you change the template engine for Markdown files, the shortcodes available for that templating language will also be available in Markdown files.

Read more about using paired shortcodes on the individual Template Language documentation pages:

Asynchronous Shortcodes Jump to heading

This is supported by Liquid, Nunjucks, and JavaScript template types (Handlebars is not async-friendly).

Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Async support for `addShortcode` and `addPairedShortcode` is new in Eleventy v2.0.0
eleventyConfig.addShortcode("single", async function(myName) { /* … */ });
eleventyConfig.addPairedShortcode("paired", async function(content, myName) { /* … */ });

// Async methods available in Eleventy v0.10.0+
eleventyConfig.addAsyncShortcode("single", async function(myName) { /* … */ });
eleventyConfig.addPairedAsyncShortcode("paired", async function(content, myName) { /* … */ });
};

Scoped Data in Shortcodes Jump to heading

A few Eleventy-specific data properties are available to shortcode callbacks.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Make sure you’re not using an arrow function here: () => {}
eleventyConfig.addShortcode("myShortcode", function() {
// this.page
// this.eleventy
});
};

Per-Engine Shortcodes Jump to heading

You can also specify different functionality for shortcodes in each engine, if you’d like. Using the addShortcode or addPairedShortcode function is equivalent to adding the shortcode to every supported template engine.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Liquid
eleventyConfig.addLiquidShortcode("user", function(firstName, lastName) {});
eleventyConfig.addPairedLiquidShortcode("user", function(content, firstName, lastName) {});

// Nunjucks
eleventyConfig.addNunjucksShortcode("user", function(firstName, lastName) {});
eleventyConfig.addPairedNunjucksShortcode("user", function(content, firstName, lastName) {});

// Handlebars
eleventyConfig.addHandlebarsShortcode("user", function(firstName, lastName) {});
eleventyConfig.addPairedHandlebarsShortcode("user", function(content, firstName, lastName) {});

// JavaScript Template Function (New in 0.7.0)
eleventyConfig.addJavaScriptFunction("user", function(firstName, lastName) {});
eleventyConfig.addJavaScriptFunction("user", function(content, firstName, lastName) {}); // Faux-paired shortcode
INFO:
Markdown files are pre-processed as Liquid templates by default—any shortcodes available in Liquid templates are also available in Markdown files. Likewise, if you change the template engine for Markdown files, the shortcodes available for that templating language will also be available in Markdown files.

Async Friendly Per-Engine Shortcodes Jump to heading

Learn more about these on the individual template engine pages for Nunjucks, Liquid, and 11ty.js JavaScript.

Filename .eleventy.js
  // Async-friendly
// Liquid is already async-friendly
eleventyConfig.addLiquidShortcode("user", async function() {});
eleventyConfig.addPairedLiquidShortcode("user", async function(content) {});

// Nunjucks Async
eleventyConfig.addNunjucksAsyncShortcode("user", async function() {});
eleventyConfig.addPairedNunjucksAsyncShortcode("user", async function(content) {});

// JavaScript Template Function (make sure you `await` these!)
eleventyConfig.addJavaScriptFunction("user", async function() {});
eleventyConfig.addJavaScriptFunction("user", async function(content) {}); // Faux-paired shortcode
};

Other pages in Configuration:


相关文档