Budibase 字符串模板引擎全解析：基于 Handlebars 的跨端模板系统实战指南

Budibase 字符串模板引擎全解析基于 Handlebars 的跨端模板系统实战指南【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibasebudibase/string-templates是 Budibase 平台中统一负责字符串模板渲染的核心包Builder 设计器、客户端页面与服务端自动化共用同一套模板能力。本文以该包的 README 为主体结合源码实现系统讲解其模板语法、九大类 Helper、日期格式化、核心 API 与内部处理管线帮助你直接在自己的模板字符串中运用{{...}}表达式、条件块与数组迭代并理解每一次渲染背后发生的预处理、Helper 注册与后处理过程。一、包定位一套模板三端共用Budibase 是一个低代码应用构建平台其页面、自动化、邮件通知等场景大量依赖模板字符串 上下文数据的渲染方式。string-templates包正是为此设计的公共基础设施位于 packages/string-templates/模板引擎内核为 HandlebarsMustache 的逻辑增强扩展具备{{variable}}、{{#if}}、{{#each}}等能力在 Handlebars 之上通过budibase/handlebars-helpers注册了一批扩展 Helper覆盖数学、数组、字符串、比较、URL、正则等常见操作包以 UMD 形式构建既能被 Node 服务端worker/server引用也能被浏览器端builder/client直接加载。从 package.json 可以看到其依赖组合handlebars4.7.9 作为引擎、budibase/handlebars-helpers提供扩展 Helper、dayjs承担日期解析与格式化取代了传统 moment 方案显著降低打包体积。二、九大 Helper 集合官方没有全部引入只注册了精选子集README 明确指出并没有实现 handlebars-helpers 包提供的全部 Helper只挑选了对 Budibase 场景有价值的 9 个集合。这一点在 helpers/constants.ts 中得到印证——源码中的EXTERNAL_FUNCTION_COLLECTIONS仅包含export const EXTERNAL_FUNCTION_COLLECTIONS [ math, array, number, url, string, comparison, object, regex, uuid, ]注册逻辑在 helpers/external.ts遍历这些集合调用helperscollection将 Helper 挂载到 Handlebars 实例同时跳过与内置 Helper 重名的条目如if、each、with等见HelperFunctionBuiltin。1. Math —— 数值运算用于对数字执行逻辑运算avg、add、abs、ceil、floor、divide、multiply、subtract、modulo、round、sum、random、remainder等。典型用法{{ add 1 2 }} - 3 {{ avg 1 2 3 4 5 }} - 3 {{ round 10.3 }} - 10 {{ modulo 10 5 }} - 02. Array —— 数组操作对数组进行切片、拼接、迭代、过滤、排序。README 强调这类 Helper 在自动化中非常实用{{ after [a,b,c,d] 2 }} - c,d {{ before [a,b,c,d] 3 }} - a,b {{ first [1,2,3,4] 2 }} - 1,2 {{ last [1,2,3] }} - 3 {{ join array - }} - 以 - 连接成字符串 {{#forEach array}} {{name}} {{/forEach}} - 迭代数组forEach是典型的块级迭代 Helper块内会暴露index、total、isFirst、isLast等变量同时index作为 Handlebars 私有变量可用。3. Number —— 数字展示格式化与 Math 不同Number 集合侧重把数字转成适合展示的格式bytes字节单位、addCommas千分位、toPrecision精度、toFixed、toExponential、toAbbr缩写、phoneNumber电话格式{{ addCommas 1000000 }} - 1,000,000 {{ bytes 1386 1 }} - 1.4 kB {{ toFixed 1.1234 2 }} - 1.124. URL —— URL 处理用于构建自动化中要请求的 URLencodeURI、escape、decodeURI、stripQueryString、stripProtocol、urlResolve、urlParse{{ encodeURI https://myurl?Hello There }} - https%3A%2F%2Fmyurl%3FHello%20There {{ stripQuerystring https://myurl/api/test?foobar }} - https://myurl/api/test {{ stripProtocol https://myurl/api/test }} - //myurl/api/test5. String —— 字符串构建与展示这是日常使用最频繁的集合append、prepend、camelcase、capitalize、capitalizeAll、downcase、upcase、lowercase、uppercase、ellipsis、truncate、trim、replace、remove、split、titleize、sentence、pascalcase、snakecase、dashcase、startsWith、occurrences等{{ append index .html }} - index.html {{ camelcase foo bar baz }} - fooBarBaz {{ ellipsis foo bar baz 7 }} - foo bar… {{ remove a b a b a b a }} - b b b {{ uppercase aBcDef }} - ABCDEF6. Comparison —— 条件逻辑主要用于按条件构造字符串是条件块{{#gte score 50}}的主力and、or、not、eq、is、isnt、gt、gte、lt、lte、compare、contains、default、has、ifEven、ifOdd、ifNth、isTruthy、isFalsey等绝大多数支持块级与内联两种用法{{#and a b}}both{{else}}no{{/and}} {{#gte 4 3}}greater or equal{{else}}less{{/gte}} {{#contains [a,b,c] d}}found{{else}}not found{{/contains}}7. Object —— 对象解析与 JSON 输出将对象转为 JSON 字符串便于在模板中输出结构化数据。源码在 helpers/index.ts 中直接注册为new Helper(HelperFunctionNames.OBJECT, (value: any) { return new Handlebars.SafeString(JSON.stringify(value)) })测试用例 helpers.spec.ts 验证了其行为{{ object obj }} - {a:1}8. Regex —— 正则测试对字符串执行正则匹配可用于条件语句{{#match foobar foo}}matched{{else}}not{{/match}}9. Date —— 日期格式化基于 moment 的helper-date改造而来可把 ISO/时间戳日期格式化为人类可读文本{{ date dateProperty DD-MM-YYYY }}需要注意源码中的日期实现并未使用 moment而是以 dayjs 重写了helper-date的逻辑见 helpers/date.ts 头部注释原因有二原包同时依赖 moment 与 date.js 在简单语法上产生怪异 bug换用 dayjs 后大幅削减 bundle 体积。该文件额外注册了duration、difference、durationFromNow三个时间差值/时长 Helper默认格式为MMMM DD, YYYY。三、日期格式化语法本包采用标准的日期时间格式化记号下表完整摘录自 READMEYYYY、YY、Y、Q、M/MM、MMM/MMMM、D/DD、Do、DDD/DDDD、X、x输入示例描述YYYY20144 位或 2 位年份。注意严格模式下只有 4 位可解析YY142 位年份Y-25任意位数并带正负号的年份Q1..4年份季度。会把月份设为该季度首月M MM1..12月份数字MMM MMMMJan..December由 moment.locale() 设定的语言环境下的月份名D DD1..31月份中的第几天Do1st..31st带序数后缀的日DDD DDDD1..365一年中的第几天X1410715640.579Unix 时间戳秒x1410715640579Unix 毫秒时间戳从源码看dateHelper 支持更多细节不传参数时返回当前时间按默认格式输出传入字符串时区参数如utc会切换到 UTC否则使用dayjs.tz.guess()推测的本地时区pattern传空字符串时返回toISOString()结果。四、模板格式内联表达式与条件/迭代块模板系统支持两种主要写法。4.1 单语句类 MustacheHello Im building a {{uppercase adjective}} string with Handlebars!给定上下文{adjective: cool}输出Hello Im building a COOL string with Handlebars!可以看到字符串 Helper 直接把结果嵌入了句子。这类语句还可以用圆括号堆叠多个 Helper{{ uppercase (remove string bad) }}内层remove先移除子串外层uppercase再对结果转大写。4.2 条件块语句Hello Im building a {{ #gte score 50 }}Great{{ else }}Bad{{ /gte }} string with Handlebars!根据上下文变量score与50的比较结果插入Great或Bad。Comparison、String、Array 集合中的部分 Helper 都支持这种条件式块级用法。4.3 迭代块与条件块语法相近但产生循环操作例如forEach数组 Helper{{#forEach orders}}{{name}} - {{total}}{{/forEach}}这正是自动化中对一组记录逐条拼装文本的核心手段。五、核心 API七个主函数 若干进阶能力包的对外使用方式是通过入口 src/index.ts 导出的函数。README 列出的七个主函数如下1.processString(string, object)async异步处理单个模板字符串。给定模板字符串与上下文对象经由预处理pre-processors、Handlebars 渲染、后处理post-processors三步产出结果字符串。从源码看其内部直接委托给processStringSyncexport async function processString(string, context, opts) { return processStringSync(string, context, opts) }2.processObject(object, object)async对对象内所有字符串属性递归执行processString的能力常用于一次处理整份数据/配置。源码 index.ts 会先调用testObject用JSON.stringify探测循环引用存在环会直接抛错防止无限递归然后逐键递归大对象因深度递归可能较慢。3.processStringSync(string, object)同步版字符串处理功能较异步版精简风格类似 Node 的readdirSync。所有 JS 绑定、异步能力在同步模式下不可用。4.processObjectSync(object, object)processObject的同步版本同样递归遍历对象并处理每个字符串属性。5.makePropSafe(string)处理 Handlebars 无法直接访问的属性名。例如Table 1含空格不是合法标识符调用后变为[Table 1]字面量说明符包裹。README 强调对象访问的每一层都应调用此函数即[Table 1].[property name]才是 Handlebars 需要的完整语法。源码实现非常简洁export function makePropSafe(property: any): string { return [${property}].replace([[, [).replace(]], ]) }6.isValid(string)检测给定字符串是否为合法模板返回布尔值。源码 index.ts 的判定方式是直接编译并渲染一次模板捕获 Handlebars 的语法错误信息再通过错误消息特征expecting 等无效特征与cannot read property、undefined等有效特征判断合法性。7.getManifest()返回描述全部 Helper 及其参数的清单 JSON。该文件由脚本从 Helper 元数据生成位于 src/manifest.json为 Builder 设计器提供该 Helper 有哪些参数、示例是什么的自动提示数据例如add的参数为a、b示例{{ add 1 2 }} - 3。进阶能力源码中额外导出的实用函数除 README 列出的七项外源码还提供了一批进阶工具适合在集成开发时使用processJsonStringSync(template, context, opts)专为 JSON 字符串模板设计先把模板中{{...}}块替换为占位 token 以保证 JSON 语法有效再解析、渲染、还原多对象模板如 Mongo 的{filter} {update}会按顶层对象拆分处理注释明确说明失败即关闭策略——多对象模板必须是合法 JSON 对象避免引号破坏导致的操作符注入index.tsencodeJSBinding(javascript)/decodeJSBinding(handlebars)/isJSBinding(handlebars)将任意 JS 代码编码为{{ js base64... }}模板表达式或反向解码这是 Budibase 在前端执行自定义 JS 绑定的机制findHBSBlocks(string)提取字符串中所有{{...}}/{{{...}}}块doesContainString(template, string)/doesContainStrings(template, strings)判断模板中是否存在包含指定词的绑定检测 JS 绑定时会先解码再匹配disableEscaping(string)把{{ name }}形式的双重花括号改写为{{{ name }}}三花括号从而关闭 Handlebars 默认的 HTML 转义由noEscaping处理选项触发convertToJS(hbs)把 Handlebars 模板编译为可执行的 JS 模板字符串用于前端 JS 执行环境。六、渲染管线预处理 → Helper 执行 → 后处理理解processString的完整行为需要看三层处理。渲染入口在 index.ts 的processStringSyncInternal模板编译时注入当前时间戳now与内部选项__opts执行后统一走postprocess/postprocessWithLogs。6.1 预处理Preprocessors定义在 processors/preprocessor.ts按顺序执行四个步骤SWAP_TO_DOT把[Table 1]这类字面量写法自动规范为.[Table 1]点号链访问语法FIX_FUNCTIONS修正{ #gte、{ else、{ /gte等带空格的块语法为{#gte标准写法容忍用户在模板中手写的多余空格NORMALIZE_SPACES将{{多个连续空格规整为{{FINALISE把绝大多数内联语句包装成{{ all ... }}形式——all是包内置的通用 Helper负责统一处理空值输出、对象转 JSON、amp;还原以及、的 HTML 安全转义helpers/index.ts。函数类块语句#、else、/开头不会被包装。此外在createTemplate中还有一个细节如果上下文对象里的键与某个 Helper 重名称为 overlapping helpers会把这些键自动加上./前缀以避免与 Helper 冲突index.ts。6.2 Helper 注册helpers/index.ts 中registerAll分两层完成注册registerMinimum注册包内置 Helper——object对象转 JSON、jsJS 绑定执行、decodeId解码 URL 编码的 ID、all全语句通用包装、literal为后处理留下字面量标记如{{%LITERAL% number-42}}registerAll在最低集基础上追加外部 Helper 集合与date、duration、difference、durationFromNow四个日期增强 Helper。同时包维护两个Handlebars 实例完整实例hbsInstance注册全部 Helper与最小实例hbsInstanceNoHelpers仅registerMinimum。当处理选项noHelpers: true时走最小实例——测试 helpers.spec.ts 验证了{{ avg 1 1 1 }}在noHelpers下输出为空字符串。6.3 后处理Postprocessors定义在 processors/postprocessor.tsCONVERT_LITERALS识别%LITERAL%标记根据标记中携带的类型string、number、boolean、object、js_result把渲染结果还原为对应类型——这正是模板能输出数字、布尔和对象而非纯字符串的关键机制。6.4 处理选项ProcessOptionscreateTemplate中的默认选项index.ts反映了可调行为选项默认值作用noHelpersfalse为true时禁用全部外部 Helper仅保留内置最小集cacheTemplatesfalse为true时按模板字符串 选项缓存编译结果复用模板函数noEscapingfalse为true时把双花括号改为三花括号关闭 HTML 转义escapeNewlinesfalse为true时把换行符替换为\n字面量noFinalisefalse为true时跳过all包装isValid内部使用onlyFound-只处理字符串中已找到的 HBS 块未命中时保留原输入noThrowtrue渲染失败时不抛错返回原始输入七、开发与构建该包与仓库中其他包一样由lerna管理使用Rollup构建Budibase 多数包的标准做法产物为UMD格式以便 Node 与浏览器同时使用同时生成TypeScript 声明文件供 IDE 在引用包时提供代码补全。package.json 中的命令yarn build—— 依次执行tsc --emitDeclarationOnly生成类型声明与rollup -c打包出dist/bundle.cjs、dist/bundle.mjsyarn test—— 运行 Jest 测试套件覆盖各 Helper 的核心行为与若干典型用例。测试文件位于 test/例如 helpers.spec.ts 验证了 object Helper、noHelpers模式、math 的abs/add/avg、array 的after/before/filter/itemAt/join/sort/unique、number 的addCommas/phoneNumber等basic.spec.ts 与 hbsToJs.spec.ts 覆盖基础渲染与 HBS 转 JS 的逻辑yarn dev—— 内部命令由 lerna 在仓库根目录执行yarn dev时调用rollup -cw监听文件变化并持续重建。此外还提供yarn manifest运行 scripts/gen-collection-info.ts 重新生成 Helper 清单 JSON与yarn check:types类型检查。八、典型应用场景与实战要点结合 Budibase 的整体架构这套模板系统主要出现在三类场景自动化节点中的文本/URL 组装利用 Math、Array、URL、String 集合将上游数据拼装为 API 请求地址、通知内容或输出消息页面数据绑定的安全访问通过makePropSafe把Table 1这类带空格的表名/属性名包装为[Table 1]再嵌入模板避免 Handlebars 解析失败Builder 中的 Helper 提示getManifest()返回的清单驱动设计器向用户展示每个 Helper 的参数与示例。实战中还需留意几个来自源码的行为边界同步与异步的能力差异processStringSync是精简功能版JS 绑定等完整能力以异步/后端路径为准index.ts 的注释明确说明循环引用防护processObject/processObjectSync对含环对象直接抛错上下文与 Helper 同名会自动加./前缀消除歧义JS 绑定限制processStringWithLogsSync在后端服务中会被禁用Logging disabled for backend bindings而isJSAllowed()在设置了环境变量NO_JS时会关闭 JS 执行能力utilities.ts。综上string-templates是一个小而全的模板基础设施以 Handlebars 为引擎、以精选 Helper 集合为扩展、以三层处理管线保证输出安全与类型正确并通过 UMD 类型声明兼顾了三端复用与开发体验。无论是阅读 README 快速上手还是深入 src/index.ts、src/helpers/ 与 src/processors/ 理解实现细节都能为你在 Budibase 中编写、调试模板提供完整的知识闭环。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考