跳转到导航 跳转到主要内容
头条
W3C技术联盟，2024 年回顾
CNB版本
社区版
cnb.cool
国外版
cnb.build
2025/12/14

Handlebars

模板语言：
本页大纲
Eleventy 简称 文件扩展名 npm 包
hbs .hbs handlebars
Eleventy 或插件版本 handlebars 版本
@11ty/eleventy@0.x handlebars@4.x
@11ty/eleventy@1.x handlebars@4.x
@11ty/eleventy@2.x handlebars@4.x
@11ty/eleventy@3.x 及更新版本 N/A
@11ty/eleventy-plugin-handlebars@1.x handlebars@4.x

您可以覆盖 .hbs 文件的模板引擎。更多信息请阅读更改模板的渲染引擎。

安装

hbs 模板语言在 v3 中已从 Eleventy 核心中移出，现在需要插件安装。

npm install @11ty/eleventy-plugin-handlebars

添加到您的配置文件（显示 ESM 版本）：

eleventy.config.js
import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";

export default function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin);
}
const handlebarsPlugin = require("@11ty/eleventy-plugin-handlebars");

module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin);
}

使用更多选项：

eleventy.config.js
import handlebars from "handlebars";
import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";

export default function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin, {
// 覆盖 `handlebars` 库实例
eleventyLibraryOverride: handlebars,
});
}
const handlebars = require("handlebars");
const handlebarsPlugin = require("@11ty/eleventy-plugin-handlebars");

module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin, {
// 覆盖 `handlebars` 库实例
eleventyLibraryOverride: handlebars,
});
}

支持的功能

功能 语法
✅ 部分模板 {{> user}} 查找 _includes/user.hbs。不处理 include 文件中的前置内容。
🚫 部分模板（相对路径） 尚不支持：{{> ./user}} 在模板的当前目录中查找 user.hbs。
✅ 助手（自定义标签） {{ helperName myObject }} Handlebars 称之为助手，但 Eleventy 称之为短代码。阅读更多关于短代码的内容。
✅ 过滤器 {{ filterName myObject }} 阅读更多关于过滤器的内容。
✅ 短代码 {{{ uppercase name }}} 阅读更多关于短代码的内容。

助手

助手用于转换或修改内容。

Eleventy 的通用过滤器和通用短代码在 Handlebars 模板中都作为助手暴露。

阅读更多关于Handlebars 助手语法的内容。

过滤器

WARNING
Handlebars 不支持异步过滤器。阅读更多内容请查看这个 Handlebars 问题。

关于通用过滤器的说明

通用过滤器一直都被传递到 Handlebars 助手中。然而，短代码（成对/单个）更符合 Handlebars 助手的语义范围。

对于 Handlebars 内容，使用通用短代码比通用过滤器更受推荐。我们将继续支持将通用过滤器传递给 Handlebars 助手。这不会影响您的模板内容，因为 Handlebars 过滤器/助手/短代码的语法将继续保持相同。它们都只是助手。

短代码

短代码基本上是可重用的内容片段。Handlebars 使用现有的同步通用短代码。

WARNING
Handlebars 不支持异步短代码。阅读更多内容请查看这个 Handlebars 问题。
eleventy.config.js
export default function(eleventyConfig) {
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
  });
};
module.exports = function(eleventyConfig) {
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
  });
};

使用方法

{{{ user "Zach Leatherman" "zachleat" }}}
请注意，如果您在 Handlebars 短代码中返回 HTML，您需要使用 Handlebars 三重花括号语法（三个开头和三个结尾的花括号）来避免双重转义的 HTML。
输出
<div class="user">
	<div class="user_name">Zach Leatherman</div>
	<div class="user_twitter">@zachleat</div>
</div>

成对短代码

WARNING
Handlebars 不支持异步短代码。阅读更多内容请查看这个 Handlebars 问题。
eleventy.config.js
export default function(eleventyConfig) {
eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
  });
};
module.exports = function(eleventyConfig) {
eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
return `<div class="user">

<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
  });
};

使用方法

请注意，您可以在 {{ user }} 短代码内放置任何 Handlebars 标签或内容！是的，甚至其他短代码也可以！

{{# user "Zach Leatherman" "zachleat" }}Zach likes to take long walks on
Nebraska beaches.{{/ user }}
虽然不成对的短代码和助手要求您使用 Handlebars 三重花括号语法来避免双重转义的 HTML，但成对的 Handlebars 短代码没有这个要求。
输出
<div class="user">
	<div class="user_name">Zach Leatherman</div>
	<div class="user_twitter">@zachleat</div>
	<div class="user_bio">Zach likes to take long walks on Nebraska beaches.</div>
</div>

其他页面在 Template Languages