工作原理

Excel 是模板，xl3 来执行它。

在 Excel 中设计布局并绑定数据，xl3 即可生成文档。并排查看原始数据 → 模板 → 输出结果。

查看数据关联

悬停或通过键盘聚焦字段以查看关联。点击固定，再次点击或按 Esc 取消。

请选择字段

每次传入的原始数据

data.xlsx每次运行都会变化的转换前数据

	A	B	C	D
1
2
3
4
5
6
7
8

Sheet1

以 .xlsx 或 JSON 传入每次变化的客户、金额、负责人等数据。这些是尚未应用模板的输入数据。

在工作簿中声明转换

template.xlsx可执行的 Excel 模板

	A	B	C	D	E
1	Customer Renewal Report
2
3
4
5
6
7
8

Report

在 Excel 中设计标题背景色、字体、边框和合并单元格，并在需要填入数据的单元格中编写 XTL {{ … }}。

新数据，相同格式的文档

result.xlsx已渲染的工作簿，格式保留

	A	B	C	D	E
1	Customer Renewal Report
2
3
4
5
6
7
8

Report

即使数据发生变化，模板中的标题背景色、字体、合并单元格、边框和数字格式仍保持不变。

基于职责的自动化

把文档改动移出部署队列。

大多数 Excel 自动化工具让开发者更快。xl3 追求的是另一种结果：让操作者接手过去需要开发者才能完成的文档改动。当每个业务伙伴都需要自己的格式时，让一位工程师逐个实现、每次变更再重改一遍，就会成为瓶颈。

xl3 是在一项运行了数月的内部服务中打磨出来的。在那段时间里，非开发者直接在 Excel 中维护模板和转换规则，而开发者几乎只专注于运行时。真正的削减不只是代码量，而是必须由开发者来做的工作量本身。

开发者

拥有运行时：引擎行为、校验、集成、部署与可靠性。

runtime

操作者

拥有模板：布局、列、重复规则、输出格式以及文档专属逻辑——直接在 Excel 中编辑。

template.xlsx

业务方

直接使用完成的工作簿，无需等待每一次重复性文档改动都变成一次发布。

result.xlsx

xl3 并不打算取代开发者。开发者拥有运行时，操作者拥有模板；文档自动化不再是开发者专属的任务，而成为组织的一种能力。

为什么 Excel 就是模板

别再把报表布局写进一次性脚本里。

ExcelJS、SheetJS、openpyxl 和 Apache POI 是电子表格的 DOM API：强大但冗长。当报表的布局、样式、合并单元格和循环都写进代码后，每一次设计改动——新增一列、移动一处小计、重排表头——都会变成一次部署。

xl3 把这份反复出现的契约搬回 Excel。工作簿本身就是视图，XTL 让它变得可执行，而应用只需提供数据并运行引擎。模板就是一个普通的 .xlsx——没有宏，也没有厂商云——因此你可以对它做 diff、在 Pull Request 中审阅，并交给一个从没听说过 xl3 的人。

开放标准，而非一个库

一份规范、一套一致性套件，以及一个参考实现。

xl3 被定义为一个由三部分组成、与实现无关的开放标准。XTL 表面刻意保持精简，让模板既便于人阅读，也便于 AI 起草。

规范（xl3 + XTL）

规范性定义：xl3 工作簿格式，以及它小巧的内嵌表达式语言 XTL。只有当某个函数的值必须在工作簿写出之前确定时，它才存在于 XTL 中（ADR-0043）。

spec/

一致性套件

语言中立的一致性夹具，每个实现都要运行以证明自身合规。契约在于这套语料库，而非任何单一实现——移植必须与之匹配。

conformance/

参考实现

@xl3-lang/xl3（TypeScript）可在浏览器和 Node 中运行。它很有用，但并非规范——Rust/WASM 与 Python 移植正在进行中。

@xl3-lang/xl3

XTL 0.1 提供 79 ADRs 与 171 conformance fixtures，在 Stage 2 全部通过。TypeScript 参考实现发布于 @xl3-lang/xl3——移植指南记录了这份契约，使其他语言的移植也能与之对齐。

对比

同一个问题，不同的形态。

方案	擅长	取舍
xl3	声明式的 Excel 模板执行。工作簿已经存在，xl3 用数据来运行它。	发布候选版；单一维护者；1.0 契约将在 2026-11-28 前进行技术稳定性验证。
Workbook APIs (ExcelJS, SheetJS, openpyxl, POI)	从应用代码进行底层或全功能的工作簿生成。	布局、样式、合并、循环和业务规则都变成了代码。非开发者无法安全地编辑模板。
Python / VBA scripts	贴近现有电子表格的快速一次性自动化。	规则存在于代码或某位维护者的记忆中；布局变更仍需改代码。
Power Query / Office Scripts	Excel 生态内的 Microsoft 365 工作流与数据整形。	绑定租户；工作流规则不会随工作簿一起迁移。
Template engines (JXLS, xltpl, jsreport xlsx)	从类电子表格模板进行服务端报表生成。	有价值的先行经验，但通常绑定单一运行时，也没有定位为小巧、可移植的 Excel 规则格式。
Doc-gen SaaS (Plumsail, Conga, Formstack)	托管式文档工作流、集成、审批与分发。	规则存在于厂商服务中，而不是你可以自行审阅和运行的可移植工作簿模板。
Direct LLM → xlsx	快速的探索性起草、一次性图表。	并非面向重复运营的确定性转换契约；每次运行的样式与合计都会漂移。

开发者 API

把同一套工作流接入你的产品。

传入应用已经保存在内存中的数据，应用 Excel 模板，并取得生成好的 .xlsx。convertJson() 可直接接收 JavaScript 对象，因此不需要源数据文件或中间工作簿。

terminal

$npm install @xl3-lang/xl3

example.ts

import { convertJson } from '@xl3-lang/xl3';

const outputs = await convertJson(templateBuffer, {
  version: 'xl3-source-json/0.1',
  sources: { default: {
    headers: ['Customer', 'Amount'],
    rows: orders.map(o => [o.customer, o.amount]),
  } },
});
// OutputFile[].data → .xlsx Uint8Array

手册 01 — 5 分钟快速上手 · 阅读规范 · 移植指南