ToolJet 使用 Base64 字符串上传并展示图片与 PDF 的完整指南

ToolJet 使用 Base64 字符串上传并展示图片与 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/ToolJet

导读

本指南演示如何在 ToolJet 中把图片和 PDF 文件以Base64 字符串的形式写入数据库，再通过Data URL在应用画布上还原展示。完成本教程后，你将掌握 Filepicker 组件的 exposed variables 用法、ToolJet Database 的写入/查询流程，以及 Image、PDF 组件接收 Base64 数据的具体配置方式，可直接套用到各类文件管理的内部工具场景。

方案原理：为什么用 Base64 + Data URL

浏览器在本地读取文件时，FileReader.readAsDataURL()会把文件内容编码为一个形如data:image/png;base64,iVBORw0...的 Data URL——其中逗号之前是 MIME 类型前缀，逗号之后才是纯 Base64 字符串。ToolJet 的 Filepicker 组件正是基于这一机制实现文件读取：在 useFilePicker.js 中，组件通过readAsDataURL读取文件，并用split(',')[1]剥离前缀，把纯 Base64 内容暴露为base64Data字段，同时保留原始 Data URL 为dataURL字段。

因此，数据库里存的是不含前缀的纯 Base64 字符串；而展示时，Image / PDF 组件需要的是完整的 Data URL，所以我们要在组件属性里手动拼接data:image;base64,或data:pdf;base64,前缀。这一步拼接正是本方案的核心所在。

说明：本指南以 ToolJet Database 作为存储示例，同样的思路完全适用于 PostgreSQL、MySQL 等任何 ToolJet 支持的数据源。

第 1 步：在 ToolJet Database 中建表

1. 打开 ToolJet 的Database页面，创建一个新表，命名为testDB。
2. 表会自动带有id字段，用于为每条记录生成唯一标识。
3. 点击Add more columns，新增两列：pdf和image。
4. 将这两列的datatype都选择为varchar。

Base64 字符串本质上是纯文本，因此varchar即可满足存储需求；如果后续要存放体积较大的文件，也可以在 PostgreSQL 等数据源中使用text类型。保存表结构后进入下一步。

第 2 步：用 Filepicker 组件选取并上传文件

2.1 搭建应用界面

1. 新建一个应用，命名为Load PDF And Images Example。
2. 从右侧组件库中拖入两个Filepicker组件。
3. 将第一个重命名为imagePicker（用于选图片），第二个重命名为pdfPicker（用于选 PDF）。

2.2 限制可接受的文件类型

Filepicker 的Accept file types属性决定了拖放区接受哪些 MIME 类型。在pdfPicker的该属性中输入：

{{"pdf/*"}}

这样 Filepicker 只会接受 PDF 文件，其他类型会被拒绝。imagePicker则保持默认的{{"image/*"}}设置，用于接收图片。

在底层，该属性会被 useFilePicker.js 解析为 react-dropzone 的accept对象，从而在拖放和文件对话框中执行类型校验。此外，你还可以参考 Filepicker 文档 配置Max file count（默认2）、Max size limit（默认51200000字节）等校验项。

随后分别在两个组件中上传文件：点击imagePicker选择一张图片，点击pdfPicker选择一个 PDF。上传完成后，文件名会显示在各自组件上。

2.3 创建写入数据库的查询

1. 点击查询面板中的+ Add新建查询。
2. 数据源选择ToolJet Database，Table name 选择testDB，Operations 选择Create Row，将查询命名为uploadFiles。
3. 在 Columns 区域添加pdf和image两个字段。
4. 为pdf列设置值：

{{components.pdfPicker.file[0].base64Data}}

5. 为image列设置值：

{{components.imagePicker.file[0].base64Data}}

这里使用的是 Filepicker 组件的exposed variables：components.pdfPicker.file是包含所选文件对象的数组，每个对象带有name、type、content、dataURL、base64Data、parsedData、filePath等字段（见 file-picker.md 的 Exposed Variables 章节）。file[0]取第一个文件，.base64Data即其纯 Base64 内容。

注意：file数组中每项都带有dataURL（完整的 Data URL，含 MIME 前缀）和base64Data（去前缀的纯 Base64）。写入数据库时请使用base64Data，这样拼接逻辑才统一可控。

2.4 用按钮触发上传

1. 在 Filepicker 下方添加一个Button组件，重命名为upload，文本设为Upload。
2. 为该按钮新建事件处理器：Event选择On click，Action选择Run Query，Query选择uploadFiles。
3. 点击Upload按钮，即可把两个组件中已选文件的 Base64 字符串写入testDB。

至此上传流程完成：每次在 Filepicker 中选定文件并点击Upload，对应的 Base64 数据就会作为新记录自动写入数据库。

第 3 步：读取数据库并展示图片与 PDF

3.1 创建读取查询

1. 点击+ Add新建查询，命名为getFiles。
2. 数据源选择ToolJet Database，Table name 选择testDB，Operations 选择List rows。
3. 开启Run this query on application load?（应用加载时自动运行），然后点击Run执行查询。

查询返回的queries.getFiles.data是记录数组，其中第一条记录的image、pdf字段就是上一步写入的 Base64 字符串。

3.2 用 Image 组件展示图片

1. 从组件库拖入一个Image组件，重命名为displayImage。
2. 在其URL属性中输入：

{{'data:image;base64,' + queries.getFiles.data[0].image}}

拼接表达式把数据库中的纯 Base64 数据转换为浏览器可识别的 Data URL。ToolJet 的 Image 组件在渲染时，若属性为 Base64 形式会构建data:${type};base64,${base64Data}的地址（见 Image.jsx），同时你还可以配置Alternative text、Zoom button、Rotate button、Loading state等属性来完善交互。

3.3 用 PDF 组件展示 PDF

1. 再拖入一个PDF组件，重命名为displayPDF。
2. 在其File URL属性中输入：

{{'data:pdf;base64,' + queries.getFiles.data[0].pdf}}

PDF 组件的底层实现基于 react-pdf / PDF.js（见 PDF.jsx），其File URL属性同时支持普通 URL 与 Base64 数据；使用 Base64 时需要以data:application/pdf;base64,为前缀。该组件还提供Scale page to width、Show page controls、Show the download等属性，并且只在 Chrome 92+、Edge 92+、Safari 15.4+、Firefox 90+ 中渲染，集成前请确认目标浏览器版本。

完成以上配置后，运行应用即可看到最终的展示效果：

进阶技巧与注意事项

使用查询变换拼接 MIME 前缀

除了在组件属性中拼接外，你还可以利用查询的Transformations功能，在返回数据时直接拼好完整 Data URL。例如在getFiles查询的变换里写入：

return data.map((row) => ({ ...row, image: 'data:image/jpeg;base64,' + row.image, pdf: 'data:application/pdf;base64,' + row.pdf, }));

随后组件的属性就可以简化为{{queries.getFiles.data[0].image}}。按需使用image/png、image/jpeg、application/pdf等精确 MIME 类型，能让浏览器更准确地解析内容。

多文件与多记录场景

本示例取file[0]和data[0]仅处理单个文件、单条记录。若 Filepicker 开启了Pick multiple files，可改用components.imagePicker.file（数组）配合map批量生成记录；若表中有多条记录，也可结合 Table 组件的行点击事件，把当前行的 Base64 传入展示组件。

局限与建议

• 存储体积：Base64 编码会使数据体积比原始文件增加约 33%，超大文件建议评估 varchar/text 字段容量或改用对象存储（如 S3）保存文件、数据库只存 URL。
• 查询响应体量：一次性List rows拉取大量含 Base64 的记录会显著增加网络与内存开销，建议限制返回行数或按需查询。
• 浏览器兼容性：PDF 展示依赖 PDF.js，请参照上文兼容矩阵选择浏览器版本。
• 其他数据库：本方案对存储引擎无特殊依赖，PostgreSQL、MySQL 等同样适用，仅需将 Base64 写入对应文本类型字段即可。

小结

通过 Filepicker 暴露的base64Data变量完成写入、通过data:...;base64,前缀完成读取，ToolJet 便能在不依赖任何外部文件服务的前提下，实现图片与 PDF 的完整"上传—存储—展示"闭环。这一模式同样适用于 CSV、音频、视频等任意二进制文件，是构建轻量级文件管理类内部工具的基础范式。更多组件细节可参阅 Filepicker、Image 与 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/ToolJet