Handlebars.Net 2.1.6

Handlebars.Net

在您的 .NET 应用程序中快速执行 Handlebars.js 模板。

Handlebars.js 是由 Chris Wanstrath 创建的 Mustache 模板语言的扩展。Handlebars.js 和 Mustache 都是逻辑无关的模板语言，它们像我们所有人都知道的那样将视图和代码分开。

查看 handlebars.js 文档 了解如何编写 Handlebars 模板。

Handlebars.Net 不使用脚本引擎来运行 JavaScript 库 - 它 将 Handlebars 模板直接编译为 IL 字节码。它还尽可能地模拟 JS 库的 API。

安装

dotnet add package Handlebars.Net

扩展

以下项目扩展了 Handlebars.Net

• Handlebars.Net.Extension.Json（添加 System.Text.Json.JsonDocument 支持）
• Handlebars.Net.Extension.NewtonsoftJson（添加 Newtonsoft.Json 支持）
• Handlebars.Net.Helpers（提供更多辅助函数，分类包括：'Constants', 'Enumerable', 'Math', 'Regex', 'String', 'DateTime', 'Url', 'DynamicLinq', 'Humanizer', 'Json', 'Random', 'Xeger' 和 'XPath'。）

用法

string source =
@"<div class=""entry"">
  <h1>{{title}}</h1>
  <div class=""body"">
    {{body}}
  </div>
</div>";

var template = Handlebars.Compile(source);

var data = new {
    title = "My new post",
    body = "This is my first post!"
};

var result = template(data);

/* Would render:
<div class="entry">
  <h1>My New Post</h1>
  <div class="body">
    This is my first post!
  </div>
</div>
*/

注册部分视图

string source =
@"<h2>Names</h2>
{{#names}}
  {{> user}}
{{/names}}";

string partialSource =
@"<strong>{{name}}</strong>";

Handlebars.RegisterTemplate("user", partialSource);

var template = Handlebars.Compile(source);

var data = new {
  names = new [] {
    new {
        name = "Karen"
    },
    new {
        name = "Jon"
    }
  }
};

var result = template(data);

/* Would render:
<h2>Names</h2>
  <strong>Karen</strong>
  <strong>Jon</strong>
*/

注册辅助函数

Handlebars.RegisterHelper("link_to", (writer, context, parameters) => 
{
    writer.WriteSafeString($"<a href='{context["url"]}'>{context["text"]}</a>");
});

string source = @"Click here: {{link_to}}";

var template = Handlebars.Compile(source);

var data = new {
    url = "https://github.com/rexm/handlebars.net",
    text = "Handlebars.Net"
};

var result = template(data);

/* Would render:
Click here: <a href='https://github.com/rexm/handlebars.net'>Handlebars.Net</a>
*/

此操作将期望你的视图位于 /Views 文件夹中，如下所示：

Views\layout.hbs                |<--shared as in \Views            
Views\partials\somepartial.hbs   <--shared as in  \Views\partials
Views\{Controller}\{Action}.hbs 
Views\{Controller}\{Action}\partials\somepartial.hbs 

注册区块辅助函数

Handlebars.RegisterHelper("StringEqualityBlockHelper", (output, options, context, arguments) => 
{
    if (arguments.Length != 2)
    {
        throw new HandlebarsException("{{#StringEqualityBlockHelper}} helper must have exactly two arguments");
    }

    var left = arguments.At<string>(0);
    var right = arguments[1] as string;
    if (left == right) options.Template(output, context);
    else options.Inverse(output, context);
});

var animals = new Dictionary<string, string>() 
{
	{"Fluffy", "cat" },
	{"Fido", "dog" },
	{"Chewy", "hamster" }
};

var template = "{{#each this}}The animal, {{@key}}, {{#StringEqualityBlockHelper @value 'dog'}}is a dog{{else}}is not a dog{{/StringEqualityBlockHelper}}.\r\n{{/each}}";
var compiledTemplate = Handlebars.Compile(template);
string templateOutput = compiledTemplate(animals);

/* Would render
The animal, Fluffy, is not a dog.
The animal, Fido, is a dog.
The animal, Chewy, is not a dog.
*/

注册装饰器

[Fact]
public void BasicDecorator(IHandlebars handlebars)
{
    string source = "{{#block @value-from-decorator}}{{*decorator 42}}{{@value}}{{/block}}";

    var handlebars = Handlebars.Create();
    handlebars.RegisterHelper("block", (output, options, context, arguments) =>
    {
        options.Data.CreateProperty("value", arguments[0], out _);
        options.Template(output, context);
    });
    
    handlebars.RegisterDecorator("decorator", 
        (TemplateDelegate function, in DecoratorOptions options, in Context context, in Arguments arguments) =>
    {
        options.Data.CreateProperty("value-from-decorator", arguments[0], out _);
    });
    
    var template = handlebars.Compile(source);
    
    var result = template(null);
    Assert.Equal("42", result);
}

更多示例请参阅 DecoratorTests.cs

已知限制

• 在装饰器内注册的辅助函数不会覆盖现有注册

注册自定义值格式化

如果你需要应用自定义值格式化（例如 DateTime），可以使用 IFormatter 和 IFormatterProvider 接口

public sealed class CustomDateTimeFormatter : IFormatter, IFormatterProvider
{
    private readonly string _format;

    public CustomDateTimeFormatter(string format) => _format = format;

    public void Format<T>(T value, in EncodedTextWriter writer)
    {
        if(!(value is DateTime dateTime)) 
            throw new ArgumentException("supposed to be DateTime");
        
        writer.Write($"{dateTime.ToString(_format)}");
    }

    public bool TryCreateFormatter(Type type, out IFormatter formatter)
    {
        if (type != typeof(DateTime))
        {
            formatter = null;
            return false;
        }

        formatter = this;
        return true;
    }
}

[Fact]
public void DateTimeFormatter(IHandlebars handlebars)
{
    var source = "{{now}}";

    var format = "d";
    var formatter = new CustomDateTimeFormatter(format);
    handlebars.Configuration.FormatterProviders.Add(formatter);

    var template = handlebars.Compile(source);
    var data = new
    {
        now = DateTime.Now
    };
    
    var result = template(data);
    Assert.Equal(data.now.ToString(format), result);
}

备注

• 格式化程序根据注册顺序反向解析。如果有多个提供程序可以提供类型格式化程序，则最后一个注册的会被使用。

共享环境

默认情况下，Handlebars 将为每个编译模板创建一个独立的副本环境。这样做是为了防止从另一个模板中更改一个模板的行为。

不幸的是，如果运行时有大量的编译模板（无论模板大小如何），它可能对内存占用很大。这可以通过使用 SharedEnvironment 解决。

在 SharedEnvironment 中编译的模板将共享相同的配置。

限制

已创建共享环境后，只能更改运行时配置属性。对 Configuration.CompileTimeConfiguration 和其他编译时属性的更改将没有任何效果。

示例

[Fact]
public void BasicSharedEnvironment()
{
    var handlebars = Handlebars.CreateSharedEnvironment();
    handlebars.RegisterHelper("registerLateHelper", 
        (in EncodedTextWriter writer, in HelperOptions options, in Context context, in Arguments arguments) =>
        {
            var configuration = options.Frame
                .GetType()
                .GetProperty("Configuration", BindingFlags.Instance | BindingFlags.NonPublic)?
                .GetValue(options.Frame) as ICompiledHandlebarsConfiguration;
            
            var helpers = configuration?.Helpers;

            const string name = "lateHelper";
            if (helpers?.TryGetValue(name, out var @ref) ?? false)
            {
                @ref.Value = new DelegateReturnHelperDescriptor(name, (c, a) => 42);
            }
        });
    
    var _0_template = "{{registerLateHelper}}";
    var _0 = handlebars.Compile(_0_template);
    var _1_template = "{{lateHelper}}";
    var _1 = handlebars.Compile(_1_template);
    
    var result = _1(null);
    Assert.Equal("", result); // `lateHelper` is not registered yet

    _0(null);
    result = _1(null);
    Assert.Equal("42", result);
}

兼容性功能开关

兼容性功能开关定义了一组控制编译/渲染行为的设置。每个设置都会启用某些特性，这可能会破坏与标准 Handlebars 的兼容性。默认情况下，所有开关都设置为 false。

传说

• 区域
  • 编译时间：在模板编译时产生影响
  • 运行时：在模板渲染时产生影响

RelaxedHelperNaming

如果为 true，则启用对 Handlebars.Net 辅助函数命名规则的支持。这允许辅助函数名称不是有效的 Handlebars 标识符（例如 {{ one.two }}）。这种命名在 Handlebarsjs 中不受支持，将会破坏兼容性。

区域

• 编译时间

示例

[Fact]
public void HelperWithDotSeparatedName()
{
    var source = "{{ one.two }}";
    var handlebars = Handlebars.Create();
    handlebars.Configuration.Compatibility.RelaxedHelperNaming = true;
    handlebars.RegisterHelper("one.two", (context, arguments) => 42);

    var template = handlebars.Compile(source);
    var actual = template(null);
    
    Assert.Equal("42", actual);
}

HtmlEncoder

用于在旧版 Handlebars.Net 和标准 Handlebars 规则（或自定义实现）之间切换。
对于 Handlebars.Net 2.x.x，HtmlEncoderLegacy 是默认的。

HtmlEncoder
实现标准 Handlebars 规则。

HtmlEncoderLegacy
不会编码
=（等于）
`（反引号）
'（单引号）

将编码非 ASCII 字符 �，�，...
为 HTML 实体（<，â，ß，...）。

区域

• 运行时

示例

[Fact]
public void UseCanonicalHtmlEncodingRules()
{
    var handlebars = Handlebars.Create();
    handlebars.Configuration.TextEncoder = new HtmlEncoder();

    var source = "{{Text}}";
    var value = new { Text = "< �" };

    var template = handlebars.Compile(source);
    var actual = template(value);
            
    Assert.Equal("&lt; �", actual);
}

性能

编译

与渲染相比，编译是一个相当密集的过程。虽然两者都是在毫秒级别测量的，但编译所占用的时间最多。因此，通常最好是只编译一次并将其缓存的结果函数用于重用的生命周期。

渲染

几乎所有的时间都花在将值与模型解析的例程中。不同类型的对象作为模型使用时具有不同的性能特征。

模型类型

• 绝对最快的模型是 IDictionary（微秒）。
• 其次是 POCO（对于平均大小的模板和模型通常需要几毫秒），它使用传统的反射并且相当快。
• 动态对象上的渲染速度开始变慢（到几十毫秒或更多）。
• 最慢的（高达几百毫秒或更差）往往是具有自定义类型实现的对象（例如 ICustomTypeDescriptor），这些对象不适用于重量级反射。

未来路线图

待定

贡献

欢迎拉取请求！指南相当直接

• 只添加 Mustache / Handlebars 规范中已有的功能
• 避免使用 .NET BCL 之外的外部依赖项
• 保持跨平台兼容性（.NET/Mono；Windows/OSX/Linux 等）
• 遵循既定的代码格式