尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

ToolJet 实战:基于 AWS S3 构建文件上传与下载界面(完整 Queries 与 Widgets 配置指南)

ToolJet 实战:基于 AWS S3 构建文件上传与下载界面(完整 Queries 与 Widgets 配置指南) ToolJet 实战基于 AWS S3 构建文件上传与下载界面完整 Queries 与 Widgets 配置指南【免费下载链接】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 官方 how-to 指南整理与源码扩充的实战教程讲解如何在不写任何后端代码的前提下使用 ToolJet 的 App Builder 组合 Dropdown、Table、Text Input、File Picker 与 Button 等组件配合 AWS S3 数据源的 4 条核心查询getBuckets、listObjects、uploadToS3、download快速搭建一个可浏览 Bucket、列出对象、上传文件并生成下载链接的 S3 文件管理界面。读完本文你将掌握 ToolJet 查询与组件之间的数据绑定、事件驱动刷新以及 base64 文件上传的标准写法并了解底层 S3 查询服务的实现原理。前置条件先接入 AWS S3 数据源在开始搭建 UI 之前必须先完成 AWS S3 数据源Data Source的接入。ToolJet 官方文档在 AWS S3 数据源指南 中详细说明了配置方式这里提炼关键步骤作为实战前置点击查询面板Query Panel左下角的 添加新数据源Add new Data source按钮或从 ToolJet 仪表盘的数据源Data Sources页面进入选择Amazon AWS S3数据源根据你的运行环境选择认证方式ToolJet 支持以下三种认证方式需要提供的参数适用场景IAM Access KeysRegion、Access key、Secret key最常见的长期凭证方式官方建议为此创建专用 IAM 用户便于控制 ToolJet 的访问权限级别AWS Instance CredentialsRegion勾选 Use AWS Instance CredentialsToolJet 运行在 EC2/ECS 上时直接复用实例绑定的 IAM 角色AWS ARN RoleRegion、Role ARN需要跨账号或按角色授权时通过 STS AssumeRole 换取临时凭证:::tip 如果使用的是非 AWS 的 S3 兼容存储还可以通过自定义 endpoint 连接不同的 S3 Host详见 S3 Custom Endpoints 指南本文主题不展开。 :::从源码角度看上述三种认证方式在 S3 插件中有对应的实现分支。以 插件实现 中的getConnection方法为例选择AWS Instance Credentials时使用 AWS SDK 的fromInstanceMetadata()创建S3Client其内部通过timeout: 5000与maxRetries: 1控制元数据服务的访问超时与重试选择AWS ARN Role时插件会调用 getAssumeRoleCredentials通过 STS 的AssumeRoleCommand换取临时凭证AccessKeyId、SecretAccessKey、SessionToken后再创建客户端使用IAM Access Keys时直接以access_key/secret_key构造凭证。构建 UI五个 Widgets 各司其职接入数据源后在 App Builder 画布上拖入以下组件构成整个 S3 文件管理界面的骨架Widget作用Dropdown用于选择 S3 存储桶Bucket其选项来自getBuckets查询结果Table用于列出所选 Bucket 内的全部对象文件数据来自listObjects查询结果Text Input用于输入文件上传的目标路径前缀目录File Picker用于选择要上传的本地文件Button用于触发上传查询uploadToS3这 5 个组件分别承担选桶 → 看文件 → 定路径 → 选文件 → 触发上传的完整交互链路。下图是搭建完成后的界面效果四条核心 Queries 的完整配置本次实战共需要创建 4 条查询分别完成列桶、列对象、生成下载链接、上传文件四项能力。接下来逐一讲解每条查询的创建方式与参数绑定。getBuckets拉取全部存储桶操作Operation选择List buckets列出所有桶该操作不需要任何参数。步骤新建查询 → 选择 AWS S3 数据源 → 操作选择List buckets→ 将查询命名为getBuckets→ 点击Save保存。从源码看ListBuckets操作最终由 listBuckets 函数 执行构造一个空的ListBucketsCommand({})并发送给 S3 客户端返回的响应结构为{ Buckets: [...], Owner: {...} }其中Buckets是对象数组每个元素含Name桶名、CreationDate创建时间等字段。这正是下一步 Dropdown 数据绑定的依据。配置 Dropdown 绑定桶列表选中画布上的Dropdown组件进入其属性面板做如下配置Label标签设置为Bucket作为界面上的提示文案Option values选项值设置为{{queries.getBuckets.data.Buckets.map(bucket bucket[Name])}}将查询返回的Buckets对象数组映射为桶名字符串数组Option label选项标签同样设置为{{queries.getBuckets.data.Buckets.map(bucket bucket[Name])}}让界面显示的标签与底层值保持一致显示桶名、值也是桶名。:::info{{ }}是 ToolJet 的表达式语法类似模板字符串可以在任意属性中输入 JavaScript 表达式并直接引用queries.查询名.data与components.组件名等全局对象。这里的map操作是因为Buckets是对象数组而 Dropdown 的选项值需要的是字符串数组。 :::事件衔接可以给 Dropdown 添加事件处理器Event Handler当用户从下拉框选中某个桶时自动触发运行listObjects查询从而联动刷新表格数据。这个联动是后续所有动态行为的基础。listObjects列出选中桶内的全部对象操作Operation选择List objects in a bucket列出桶中的对象。参数配置在Bucket字段中输入{{components.dropdown1.value}}这样查询执行时会动态取 Dropdown 当前选中的桶名而不是写死某个桶。从源码可以更深入地理解这个操作的行为。在 listObjects 函数 中插件将查询参数映射为 AWS SDK v3 的ListObjectsV2CommandInputToolJet 查询参数SDK 字段说明BucketBucket桶名必填PrefixPrefix可选按前缀过滤例如只列出images/下的对象Max keysMaxKeys可选单次最多返回的对象数量OffsetStartAfter可选从某个键名之后开始列举等效于按前缀起始位置列举Next Continuation TokenContinuationToken可选当结果被截断时用响应中的令牌取下一页列表操作返回的响应中Contents字段是对象数组每个元素包含Key对象键即文件路径、LastModified最后修改时间、Size大小字节、ETag、StorageClass等元数据这些字段将直接用于 Table 组件的列绑定。配置 Table 展示对象列表选中Table组件按以下方式配置其属性Table data表数据{{queries.listObjects.data[Contents]}}将表格数据源绑定到listObjects查询返回的对象数组。注意这里用data[Contents]而不是data.Contents两种写法等价但后者在某些包含特殊字符的字段名场景下更稳妥添加列Add Columns列Column Name列名Key数据键第 1 列KeyKey第 2 列Last ModifiedLastModified第 3 列SizeSize添加操作按钮Action button添加一个按钮按钮文本设为Copy signed URL并为其添加事件处理器事件选择On Click动作Action选择Copy to clipboard在文本字段中输入{{queries.download.data.url}}这样点击按钮时会把download查询生成的签名下载 URL 复制到剪贴板。download为选中对象生成签名下载 URL操作Operation选择Signed URL for download生成下载签名 URL。参数配置Bucket{{components.dropdown1.value}}Key{{components.table1.selectedRow.Key}}使用 Table 组件当前选中行的Key字段实现点哪行、签哪行的动态绑定。事件衔接回到 Table 组件的属性面板添加一个事件处理器Event选择Row clicked行点击Action选择Run queryQuery选择download。这样每当用户点击表格中的任意一行都会触发download查询为该行对象生成新的签名下载 URL。:::info 签名 URLSigned URL / Presigned URL是对象所有者用自己的安全凭证为他人生成的、带时间限制的下载链接。其关键特性是临时有效过期后链接失效从而在不暴露 AWS 凭证的前提下安全共享对象。 :::从源码看该操作由 signedUrlForGet 函数 实现插件构造GetObjectCommand后调用 AWS SDK 的getSignedUrl()方法生成 URL其中expiresIn参数控制有效期默认值为 3600 秒1 小时查询面板中可通过Expires in参数覆盖默认值。返回结构为{ url: https://... }这就是上文中Copy signed URL按钮绑定queries.download.data.url的来源。uploadToS3将本地文件上传到指定路径操作Operation选择Upload object上传对象。参数配置这是本教程中信息密度最高、也最容易踩坑的一组绑定参数字段表达式含义Bucket{{components.dropdown1.value}}目标桶名动态取 Dropdown 当前选中值Key{{ components.textinput1.value / components.filepicker1.file[0].name }}上传路径Text Input 输入的目录 / 文件名Content type{{components.filepicker1.file[0].type}}文件的 MIME 类型由 File Picker 自动读取Upload data{{components.filepicker1.file[0].base64Data}}文件的 base64 编码内容Encodingbase64告知数据源上传数据是 base64 编码需要解码后写入这里的几个绑定点值得展开说明其底层逻辑components.filepicker1.file是文件对象数组。ToolJet 的 File Picker 组件在useFilePicker钩子中frontend/src/AppBuilder/Widgets/FilePicker/hooks/useFilePicker.js通过FileReader的readAsDataURL读取文件将结果拆出 base64 部分存入base64Data字段同时保留name文件名、typeMIME 类型、sizeBytes大小等元数据。因此file[0]表示第一个文件file[0].name、file[0].type、file[0].base64Data分别对应文件名、类型与内容。这也是为什么Max file count要设为 1——保证file[0]就是唯一且确定的文件。Encoding为base64时服务端会做解码。在 uploadObject 函数 中插件用Buffer.from(data, encoding)将Upload data按指定编码转换成二进制Buffer再作为PutObjectCommand的Body发送ContentEncoding也会被一并设置。若你的文件内容不是 base64 编码则保持默认的utf8即可。Content type 会被写入对象的元数据。ContentType参数会传给 S3 的PutObjectCommand决定对象下载时的响应 Content-Type 头因此建议从 File Picker 动态读取文件真实类型而不是写死。配置 File Picker限定文件类型与数量点击 File Picker 组件的属性手柄widget handle进入属性面板进行以下配置Accept file types接受的文件类型只接受 PDF{{application/pdf}}只接受图片{{image/*}}接受任意类型留空Max file count最大文件数{{1}}因为每次只上传 1 个文件。:::infoAccept file types必须是符合 input 元素规范的合法 MIME 类型如application/pdf、image/*或合法的文件扩展名。要接受任意类型文件将该属性设为空值即可。 :::从组件定义看该属性在 File Picker 组件定义 中对应validation.fileType字段默认值为image/*而maxFileCount的默认值为2见 filepicker.js并且仅在启用多文件模式enableMultiple时才渲染显示。useFilePicker钩子中同样以maxFileCount作为上限校验依据useFilePicker.js超出数量会提示 You can select a maximum of N files.。因此本次实战将两个值分别设为application/pdf与{{1}}既限定了类型也限定了数量。收尾上传成功后自动刷新对象列表最后一步是让整个流程闭环。进入uploadToS3查询的Advanced高级选项卡添加一个成功事件处理器On SuccessEventQuery SuccessActionRun queryQuerylistObjects这样每当文件上传成功listObjects查询会自动重新执行Table 中的数据随即刷新新上传的文件立刻出现在列表中无需手动点击任何刷新按钮。至此整个 S3 文件管理应用的核心链路就完整了页面加载时运行getBucketsDropdown 填充全部桶名用户选择桶触发listObjectsTable 列出桶内所有对象用户点击某一行触发download生成该对象的签名下载 URL可通过Copy signed URL按钮复制用户在 Text Input 输入目标目录、用 File Picker 选择文件点击 Button 触发uploadToS3上传上传成功后自动重跑listObjects表格即时刷新。延伸还能做哪些扩展基于同样的查询 组件 事件模式结合 S3 数据源支持的操作清单其底层实现均可参考 operations.ts你可以很方便地扩展更多能力Read object读取对象直接读取对象内容并返回字符串适合预览文本类文件Remove object删除对象可在 Table 中再添加一个删除操作按钮绑定{{components.table1.selectedRow.Key}}后触发删除查询Signed URL for upload上传签名 URL如果希望让不具备 AWS 凭证的外部用户直接向桶内上传可以生成上传签名 URL 交给客户端直传Create a new bucket新建桶结合 Text Input 输入桶名即可在界面内完成建桶操作。此外S3 插件还支持allow_dynamic_connection_parameters开关默认开启它决定查询中的 Bucket 参数是采用查询级动态值还是回退到数据源配置的默认桶名见 插件入口在多环境、多桶切换场景下非常实用。如果需要更完整的可运行示例仓库中还提供了官方 S3 浏览应用的教程链接与配套截图可结合本文逐步复现。整个方案的实现思路同样适用于 ToolJet 支持的其他对象存储数据源如 GCS、MinIO 等一通百通。【免费下载链接】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),仅供参考
返回列表