ToolJet 动作指南：Copy to clipboard（复制到剪贴板）动作的配置与源码解析-迪斯科星球

ToolJet 动作指南：Copy to clipboard（复制到剪贴板）动作的配置与源码解析

【免费下载链接】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

Copy to clipboard 是 ToolJet 内置的"其他类（Other）"动作之一，用于在应用运行时把指定文本写入浏览器剪贴板。本文以 ToolJet 2.50.0-LTS 版本文档为骨架，结合前端事件执行链路的真实源码，完整讲解该动作的可视化配置方式、Debounce 防抖参数、支持动态值（{{...}}）的取值机制，以及如何在 RunJS 中通过copyToClipboard()编程触发同一动作，帮助你在表单复制、邀请链接、凭证展示等场景中快速落地。

动作概览

Copy to clipboard 动作的作用非常直接：将一段文本复制到剪贴板。在 ToolJet 的事件处理器（Event Handlers）中，它被归入other（其他）动作分组，动作唯一标识为copy-to-clipboard。

从动作注册表 frontend/src/AppBuilder/RightSideBar/Inspector/ActionTypes.js 可以看到该动作的正式定义：

{ name: 'Copy to clipboard', id: 'copy-to-clipboard', options: [{ name: 'copy-to-clipboard', type: 'text', default: '' }], group: 'other', },

也就是说，该动作只有一个输入参数：要复制的内容（文本），默认值为空字符串。你可以在其中填入普通文本，也可以填入{{ variables }}、{{ components.textarea1.value }}之类的动态值表达式，让复制内容随应用状态实时变化。

在事件处理器中配置 Copy to clipboard

在 ToolJet 应用编辑器中，任意支持事件（Event）的组件（如 Button、TextInput、Table 等）都可以挂载该动作。配置步骤如下：

选中组件，在右侧检查器（Inspector）的Events区域添加一个新事件处理器（如On Click）；
在动作（Action）下拉框中选择Copy to clipboard；
在Copy to clipboard输入框中填写要复制的文本或{{ }}动态表达式；
（可选）填写Debounce字段，控制动作触发的延迟时间。

下图展示了该动作在事件处理器中的配置界面（图片来源：docs/static/img/actions/copytoclipboard/copy2.png）：

说明：该界面截图来自 ToolJet 2.50.0-LTS 版本文档，展示的是在事件处理器中选择 Copy to clipboard 动作并填写复制内容的面板形态。

Debounce 防抖参数

原版文档明确指出：

Debounce field is empty by default, you can enter a numerical value to specify the time in milliseconds after which the action will be performed. ex:300

即：

默认值为空：不开启防抖，事件触发后动作立即执行；
填写数值：单位为毫秒（ms），表示事件触发后延迟该时长再执行动作，例如300表示延迟 300ms。

这个参数在事件处理器源码 frontend/src/AppBuilder/RightSideBar/Inspector/EventManager.jsx 中对应一个独立的Debounce表单字段，其值保存在事件的debounce属性上：

<FieldRow label={t('editor.inspector.eventManager.debounce', 'Debounce')} dataCy="debounce-label"> <Input initialValue={event.debounce} onChange={(value) => handlerChanged(index, 'debounce', value)} cyLabel={'debounce'} /> </FieldRow>

值得注意的是，源码中对空值做了特殊处理：当 Debounce 字段被清空时，会从事件对象中删除debounce键（EventManager.jsx），从而保证"默认立即执行"的语义：

// Remove debounce key if it's empty if (param === 'debounce' && value === '') { delete updatedEvent.event.debounce; }

典型使用场景：在双击选择表格行、键盘快捷触发等连续事件场景下，设置一个较小的防抖值（如300），可以避免用户高频操作导致剪贴板被意外覆盖。

底层实现：事件执行链路

Copy to clipboard 动作在前端的事件分发器中执行。核心实现在 frontend/src/AppBuilder/_stores/slices/eventsSlice.js：

case 'copy-to-clipboard': { const contentToCopy = getResolvedValue(event.contentToCopy, customVariables, moduleId); copyToClipboard(contentToCopy); return Promise.resolve(); }

这段代码揭示了两个关键实现细节：

动态值解析：event.contentToCopy会先经过getResolvedValue解析，再传入复制函数。这意味着你在配置界面填写的{{ ... }}表达式会在动作执行时被实时求值——例如{{ globals.currentUser.email }}、{{ components.table1.selectedRow.id }}都会被解析成具体值后写入剪贴板。
动作是异步的：该 case 返回Promise.resolve()，说明它是一个可被事件系统正确等待的异步动作，后续事件（如果有的话）会在复制完成后继续执行。

真正执行写入剪贴板操作的是工具函数 frontend/src/_helpers/appUtils.js：

export async function copyToClipboard(text) { try { await navigator.clipboard.writeText(text); toast.success('Copied to clipboard!'); } catch (err) { console.log('Failed to copy!', err); } }

它使用浏览器标准的Clipboard API（navigator.clipboard.writeText）完成写入：

写入成功后，界面右上角会弹出Copied to clipboard!的成功提示（toast）；
写入失败（例如页面处于非安全上下文、剪贴板权限被拒绝）时，错误会被捕获并输出到控制台，不会抛出未处理异常导致事件链路中断。

环境前提：navigator.clipboard仅在 HTTPS（或 localhost）等安全上下文（secure context）中可用。如果你在非 HTTPS 环境部署 ToolJet，复制动作可能无法生效，这一点在排查"点击后没反应"问题时需要优先确认。

在 RunJS 中编程触发

Copy to clipboard 不限于在事件处理器中配置，你也可以在RunJS代码中直接调用。原版文档也提示了这一点：

You can also trigger actions from theJavaScript code. Check it out here.

对应的完整教程见 docs/versioned_docs/version-2.50.0-LTS/how-to/run-action-from-runjs.md，其核心用法是调用actions.copyToClipboard()。

事件执行器为 RunJS 暴露的 API 封装在 eventsSlice.js 中：

const copyToClipboard = (contentToCopy = '') => { const event = { actionId: 'copy-to-clipboard', contentToCopy, }; return executeAction(event, mode, {}, moduleId); };

因此，在应用的RunJS组件（或任意支持actions对象的 JavaScript 代码处）可以这样写：

// 复制静态文本 await actions.copyToClipboard('Hello, ToolJet!'); // 复制动态内容：把输入框当前值复制到剪贴板 await actions.copyToClipboard(components.textinput1.value); // 复制查询结果 await actions.copyToClipboard(JSON.stringify(queries.getUsers.data, null, 2));

几点实践建议：

参数缺省时默认为空字符串（contentToCopy = ''），此时会复制一个空文本，属于合法的边界行为；
传入对象时建议先用JSON.stringify序列化，因为剪贴板 API 写入的是文本；
通过actions触发与事件处理器配置走的是同一条执行链路（相同的actionId: 'copy-to-clipboard'与executeAction），因此同样会经历getResolvedValue的动态值解析，并在成功后弹出 toast 提示。

与其他动作的搭配与典型场景

由于 Copy to clipboard 只是把文本写入剪贴板，它经常与生成文件（Generate file）、显示提示（Show Alert）等动作组合，构成完整的用户反馈闭环。例如：

一键复制邀请链接：按钮On Click→ 复制{{ globals.currentUser.email }}或拼接好的分享链接 → 再叠加Show Alert提示"链接已复制"；
复制表格选中行的主键：使用{{ components.table1.selectedRow.id }}作为复制内容，配合防抖参数避免误触；
复制 API 凭证：将查询结果{{ queries.getCredential.data.apiKey }}复制到剪贴板，方便用户粘贴到外部系统。

小结

Copy to clipboard 是 ToolJet 中最轻量的动作之一，但它的灵活性来自两点：一是{{ }}动态表达式支持在动作执行时才解析取值，二是同时支持可视化事件配置与 RunJS 编程调用两种触发方式。本文涉及的源码位置汇总如下，供进一步深入阅读：

动作注册表：frontend/src/AppBuilder/RightSideBar/Inspector/ActionTypes.js
事件执行链路：frontend/src/AppBuilder/_stores/slices/eventsSlice.js
RunJS 编程接口：frontend/src/AppBuilder/_stores/slices/eventsSlice.js
剪贴板写入实现：frontend/src/_helpers/appUtils.js
Debounce 字段处理：frontend/src/AppBuilder/RightSideBar/Inspector/EventManager.jsx
官方概念文档：docs/versioned_docs/version-2.50.0-LTS/tooljet-concepts/actions.md

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析