前端【免费下载链接】handlebars.jsMinimal templating on steroids.项目地址https://gitcode.com/gh_mirrors/ha/handlebars.js点击查看免费下载本文基于本仓库官方文档 docs/decorators-api.md 展开并结合仓库内编译器、运行时与测试源码进行深度印证。Handlebars.js 的 Decorator装饰器机制允许在块Block执行之前为其附加元数据Metadata或将其包装进自定义行为常用于与包含它的 Helper 通信、或在渲染前建立特定的系统状态。读完本文你将掌握 Decorator 的注册/注销 API、{{* decorator}}与{{#* decorator}}两种模板语法、七个执行期参数的准确含义以及如何参考内置的 inline partial 实现写出既能设置元数据又能包装程序的 Decorator。Decorator 是什么在块执行前注入元数据与行为Decorators 允许对块进行元数据注解或执行前包装。按照 docs/decorators-api.md 的定义它可以用来与包含该块的 Helper 进行通信或者在运行块之前为系统建立特定的状态。例如你可以把一个模板片段标记为异步、为它绑定额外的 partial 命名空间、或统计它被实例化的次数——这些都属于 Decorator 的典型应用场景。从机制上讲Decorator 在块程序Program被实例化时执行此时它接收(program, props, container, context, data, blockParams, depths)七个参数可以对program做两件事直接修改其属性通过props间接完成或返回一个包装了program的新函数。⚠️重要提示来自官方文档Decorators 已被标记为deprecated废弃。官方建议关注 handlebars-lang/handlebars.js #1574 的讨论以了解其未来走向。本文仅用于理解既有代码与历史实现新项目中应谨慎评估是否引入该机制。注册与注销与 Helper 同构的 APIDecorator 的注册方式与 Helper 高度相似核心方法定义在 lib/handlebars/base.js 的HandlebarsEnvironment原型上。官方文档写作 registerDecorators 与 unregisterDecorators仓库源码中的实际方法名为单数形式registerDecorator: function (name, fn) { if (toString.call(name) objectType) { if (fn) { throw new Exception(Arg not supported with multiple decorators); } extend(this.decorators, name); } else { this.decorators[name] fn; } }, unregisterDecorator: function (name) { delete this.decorators[name]; },由此可以看出两个关键行为lib/handlebars/base.js单名注册registerDecorator(name, fn)以名字为键写入this.decorators对象批量注册传入一个对象registerDecorator({ foo: fn, bar: fn2 })即可一次注册多个但批量注册时不允许再传入第二个参数fn否则会抛出异常Arg not supported with multiple decorators该分支行为在 spec/blocks.js 有专门测试覆盖注销unregisterDecorator(name)直接delete对应键。注册的 Decorator 会存放在环境实例的this.decorators集合中并在运行时被合并进container.decorators合并逻辑见 lib/handlebars/runtime.js。registerDecorator/unregisterDecorator的注册与注销往返行为在 spec/blocks.js 中被验证注册后handlebarsEnv.decorators.foo为真注销后变为undefined。默认情况下registerDefaultDecorators会为每个环境注册内置的inlineDecorator见 lib/handlebars/decorators.js。模板语法{{* decorator}}与{{#* decorator}}注册完成后即可在模板中通过友好名称引用 Decorator。官方文档明确指出有两种语法它们是标准 Mustache 语法的衍生形式因此拥有与普通 mustache 完全一致的参数与空白whitespace行为语法形式说明行内装饰Mustache Decorator{{* decorator}}对当前块进行注解/包装不产生输出块装饰Block Decorator{{#* decorator}}...{{/decorator}}包裹一段子模板可在其中传入子内容在解析与编译层面这两种语法由编译器分别处理为Decorator与DecoratorBlock节点见 lib/handlebars/compiler/compiler.js 与 lib/handlebars/compiler/compiler.js。编译时二者都会通过setupFullMustacheParams收集与 mustache 完全一致的参数因此可以携带foo、string等参数以及 hash 参数设置this.useDecorators true标记发射registerDecorator操作码opcode把装饰器名 参数压入指令流。随后的 lib/handlebars/compiler/javascript-compiler.js 中registerDecorator(paramSize, name)会把栈上的fn、props、container、options传给查找到的 Decorator 函数并生成fn decorator(fn, props, container, options) || fn;形式的代码——这一行代码正好印证了文档中Decorator 返回undefined时program保持不变的行为因为|| fn保证了空返回值回落为原始fn。说明编译后主程序与各子程序的 Decorator 会被分别存入templateSpec.main_d与templateSpec[i _d]运行时通过fn.decorator读取见 lib/handlebars/runtime.js 与 lib/handlebars/runtime.js。执行时机与七个参数Decorator 在块程序被实例化时执行。这个时机的关键实现位于 lib/handlebars/runtime.js 的wrapProgram它先构造出包装函数prog随后立即调用executeDecorators把 Decorator 应用上去而executeDecoratorslib/handlebars/runtime.js则是真正调用fn.decorator的地方function executeDecorators(fn, prog, container, depths, data, blockParams) { if (fn.decorator) { let props {}; prog fn.decorator( prog, props, container, depths depths[0], data, blockParams, depths ); Utils.extend(prog, props); } return prog; }注意此处的调用顺序context实参是depths depths[0]即当前最深一层上下文随后依次是data、blockParams、depths。执行完毕后props上设置的任何值都会被Utils.extend(prog, props)合并到最终函数上。官方文档对七个参数的定义如下参数含义program要被包装的块Blockprops用于在最终函数上设置元数据的对象。无论原始函数是否被替换设置在该对象上的值都会出现在最终函数上。元数据应写入props因为直接写入program的值可能被后续包裹program的 Decorator 遮蔽container当前运行时容器runtime containercontext当前上下文。由于 Decorator 运行于包含它的块之前因此这是父级上下文parent contextdata当前的data值blockParams当前的块参数栈block parameters stackdepths当前的上下文栈context stack从 lib/handlebars/runtime.js 的调用序列可以推断props由运行时在每次executeDecorators调用时新建let props {}因此它是每次实例化独立的元数据载体而container则与 lib/handlebars/runtime.js 中构建的运行时容器一致包含helpers、partials、decorators、lookup、escapeExpression等全套运行时能力。两种行为模式设置元数据 vs 返回包装函数文档将 Decorator 的行为归结为两种可以同时使用设置元数据向props对象写入键值运行时会把它们合并到最终函数上。即使 Decorator 没有返回新函数这些元数据也依然生效。返回包装函数返回一个修改过的、把program包裹进特定行为的函数。返回undefinedprogram保持原样对应上文|| fn的回退逻辑。props与直接修改program的关键区别在于遮蔽问题后续可能有其他 Decorator 继续包装program导致你在旧函数上设置的属性被替换掉而写入props的值由executeDecorators在所有Decorator 执行完之后统一extend到最终函数上因此不会被遮蔽。这正是官方文档强调Metadata should be applied using this object的原因。spec中 spec/blocks.js 的测试直接演示了这一行为Decorator 只设置fn.run cess而不返回任何值外层 Helper 通过options.fn() options.fn.run仍能读到元数据并渲染出success。参考实现内置 inline partial 是如何鱼与熊掌兼得的官方文档点名 lib/handlebars/decorators/inline.js 作为同时使用元数据与包装行为的参考实现。其完整源码如下import { extend } from ../utils.js; export default function (instance) { instance.registerDecorator( inline, function (fn, props, container, options) { let ret fn; if (!props.partials) { props.partials {}; ret function (context, options) { // Create a new partials stack frame prior to exec. let original container.partials; container.partials extend({}, original, props.partials); let ret fn(context, options); container.partials original; return ret; }; } props.partials[options.args[0]] options.fn; return ret; } ); }这段代码清晰展示了文档所述的两种模式如何协作元数据props每次调用都会执行props.partials[options.args[0]] options.fn把块内容注册为一个具名 partial名字来自第一个参数options.args[0]并写入props.partials——由于props会被合并回最终函数后续无论函数是否被再次包装这些 partial 都始终存在。包装返回新函数仅在props.partials尚未初始化时即第一次执行创建包装函数。该包装函数在执行原fn之前把props.partials临时合并进container.partials形成一个新的 partials 栈帧执行完毕后再恢复original从而保证 inline partial 只对当前块的作用域可见不会污染外层状态。registerDefaultDecorators在 lib/handlebars/decorators.js 中通过registerInline(instance)将其注册为所有环境的内置能力。行为约束与测试验证关于 Decorator 的参数与上下文访问spec/blocks.js 提供了系统性的行为契约可视为官方文档的补充细则行内装饰mustache decorator{{#helper}}{{*decorator}}{{/helper}}中Decorator 通过fn.run success给块打上标记外层 helper 读取options.fn.run输出successspec/blocks.js块装饰block decorator{{#*decorator}}success{{/decorator}}中Decorator 可以访问options.fn()拿到子模板的渲染结果并挂到fn.run上spec/blocks.js嵌套装饰外层 Decorator 可以读取内层 Decorator 通过props设置的元数据options.fn.nested证明props在嵌套场景下是逐层合并的spec/blocks.js多重装饰同一块上可以叠加多个同名单个 Decorator元数据按执行顺序累加fn.run (fn.run || ) options.fn()spec/blocks.js父级上下文访问{{#helper}}{{*decorator foo}}{{/helper}}中options.args可以拿到foo的值对应文档所说 Decorator 运行于块之前、位于父级上下文spec/blocks.js根程序限制{{*decorator success}}可以拿到字面量参数但{{*decorator foo}}在根程序root program中无法访问变量options.args[0]为undefinedspec/blocks.js——这是使用行内顶层 Decorator 时需要注意的边界。使用示例与最佳实践综合以上 API 与行为约束一个完整的自定义 Decorator 使用流程如下// 1. 注册一个异步标记装饰器 Handlebars.registerDecorator(async, function (fn, props, container, options) { props.async true; // 元数据无论函数是否被替换都保留 return fn; // 保持原块不变也可以返回包装函数 }); // 2. 在模板中使用 // {{#helper}}{{*async}}{{/helper}} // 3. 外层 helper 读取元数据 Handlebars.registerHelper(helper, function (options) { return options.fn.async ? async block : sync block; });遵循官方文档与源码约束推荐的做法是元数据一律写入props不要直接写program以免被后续包装的 Decorator 遮蔽需要包装行为时返回新函数并在新函数内先建立状态、执行fn(context, options)、再恢复状态参考 inline 的 partials 栈帧模式不需要包装时可以不返回值运行时通过|| fn自动保留原始块顶层root program使用{{* decorator}}时注意无法通过options.args读取普通上下文变量只能读取字面量参数鉴于官方已将其标记为 deprecated见 docs/decorators-api.md 开头的弃用声明在引入到新项目前应评估替代方案并关注上游讨论。相关阅读官方文档原文docs/decorators-api.md内置 inline 实现lib/handlebars/decorators/inline.js默认注册入口lib/handlebars/decorators.js注册/注销 APIlib/handlebars/base.js运行时执行链executeDecorators/wrapProgramlib/handlebars/runtime.js、lib/handlebars/runtime.js编译器节点处理lib/handlebars/compiler/compiler.js代码生成阶段lib/handlebars/compiler/javascript-compiler.js行为契约测试spec/blocks.js赞分享前端【免费下载链接】handlebars.jsMinimal templating on steroids.项目地址https://gitcode.com/gh_mirrors/ha/handlebars.js点击查看免费下载相关推荐深度解析macOS文件系统扩展macFUSE架构设计与实战应用指南深度解析macOS文件系统扩展macFUSE架构设计与实战应用指南 macFUSE作为macOS平台上革命性的用户空间文件系统框架为开发者提供了无需编写内核OpenSpec教学视频直观了解规范驱动开发流程的完整指南OpenSpec教学视频直观了解规范驱动开发流程的完整指南 想要掌握AI编程助手的规范驱动开发流程吗OpenSpec教学视频将为你展示如何通过直观的视觉化方开发工具CLIAI 应用工作流自动化Handlebars.js Helper调用指南揭秘自定义函数的完整执行流程Handlebars.js Helper调用指南揭秘自定义函数的完整执行流程 Handlebars.js是一个强大的语义模板引擎它通过 Helper函数调用前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
前端【免费下载链接】handlebars.jsMinimal templating on steroids.项目地址https://gitcode.com/gh_mirrors/ha/handlebars.js点击查看免费下载本文基于本仓库官方文档 docs/decorators-api.md 展开并结合仓库内编译器、运行时与测试源码进行深度印证。Handlebars.js 的 Decorator装饰器机制允许在块Block执行之前为其附加元数据Metadata或将其包装进自定义行为常用于与包含它的 Helper 通信、或在渲染前建立特定的系统状态。读完本文你将掌握 Decorator 的注册/注销 API、{{* decorator}}与{{#* decorator}}两种模板语法、七个执行期参数的准确含义以及如何参考内置的 inline partial 实现写出既能设置元数据又能包装程序的 Decorator。Decorator 是什么在块执行前注入元数据与行为Decorators 允许对块进行元数据注解或执行前包装。按照 docs/decorators-api.md 的定义它可以用来与包含该块的 Helper 进行通信或者在运行块之前为系统建立特定的状态。例如你可以把一个模板片段标记为异步、为它绑定额外的 partial 命名空间、或统计它被实例化的次数——这些都属于 Decorator 的典型应用场景。从机制上讲Decorator 在块程序Program被实例化时执行此时它接收(program, props, container, context, data, blockParams, depths)七个参数可以对program做两件事直接修改其属性通过props间接完成或返回一个包装了program的新函数。⚠️重要提示来自官方文档Decorators 已被标记为deprecated废弃。官方建议关注 handlebars-lang/handlebars.js #1574 的讨论以了解其未来走向。本文仅用于理解既有代码与历史实现新项目中应谨慎评估是否引入该机制。注册与注销与 Helper 同构的 APIDecorator 的注册方式与 Helper 高度相似核心方法定义在 lib/handlebars/base.js 的HandlebarsEnvironment原型上。官方文档写作 registerDecorators 与 unregisterDecorators仓库源码中的实际方法名为单数形式registerDecorator: function (name, fn) { if (toString.call(name) objectType) { if (fn) { throw new Exception(Arg not supported with multiple decorators); } extend(this.decorators, name); } else { this.decorators[name] fn; } }, unregisterDecorator: function (name) { delete this.decorators[name]; },由此可以看出两个关键行为lib/handlebars/base.js单名注册registerDecorator(name, fn)以名字为键写入this.decorators对象批量注册传入一个对象registerDecorator({ foo: fn, bar: fn2 })即可一次注册多个但批量注册时不允许再传入第二个参数fn否则会抛出异常Arg not supported with multiple decorators该分支行为在 spec/blocks.js 有专门测试覆盖注销unregisterDecorator(name)直接delete对应键。注册的 Decorator 会存放在环境实例的this.decorators集合中并在运行时被合并进container.decorators合并逻辑见 lib/handlebars/runtime.js。registerDecorator/unregisterDecorator的注册与注销往返行为在 spec/blocks.js 中被验证注册后handlebarsEnv.decorators.foo为真注销后变为undefined。默认情况下registerDefaultDecorators会为每个环境注册内置的inlineDecorator见 lib/handlebars/decorators.js。模板语法{{* decorator}}与{{#* decorator}}注册完成后即可在模板中通过友好名称引用 Decorator。官方文档明确指出有两种语法它们是标准 Mustache 语法的衍生形式因此拥有与普通 mustache 完全一致的参数与空白whitespace行为语法形式说明行内装饰Mustache Decorator{{* decorator}}对当前块进行注解/包装不产生输出块装饰Block Decorator{{#* decorator}}...{{/decorator}}包裹一段子模板可在其中传入子内容在解析与编译层面这两种语法由编译器分别处理为Decorator与DecoratorBlock节点见 lib/handlebars/compiler/compiler.js 与 lib/handlebars/compiler/compiler.js。编译时二者都会通过setupFullMustacheParams收集与 mustache 完全一致的参数因此可以携带foo、string等参数以及 hash 参数设置this.useDecorators true标记发射registerDecorator操作码opcode把装饰器名 参数压入指令流。随后的 lib/handlebars/compiler/javascript-compiler.js 中registerDecorator(paramSize, name)会把栈上的fn、props、container、options传给查找到的 Decorator 函数并生成fn decorator(fn, props, container, options) || fn;形式的代码——这一行代码正好印证了文档中Decorator 返回undefined时program保持不变的行为因为|| fn保证了空返回值回落为原始fn。说明编译后主程序与各子程序的 Decorator 会被分别存入templateSpec.main_d与templateSpec[i _d]运行时通过fn.decorator读取见 lib/handlebars/runtime.js 与 lib/handlebars/runtime.js。执行时机与七个参数Decorator 在块程序被实例化时执行。这个时机的关键实现位于 lib/handlebars/runtime.js 的wrapProgram它先构造出包装函数prog随后立即调用executeDecorators把 Decorator 应用上去而executeDecoratorslib/handlebars/runtime.js则是真正调用fn.decorator的地方function executeDecorators(fn, prog, container, depths, data, blockParams) { if (fn.decorator) { let props {}; prog fn.decorator( prog, props, container, depths depths[0], data, blockParams, depths ); Utils.extend(prog, props); } return prog; }注意此处的调用顺序context实参是depths depths[0]即当前最深一层上下文随后依次是data、blockParams、depths。执行完毕后props上设置的任何值都会被Utils.extend(prog, props)合并到最终函数上。官方文档对七个参数的定义如下参数含义program要被包装的块Blockprops用于在最终函数上设置元数据的对象。无论原始函数是否被替换设置在该对象上的值都会出现在最终函数上。元数据应写入props因为直接写入program的值可能被后续包裹program的 Decorator 遮蔽container当前运行时容器runtime containercontext当前上下文。由于 Decorator 运行于包含它的块之前因此这是父级上下文parent contextdata当前的data值blockParams当前的块参数栈block parameters stackdepths当前的上下文栈context stack从 lib/handlebars/runtime.js 的调用序列可以推断props由运行时在每次executeDecorators调用时新建let props {}因此它是每次实例化独立的元数据载体而container则与 lib/handlebars/runtime.js 中构建的运行时容器一致包含helpers、partials、decorators、lookup、escapeExpression等全套运行时能力。两种行为模式设置元数据 vs 返回包装函数文档将 Decorator 的行为归结为两种可以同时使用设置元数据向props对象写入键值运行时会把它们合并到最终函数上。即使 Decorator 没有返回新函数这些元数据也依然生效。返回包装函数返回一个修改过的、把program包裹进特定行为的函数。返回undefinedprogram保持原样对应上文|| fn的回退逻辑。props与直接修改program的关键区别在于遮蔽问题后续可能有其他 Decorator 继续包装program导致你在旧函数上设置的属性被替换掉而写入props的值由executeDecorators在所有Decorator 执行完之后统一extend到最终函数上因此不会被遮蔽。这正是官方文档强调Metadata should be applied using this object的原因。spec中 spec/blocks.js 的测试直接演示了这一行为Decorator 只设置fn.run cess而不返回任何值外层 Helper 通过options.fn() options.fn.run仍能读到元数据并渲染出success。参考实现内置 inline partial 是如何鱼与熊掌兼得的官方文档点名 lib/handlebars/decorators/inline.js 作为同时使用元数据与包装行为的参考实现。其完整源码如下import { extend } from ../utils.js; export default function (instance) { instance.registerDecorator( inline, function (fn, props, container, options) { let ret fn; if (!props.partials) { props.partials {}; ret function (context, options) { // Create a new partials stack frame prior to exec. let original container.partials; container.partials extend({}, original, props.partials); let ret fn(context, options); container.partials original; return ret; }; } props.partials[options.args[0]] options.fn; return ret; } ); }这段代码清晰展示了文档所述的两种模式如何协作元数据props每次调用都会执行props.partials[options.args[0]] options.fn把块内容注册为一个具名 partial名字来自第一个参数options.args[0]并写入props.partials——由于props会被合并回最终函数后续无论函数是否被再次包装这些 partial 都始终存在。包装返回新函数仅在props.partials尚未初始化时即第一次执行创建包装函数。该包装函数在执行原fn之前把props.partials临时合并进container.partials形成一个新的 partials 栈帧执行完毕后再恢复original从而保证 inline partial 只对当前块的作用域可见不会污染外层状态。registerDefaultDecorators在 lib/handlebars/decorators.js 中通过registerInline(instance)将其注册为所有环境的内置能力。行为约束与测试验证关于 Decorator 的参数与上下文访问spec/blocks.js 提供了系统性的行为契约可视为官方文档的补充细则行内装饰mustache decorator{{#helper}}{{*decorator}}{{/helper}}中Decorator 通过fn.run success给块打上标记外层 helper 读取options.fn.run输出successspec/blocks.js块装饰block decorator{{#*decorator}}success{{/decorator}}中Decorator 可以访问options.fn()拿到子模板的渲染结果并挂到fn.run上spec/blocks.js嵌套装饰外层 Decorator 可以读取内层 Decorator 通过props设置的元数据options.fn.nested证明props在嵌套场景下是逐层合并的spec/blocks.js多重装饰同一块上可以叠加多个同名单个 Decorator元数据按执行顺序累加fn.run (fn.run || ) options.fn()spec/blocks.js父级上下文访问{{#helper}}{{*decorator foo}}{{/helper}}中options.args可以拿到foo的值对应文档所说 Decorator 运行于块之前、位于父级上下文spec/blocks.js根程序限制{{*decorator success}}可以拿到字面量参数但{{*decorator foo}}在根程序root program中无法访问变量options.args[0]为undefinedspec/blocks.js——这是使用行内顶层 Decorator 时需要注意的边界。使用示例与最佳实践综合以上 API 与行为约束一个完整的自定义 Decorator 使用流程如下// 1. 注册一个异步标记装饰器 Handlebars.registerDecorator(async, function (fn, props, container, options) { props.async true; // 元数据无论函数是否被替换都保留 return fn; // 保持原块不变也可以返回包装函数 }); // 2. 在模板中使用 // {{#helper}}{{*async}}{{/helper}} // 3. 外层 helper 读取元数据 Handlebars.registerHelper(helper, function (options) { return options.fn.async ? async block : sync block; });遵循官方文档与源码约束推荐的做法是元数据一律写入props不要直接写program以免被后续包装的 Decorator 遮蔽需要包装行为时返回新函数并在新函数内先建立状态、执行fn(context, options)、再恢复状态参考 inline 的 partials 栈帧模式不需要包装时可以不返回值运行时通过|| fn自动保留原始块顶层root program使用{{* decorator}}时注意无法通过options.args读取普通上下文变量只能读取字面量参数鉴于官方已将其标记为 deprecated见 docs/decorators-api.md 开头的弃用声明在引入到新项目前应评估替代方案并关注上游讨论。相关阅读官方文档原文docs/decorators-api.md内置 inline 实现lib/handlebars/decorators/inline.js默认注册入口lib/handlebars/decorators.js注册/注销 APIlib/handlebars/base.js运行时执行链executeDecorators/wrapProgramlib/handlebars/runtime.js、lib/handlebars/runtime.js编译器节点处理lib/handlebars/compiler/compiler.js代码生成阶段lib/handlebars/compiler/javascript-compiler.js行为契约测试spec/blocks.js赞分享前端【免费下载链接】handlebars.jsMinimal templating on steroids.项目地址https://gitcode.com/gh_mirrors/ha/handlebars.js点击查看免费下载相关推荐深度解析macOS文件系统扩展macFUSE架构设计与实战应用指南深度解析macOS文件系统扩展macFUSE架构设计与实战应用指南 macFUSE作为macOS平台上革命性的用户空间文件系统框架为开发者提供了无需编写内核OpenSpec教学视频直观了解规范驱动开发流程的完整指南OpenSpec教学视频直观了解规范驱动开发流程的完整指南 想要掌握AI编程助手的规范驱动开发流程吗OpenSpec教学视频将为你展示如何通过直观的视觉化方开发工具CLIAI 应用工作流自动化Handlebars.js Helper调用指南揭秘自定义函数的完整执行流程Handlebars.js Helper调用指南揭秘自定义函数的完整执行流程 Handlebars.js是一个强大的语义模板引擎它通过 Helper函数调用前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
