- Stable
3.0.0
Toggle Menu
5.81s
43.36s
Shortcodes
Contents
各种模板引擎都支持通过快捷码(shortcodes)实现内容重用。快捷码(shortcodes)是模板语言(Template Language)基于 自定义标签(Custom Tags) 提供的一种语法糖。JavaScript、Liquid、Nunjucks 模板语言均支持 快捷码(Shortcodes)。
以下是几个示例:
{% user firstName, lastName %}
The comma between arguments is optional in Liquid templates.
{% user firstName lastName %}
{% user firstName, lastName %}
The comma between arguments is required in Nunjucks templates.
export default function({ firstName, lastName }) {
return `<h1>${this.user(firstName, lastName)}</h1>`;
};
module.exports = function({ firstName, lastName }) {
return `<h1>${this.user(firstName, lastName)}</h1>`;
};
export default function (eleventyConfig) {
// Shortcodes added in this way are available in:
// * Markdown
// * Liquid
// * Nunjucks
// * JavaScript
// * Handlebars (not async)
eleventyConfig.addShortcode("user", function(firstName, lastName) { /* … */ });
// Async-friendly in v2.0.0
eleventyConfig.addShortcode("user", async function(myName) { /* … */ });
// Direct async method available
eleventyConfig.addAsyncShortcode("user", async function(myName) { /* … */ });
};
module.exports = function (eleventyConfig) {
// Shortcodes added in this way are available in:
// * Markdown
// * Liquid
// * Nunjucks
// * JavaScript
// * Handlebars (not async)
eleventyConfig.addShortcode("user", function(firstName, lastName) { /* … */ });
// Async-friendly in v2.0.0
eleventyConfig.addShortcode("user", async function(myName) { /* … */ });
// Direct 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.
请阅读各个模板语言关于快捷码(shortcodes)的文档以了解更多信息:
- JavaScript
*.11ty.js
(async-friendly) - Liquid
*.liquid
(async-friendly) - Nunjucks
*.njk
(async-friendly) - Handlebars
*.hbs
(sync only)
配对快捷码(Paired Shortcodes)
从上面所了解到的快捷码(shortcodes)信息来看,它还是挺不错的。但实际上,快捷码和过滤器(filter)没有什么不同。其实,当快捷码(Shortcodes)配对使用时才能体现出它的强大之处。配对快捷码(Paired Shortcodes)由一个开始标签和一个结束标签组成,并且允许你在其中嵌套其它模板内容!
{% user firstName, lastName %}
Hello {{ someOtherVariable }}.
Hello {% anotherShortcode %}.
{% enduser %}
The comma between arguments is optional in Liquid templates.
{% user firstName, lastName %}
Hello {{ someOtherVariable }}.
Hello {% anotherShortcode %}.
{% enduser %}
The comma between arguments is required in Nunjucks.
export default 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>`;
};
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>`;
};
When adding paired shortcodes using the Configuration API, the first argument to your shortcode callback is the nested content.
export default function (eleventyConfig) {
// Shortcodes added in this way are available in:
// * Markdown
// * Liquid
// * Nunjucks
// * JavaScript
// * Handlebars (sync only)
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) { /* … */ });
};
module.exports = function (eleventyConfig) {
// Shortcodes added in this way are available in:
// * Markdown
// * Liquid
// * Nunjucks
// * JavaScript
// * Handlebars (sync only)
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) { /* … */ });
};
Read more about using paired shortcodes on the individual Template Language documentation pages:
- JavaScript
*.11ty.js
(async-friendly) - Liquid
*.liquid
(async-friendly) - Nunjucks
*.njk
(async-friendly) - Handlebars
*.hbs
(sync only)
Asynchronous Shortcodes
addShortcode
, addPairedShortcode
both accept async
function callbacks as of Eleventy v2.0.0
. addAsyncShortcode
and addPairedAsyncShortcode
also accept async
function callbacks and have been available since Eleventy v0.10.0
.
Scoped Data in Shortcodes
A few Eleventy-specific data properties are available to shortcode callbacks.
this.page
(Learn aboutpage
)this.eleventy
Added in v2.0.0 (Learn abouteleventy
)this.env
(Nunjucks-specific) Added in v3.0.0this.ctx
(Nunjucks-specific) Added in v3.0.0
export default function (eleventyConfig) {
// Make sure you’re not using an arrow function here: () => {}
eleventyConfig.addShortcode("myShortcode", function () {
// this.page
// this.eleventy
});
};
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
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.
export default 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) {});
// JavaScript Template Function (New in 0.7.0)
eleventyConfig.addJavaScriptFunction("user", function(firstName, lastName) {});
eleventyConfig.addJavaScriptFunction("user", function(content, firstName, lastName) {}); // Faux-paired shortcode
};
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) {});
// JavaScript Template Function (New in 0.7.0)
eleventyConfig.addJavaScriptFunction("user", function(firstName, lastName) {});
eleventyConfig.addJavaScriptFunction("user", function(content, firstName, lastName) {}); // Faux-paired shortcode
};
Async Friendly Per-Engine Shortcodes
Learn more about these on the individual template engine pages for Nunjucks, Liquid, and 11ty.js
JavaScript.
export default function (eleventyConfig) {
// 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 when using in templates!)
eleventyConfig.addJavaScriptFunction("user", async function() {});
eleventyConfig.addJavaScriptFunction("user", async function(content) {}); // Faux-paired shortcode
};
module.exports = function (eleventyConfig) {
// 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 when using in templates!)
eleventyConfig.addJavaScriptFunction("user", async function() {});
eleventyConfig.addJavaScriptFunction("user", async function(content) {}); // Faux-paired shortcode
};
Other pages in Configuration:
- Configuration Shapes
- Passthrough File Copy
- Ignore Files
- Filters
- 快捷码(Shortcodes)
- Preprocessors
- Custom Tags
- Events
- Transforms
- Watch and Serve
- Memoize