ToolJet Generate File 动作详解动态构造 CSV、Text、PDF 文件并触发下载【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetGenerate file 是 ToolJet 内置的一种客户端动作Action用于在运行时根据动态数据即时构造文件并直接触发浏览器下载典型场景包括一键导出表格数据为 CSV、生成纯文本报告、以 PDF 表格形式输出查询结果等。本文基于官方文档 generate-file.md 的完整配置说明展开并结合 前端事件调度实现、文件生成核心库 与 CSV 序列化实现讲清楚每种文件类型对 Data 字段的格式要求、默认值行为以及底层生成原理读完后可直接在 App Builder 和 RunJS 中正确使用该动作。动作定位与执行链路从官方文档描述看该动作允许你在运行时构造文件并让用户下载。在前端源码中它对应事件类型generate-file与runQuery、showAlert、goToApp等并列注册为可在 RunJS 中调用的动作之一见 actions.js 中的动作清单。事件分发逻辑位于 eventsSlice.jscase generate-file: { const data getResolvedValue(event.data, customVariables, moduleId) || []; const fileName getResolvedValue(event.fileName, customVariables, moduleId) || data.txt; const fileType getResolvedValue(event.fileType, customVariables, moduleId) || csv; const fileData { csv: generateCSV, plaintext: (plaintext) plaintext, pdf: (pdfData) pdfData, }fileType; return generateFile(fileName, fileData, fileType); }这段代码揭示了三个源码级事实所有字段都经过变量解析data、fileName、fileType均通过getResolvedValue解析因此支持{{...}}动态变量引用存在隐式默认值Data 为空时回退为[]File name 为空时回退为data.txtType 为空时回退为csv文本类型的内部标识是plaintext而非text虽然 UI 选项表中 Type 写作CSV、Text、PDF但序列化映射表的键是csv/plaintext/pdf这一点在 RunJS 中调用时尤为关键见下文。配置项全解官方文档给出了如下四个选项本文逐一补充其在源码中的落地行为Option说明源码层面的行为Type要生成的文件类型CSV、Text、PDF内部取值为csv/plaintext/pdf决定 Data 的序列化方式未填时默认为csvFile name生成文件的名称未填时默认为data.txt支持变量插值Data用于构造文件的数据格式随文件类型而定为空时默认为[]支持{{...}}动态表达式Debounce默认空填入数字表示该毫秒数后才执行动作如300事件节流配置避免高频事件如连续输入反复触发文件下载其中 Debounce 字段对交互密集型场景很有价值例如在输入事件上挂载 generate file 时填入300可使动作在用户停止触发 300ms 后才真正执行一次避免产生大量重复下载。三种文件类型的数据格式要求CSV对象数组键即列头使用CSV格式时Data 字段应是一个对象数组ToolJet 假定每个对象的键都相同并将这些键作为 CSV 的列头。官方文档示例{{ [ { name: John, email: johntooljet.com }, { name: Sarah, email: sarahtooljet.com }, ] }}生成结果为name,email John,johntooljet.com Sarah,sarahtooljet.com这一行为由 generate-csv.js 实现仅 5 行核心逻辑import Papa from papaparse; export default function generateCSV(records) { return Papa.unparse(records); }即底层直接委托给 papaparse 的Papa.unparse完成对象数组 → CSV 文本的序列化。这意味着字段中包含逗号、引号、换行符等字符时会按 RFC 4180 标准自动加引号转义可直接粘贴到 Excel 等工具中解析。Text字符串对象数组需先序列化使用Text格式时Data 字段应直接是一个字符串。如果数据源是对象数组例如表格组件的当前页数据必须先stringify再传入 Data 字段。官方文档给出的示例是{{JSON.stringify(components.table1.currentPageData)}}对应源码中plaintext的序列化函数是恒等函数(plaintext) plaintext即不做任何转换、原样写入文件——这也解释了为什么必须自行完成序列化若直接传对象数组Blob会得到无意义的[object Object]内容。PDF字符串或对象数组二选一PDF 支持两种输入形态行为差异在 generate-file.js 的generatePDF函数中清晰可见传入字符串生成纯文本 PDF。源码中以doc.text(value, x, y, { align: left, maxWidth: pageWidth - 2 * margin })逐行绘制页边距margin 10传入对象数组生成表格形态的 PDF。源码以数组第一个元素的键作为表头调用 jspdf-autotable 的doc.autoTable({ head: [columnNames], body: value.map((item) Object.values(item)) })渲染出带行列的表格并依据doc.lastAutoTable.finalY控制后续内容的起始位置传入单个对象同样渲染为表格只是 body 只有一行数据其他类型数字、布尔等抛出Invalid data type. Expected string, object, or array.错误。底层生成机制Blob 下载与 PDF 动态加载generate-file.js 的generateFile主函数处理 CSV 与文本文件的下载const type fileType csv ? text/csv : text/plain; const blob new Blob([data], { type }); if (window.navigator.msSaveOrOpenBlob) { window.navigator.msSaveBlob(blob, filename); } else { const elem window.document.createElement(a); elem.href window.URL.createObjectURL(blob); elem.download filename; document.body.appendChild(elem); elem.click(); document.body.removeChild(elem); window.URL.revokeObjectURL(elem.href); }要点CSV 使用text/csvMIME 类型其余plaintext使用text/plain兼容旧版 IE/Edge 的msSaveOrOpenBlob接口现代浏览器走标准的创建a元素 URL.createObjectURL 模拟点击流程并在使用后revokeObjectURL释放内存避免 Blob URL 泄漏全程在浏览器端完成数据不经过服务端中转适合包含敏感数据的本地导出场景。PDF 则采用动态 import按需加载await import(jspdf)见 generate-file.js L22-L26jspdf 体积较大按需引入可避免首屏加载负担同时对 ESM/CJS 两种导出形式都做了兼容取值jsPDFNamespace.jsPDF || jsPDFNamespace.default。通过 RunJS 调用 generate file除在组件事件Events中配置外该动作同样可在 RunJS 代码中调用官方文档在 run-action-from-runjs.md 中给出了签名与示例actions.generateFile(fileName, fileType, data)三个实战示例均出自该文档// 以表格当前页数据生成 CSV 文件 csvfile1 actions.generateFile(csvfile1, csv, {{components.table1.currentPageData}}) // 以字符串化后的表格数据生成文本文件 textfile1 actions.generateFile(textfile1, plaintext, {{JSON.stringify(components.table1.currentPageData)}}) // 以表格当前页数据生成 PDF 表格文件 Pdffile1 actions.generateFile(Pdffile1, pdf, {{components.table1.currentPageData}})RunJS 桥接实现位于 eventsSlice.js L1298-L1310内部先校验三个参数均非空缺失时弹出Action failed: fileName, fileType and data are required错误提示再构造actionId: generate-file的事件对象并复用与 UI 完全相同的executeAction执行通道——这意味着 RunJS 调用与事件面板配置走的是同一条执行链路行为完全一致。使用要点小结参数命名与文档一致fileName、fileType、data三个字段都支持{{...}}变量表达式可引用查询结果、组件数据或全局变量文本类型务必传字符串UI 中 Type 选择Text后内部类型值是plaintext若数据是对象数组请在 Data 字段中显式JSON.stringifyCSV 列头来自对象的键确保数组中各对象键集一致列头顺序即对象键的顺序PDF 想要表格效果就传对象数组想要纯文本就传字符串善用 Debounce在高频触发的事件上配置毫秒级延迟避免重复下载。以上配置与行为均可在当前仓库中直接查证文档主体见 generate-file.md事件分发见 eventsSlice.js文件生成核心见 generate-file.js 与 generate-csv.jsRunJS 调用说明见 run-action-from-runjs.md。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考