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

本指南讲解如何在 ToolJet 中利用 Base64 字符串完成文件的"上传—存储—回显"闭环：先通过 Filepicker 组件把图片与 PDF 读取为 Base64 编码写入 ToolJet Database（或其他数据库），再借助 Image 组件与 PDF 组件配合 Data URL 将数据库中的 Base64 数据渲染回界面。读完本文，你将掌握 Filepicker 暴露变量、ToolJet Database 的 Create Row / List rows 查询以及 Data URL 拼接这一整套可在真实业务中直接复用的文件存取方案。

1. 方案原理：为什么选择 Base64

浏览器无法直接把本地文件的二进制内容写入普通数据库字段，而 Base64 是一种把二进制数据编码为 ASCII 文本的通用方案，恰好可以安全地存入 varchar / text 类型的数据库列。ToolJet 的 Filepicker 组件在读取文件时会同时把内容加工成多种格式，其中就包括去除 Data URL 前缀后的纯 Base64 字符串。

从源码实现看，Filepicker 通过 FileReader 以两种方式读取文件（useFilePicker.js）：

• readAsText 读取纯文本内容（存入 content）；
• readAsDataURL 读取 Data URL，随后用 readFileAsDataURLResult.split(',')[1] 截取逗号之后的部分，得到 base64Data。

const readFileAsDataURLResult = await getFileData(file, 'readAsDataURL');
const base64Data = readFileAsDataURLResult.split(',')[1];

最终每个文件对象会暴露 name、type、content、dataURL、base64Data、parsedData、filePath 等字段，并在画布上以 {{components.imagePicker.file[0].base64Data}} 这类暴露变量形式供查询和事件使用（对应文档见 file-picker.md）。这正是本方案中"上传"环节的数据来源。

2. 准备工作：在 ToolJet Database 中创建数据表

本指南以 ToolJet 内置的 ToolJet Database 为例（该原则同样适用于其他数据库，只要列类型能容纳长文本即可）。

1. 进入 ToolJet 的数据库页面，新建一张表，命名为 testDB；
2. 数据表默认自带 id 字段，用于为每条记录生成唯一标识；
3. 点击 Add more columns（添加更多列），追加两列：pdf 和 image；
4. 将 pdf 与 image 两列的数据类型都选择为 varchar，用于存放 Base64 编码后的长字符串。

提示：Base64 编码会使数据体积比原始文件增大约 33%，若存储较大的文件，建议在数据库中为该列选用容量更大的文本类型（如 text），并在 Filepicker 中合理设置文件大小上限（默认为 51200000 字节，即约 48.8MB，见 useFilePicker.js）。

3. 上传环节：用 Filepicker 读取文件为 Base64

3.1 创建应用并放置两个 Filepicker

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

3.2 限制可接受的文件类型

Filepicker 的 Accept file types 属性决定了拖拽/选择弹窗中允许的文件类型，置空表示接受所有类型（见 file-picker.md）。

• 对 pdfPicker，将 Accept file types 设为 {{"pdf/*"}}，确保只能选择 PDF 文件；

• 对 imagePicker，保留默认的 {{"image/*"}} 设置，用于图片上传。

该属性最终会透传到 react-dropzone 的 accept 配置（见 useFilePicker.js），如果上传了不符合类型的文件，会触发 file-invalid-type 校验错误并给出提示。

3.3 选择要上传的文件

分别点击两个 Filepicker 组件：imagePicker 中选择一张图片，pdfPicker 中选择一个 PDF 文件。上传成功后，组件上会显示对应文件名。

3.4 创建写入数据库的查询

1. 点击查询面板中的 + Add 按钮新建查询；
2. 数据源选择 ToolJet Database；
3. Table name 选择 testDB，Operations 选择 Create Row；
4. 将查询命名为 uploadFiles。

在 Columns 区域添加 pdf 和 image 两列，并填入以下表达式——这里直接引用了两个 Filepicker 的暴露变量，取数组中第一个文件的 base64Data：

• pdf 列：

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

• image 列：

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

3.5 用按钮触发上传

1. 在 Filepicker 下方添加一个 Button 组件，重命名为 upload，文本设为 Upload；
2. 为该按钮新建事件处理器（New event handler）：Event 选择 On click，Action 选择 Run Query，Query 选择 uploadFiles。

点击 Upload 按钮后，两个 Filepicker 中当前选中文件的 Base64 字符串会被写入 testDB 表的新行。至此，上传流程完成。

4. 回显环节：从数据库读取并展示图片与 PDF

4.1 创建读取数据的查询

1. 点击查询面板中的 + Add 按钮新建查询，命名为 getFiles；
2. 数据源选择 ToolJet Database，Table name 选择 testDB，Operations 选择 List rows；
3. 勾选 Run this query on application load?（应用加载时自动运行），点击 Run 执行查询，确保界面初始化时即可拿到数据。

执行后，查询结果会保存在 queries.getFiles.data 中，data[0] 对应表中第一行记录，其 image 与 pdf 字段即之前写入的 Base64 字符串。

4.2 用 Image 组件展示图片

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

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

这段表达式把 MIME 声明 data:image;base64, 与数据库中的 Base64 数据拼接成完整的 Data URL，浏览器即可直接渲染。这也是 Image 组件内部 data:${type};base64,${base64Data} 拼接逻辑（见 Image.jsx）的通用形式——事实上，Image 组件的 Image Format 属性若选择 base64 模式，本身就支持直接传入 {{data:...;base64,...}} 形式的 Data URL。

4.3 用 PDF 组件展示 PDF

1. 从组件库拖入一个 PDF 组件，重命名为 displayPDF；
2. 在其 File URL 属性中填入：

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

PDF 组件底层基于 react-pdf（pdf.js）渲染（见 PDF.jsx），支持多页文档加载、页码导航、滚动定位、缩放等交互能力，Data URL 与普通 URL 一样可以作为其文档源。

4.4 最终效果

完成上述配置后，应用加载时会自动执行 getFiles 查询，displayImage 与 displayPDF 分别把数据库中存储的图片和 PDF 渲染出来，界面如下：

5. 进阶技巧与注意事项

5.1 使用查询响应转换（Transformation）拼接 MIME 前缀

如果不想在组件属性里拼接，也可以在查询的 Transformation 中对响应做预处理。例如在 getFiles 查询的转换函数中返回：

{
  ...data[0],
  image: 'data:image/jpeg;base64,' + data[0].image,
  pdf: 'data:application/pdf;base64,' + data[0].pdf,
}

之后组件属性可直接简写为：

{{queries.getFiles.data[0].image}}

5.2 多文件与多条记录的处理

• 本示例默认 Filepicker 单选（enableMultiple 为 false）。若开启多选，文件数组会包含多个元素，写入时需按需遍历，例如用 {{components.pdfPicker.file.map(f => f.base64Data)}} 配合支持数组存储的列或分多条记录写入；
• 回显时 queries.getFiles.data[0] 固定取第一行记录，实际场景中建议通过 List rows 的筛选条件（如按 id 或业务主键过滤）精确取到目标记录。

5.3 性能与数据量注意事项

• Base64 编码约使数据膨胀 33%，请结合数据库列类型（varchar 长度限制）评估可存储的文件大小；
• Filepicker 默认最大文件大小为 51200000 字节（约 48.8MB）、默认最小文件大小为 0、默认文件数量上限为 2（见 useFilePicker.js），可在组件的验证（Validation）属性中调整；
• 如果图片渲染失败，可检查数据库中存的是否为纯 Base64（不含 data: 前缀），因为组件属性拼接时已显式补充了 data:image;base64, 前缀。

6. 总结

通过上述四步（建表 → Filepicker 读取为 Base64 → Create Row 写入 → List rows 读取并以 Data URL 回显），即可在 ToolJet 中实现图片与 PDF 的完整存取闭环。核心要点可归纳为：

• 文件在浏览器端由 Filepicker 通过 FileReader.readAsDataURL 读取，split(',')[1] 提取纯 Base64（useFilePicker.js）；
• 数据库只需普通字符串列即可保存文件内容；
• 展示时通过 'data:<type>;base64,' + base64 拼装 Data URL，交给 Image / PDF 组件渲染（Image.jsx）；
• 同一套逻辑可推广到其他文件类型（如 Word、CSV、音频等），只需对应调整 Accept file types 与 Data URL 的 MIME 前缀。