模板引擎
这是 协议项目 模板引擎。 rich-text模板在TemplateMark中被定义(要么作为markdown文件,要么作为JSON文档),然后被与JSON数据合并生成出输出文件. 模板可能包含 类型脚本 表达.
资源
核心模板引擎是JSON到JSON的转换,将TemplateMark JSON +协议数据(JSON)转换为AccordMark JSON.
说明:使用
@accordproject/markdown-transform项目将下标模板转换为模板Mark JSON并转换为输出格式(HTML,PDF,DOCX等). 用于命令行使用请使用@accordproject/template-cli。 。 。 .
TemplateMark是一个描述丰富文本模板的文档对象模型,有嵌入式变量,有条件部分,公式等. TemplateMark使用嵌入式TypeScript表达式进行条件和计算.
模板马克和协议马克的格式使用 音乐会 数据建模语言.
在高层次上,模板引擎将模板Mark DOM转换为协议Mark DOM,评价有条件的节和公式的TypeScript表达式,并用所提供的协议数据的可变值来替换可变引用.
执行管道概览
在内部,模板引擎通过结构化执行管道评价模板:
-
类型验证
TemplateMark JSON文件和收到的协议数据根据各自的Concerto模型进行验证,以确保结构和类型正确. -
类型脚本汇编
嵌入式类型脚本表达式(如条件、条款和公式)使用TemplateMarkToJavaScriptCompiler。 。 。 . -
用户代码评价
在协议生成过程中,使用JavaScriptEvaluator。 。 。 .
评价员支持两项执行战略:evalDangerously()——直接在当前进程内执行JavaScript. 这只应用于可信任的代码或沙盒环境中(如浏览器).evalChildProcess()——执行JavaScript在一个孤立的Node.js子进程,以提高安全和隔离性,被推荐为服务器上不可信的模板内容.
-
协议马克生成
TemplateMark文档被切换,评估值被插入到文档结构中,并生成了AccordMark JSON文档. -
输出验证
生成的协议马克文档在返回前被验证 .
这种分层结构确保类型安全、确定模板逻辑的执行以及运行时间评价期间的隔离.
你好,世界模板
让我们创造最简单的模板 想象,臭名昭著"你好世界"!
此测试的代码为: https://github.com/accordproject/template-engine/blob/main/test/helloWorld.ts 页面存档备份,存于互联网档案馆
模板数据模型
首先在Concerto语法中创建模板数据模型. 数据模型定义了要与模板合并的数据的结构. 在这种情况下,模板模型包含一个属性 message 类型 String需要财产(不是 optional) (中文(简体) ).
namespace [email protected]
@template
concept TemplateData {
o String message
}
TemplateMark( 延长标记)
下一个定义模板的模板 Mark 。 这样的话,就是普通文字世界 "Hello" 后面是空格,然后是变量 message 接下来是 "."。 。 。 .
Hello {{message}}.
请注意,在这种情况下,模板是使用扩展的标记下语法(富文本有嵌入变量等)定义的. 这个
@accordproject/markdown-transform套件用于将标记降为模板Mark JSON,供模板引擎使用.
从数据生成协议马克( JSON)
定义一个 实例 会 议 日 程 和 议 程 [email protected] 数据模型。 在此情况下,确定 message 属性到字符串“世界”.
const data = {
$class: '[email protected]',
message: 'World',
};
产出协议马克(JSON)
当TemplateMark和数据JSON被传递到Template Engine上时,它就将两者合并起来,在这种情况下,只是简单地替换了引用 message 变量,并生成 AccordMark JSON 文档.
然后,可将本协议的Mark JSON文件转交给 @accordproject/markdown-transform 用于转换到下标、PDF、HTML的模块.
{
"$class": "[email protected]",
"xmlns": "http://commonmark.org/xml/1.0",
"nodes": [
{
"$class": "[email protected]",
"nodes": [
{
"$class": "[email protected]",
"nodes": [
{
"$class": "[email protected]",
"text": "Hello "
},
{
"$class": "[email protected]",
"value": "World",
"name": "message",
"elementType": "String"
},
{
"$class": "[email protected]",
"text": "."
}
]
}
]
}
]
}
下一步
"Hello World"的例子只是刮了可以完成的表面! TemplateMark可以定义可选部分,有条件部分,TypeScript公式/计算,甚至参考外部数据.
参见 满 详情请举出例子.
更详细的语法文档即将到来! 阅读现有文档: https://docs.accordproject.org/docs/markup-templatemark.html 页面存档备份,存于互联网档案馆
为什么要创建新的模板引擎 ?
有许多巨大的开源模板引擎可用,例如 胡子, (中文(简体) ), 处理栏 或者说 EJS (英语),那么为什么还要创造另一个呢?
1. 输入和输出格式不可知论
大部分的模板引擎都是基本的 基于文本 ——即将模板作为文本字符串,被颂"查找并替换"的机器. 这种方法在模板的输入格式(比如DOCX文件)和模板引擎的输出之间建立了耦合,在DOCX模板的情况下,模板引擎必须是DOCX文件. 这使得支持多种输入和输出格式变得困难.
Agree Project模板引擎会打破模板输入格式和引擎输出格式之间的耦合,将数据格式转换移出核心模板引擎. 引擎层面的模板为TemplateMark JSON文档,模板引擎的输出为AccordMark JSON文档. 单独的库用于将源模板转换为TemplateMark JSON,或者将AccordMark JSON转换为输出格式.
这种灵活性可以创建一个可被标记下模板,用于创建HTML,PDF或DOCX. 人们甚至可以想象使用DOCX模板来创建HTML或PDF文件,或其他情景.
2. TemplateMark 作为定义格式
TemplateMark JSON是一个定义明确的文件格式,指可以创建强大的模板编辑器来定义它:包括用于定义条件区段的部件和用户经验,以及公式,并提供模板预览和综合测试. 我们认为,模板编辑比文字处理更接近编程.
我们鼓励这个领域的社区和商业创新!
3. 充分逻辑支持
与一些禁止或尽量减少模板中逻辑的诱导系统不同,Accord Project模板完全包含可能包含复杂逻辑的模板:有条件的逻辑来决定要包含什么文本,甚至计算,例如根据抵押期限,金额和利率来计算抵押贷款的月付款.
4. 类型安全
鉴于模板能够包含逻辑,必须确保模板 保险 - 即当一个模板与结构良好的数据合并时,保证产生结构良好的输出.
太多的诱导引擎在运行时以不可预测的方式出故障,或者在提交数据时静悄悄地产生无效输出——这对企业的使用来说是不可接受的.
因此,项目模板 强型。模板中的逻辑用 类型脚本. TypeScript是一种很强型的通用编程语言,由充满活力的开源和企业社区支持. TypeScript 编译为 JavaScript,以方便大多数平台的执行.
5. 数据模型
带有模板变量的丰富文本与 音乐会数据模型. Concerto数据模型定义了模板所需数据的结构,用于静态地编译模板并验证类型安全性,在运行时也用于确保所接入的数据结构完善.
6. 汇编
模板可能被静态编译到TypeScript程序,强制进行类型安全,确保运行时不需要不安全的代码评价("eval"),并放宽对应用程序的整合.
模板编译器是一个单独的项目,在这里托管: https://github.com/accordproject/template-compiller 互联网档案馆的存檔,存档日期2013-12-21
安装
请注意,本模块主要针对工具作者,或开发者将模板引擎嵌入应用程序中. 关于命令行的使用,请参见 @accordproject/template-cli 软件包,可以执行一个完整的管道,将下调模板加上JSON数据转换为支持的输出格式,如HTML、DOCX或PDF.
npm install @accordproject/template-engine --save
要求节点.js >= 22.
浏览器使用量
软件包发布时有两个切入点:
lib/index.js——节点js建设(tsc输出,通过lib/index.d.ts) (中文(简体) ).umd/template-engine.js——预建的UMD浏览器捆绑(参考:browser字段,所以捆绑者会自动把它捡起来用于网页构建).
完全作者和运行的循环作品 在浏览器中 分析模板到模板Mark,
类型检查,将其嵌入式类型Script逻辑编译为JavaScript,并评价它——哪个
是什么权力 模板播放场用于
方便的捆绑也再出口 ModelManager (音乐会)和 TemplateMarkTransformer
因此,一个单捆可以运行整个 model -> template -> agreement 流动
一个协奏曲实例:
<script src="https://unpkg.com/@accordproject/template-engine/umd/template-engine.js"></script>
<script>
const { ModelManager, TemplateMarkTransformer, TemplateMarkInterpreter } = window['template-engine'];
const modelManager = new ModelManager();
modelManager.addCTOModel('namespace [email protected]\n@template\nconcept TemplateData { o String name }');
const templateMark = new TemplateMarkTransformer()
.fromMarkdownTemplate({ content: 'Hello {{name}}!' }, modelManager, 'contract');
const engine = new TemplateMarkInterpreter(modelManager, {});
const agreement = await engine.generate(templateMark, { $class: '[email protected]', name: 'World' });
</script>
关于浏览器限制的说明 :
- 进口的逻辑 任意 第三方包必须作为 编译归档 (JavaScript逻辑,已捆绑的依赖性——由Node.js生产出离线). 在浏览器中, 源文件 (TypeScript logical) 根据一组固定的被支持的运行时间依赖性来编译.
Template.fromDirectory()编号 :fromUrl()和子进程逻辑评价是仅节点 浏览器装入模板通过Template.fromArchive(buffer)并使用默认的流程评估器.
浏览器捆绑由 Playwright 测试在 e2e/ 工作空间, 负载
umd/template-engine.js 变成无头铬并运行一个真正的 generate()。 。 。 .
LLM 提供者
可选 LLM 执行器 通过官方与供应商交谈 SDKs (英语). 这些是 可选同伴依赖关系 ——没有安装模板 因此,为您使用的每个供应商安装 SDK :
| 提供者 | 软件包 |
|---|---|
anthropic | @anthropic-ai/sdk |
openai, (中文(简体) ), ollama, (中文(简体) ), openai-compatible | openai |
groq | groq-sdk |
google | @google/genai |
mistral | @mistralai/mistralai |
openrouter | @openrouter/sdk |
npm install @anthropic-ai/sdk
在Node.js中,SDK在第一次使用时被包名加载. Bundlers (Vite, web package,.) 无法使用
解决该运行时间查询, 因此浏览器应用程序应该通过 sdkLoaders - 单字 import()
他们支持的每个提供者——所以他们的捆绑机包括SDK:
const processor = new TemplateArchiveProcessor(template, llmConfig, {
anthropic: () => import('@anthropic-ai/sdk'),
openai: () => import('openai'), // also used by `ollama` and `openai-compatible`
});
同样的装载器被接受 new LLMExecutor(template, config, sdkLoaders) 财务报告和审定财务报表
createReasoner(providerConfig, sdkLoaders)。 。 。 .
这个 openai SDK( 也由 ollama 财务报告和审定财务报表 openai-compatible)和 @anthropic-ai/sdk SDK 软件
拒绝在浏览器中运行, 除非提供者配置选择使用
clientOptions: { dangerouslyAllowBrowser: true }。只有当您接受 API 密钥时才会这样做
任何使用此页面的人都可以看到,例如,用户提供自己的密钥;否则就呼叫
服务器的提供者.
许可证
Accord Project源代码文件在位于LICENSE文件的Apache许可证2.0版本(Apache-2.0)下提供. 项目文件文件根据创用CC-BY-4.0国际许可证提供 http://creativecommons.org/licenses/by/ 4.0/ 页面存档备份,存于互联网档案馆。 。 。 .