ToolJet Chat 组件实战属性、事件与 CSA 驱动的 AI 聊天机器人构建指南【免费下载链接】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 的 Chat Component 官方文档version-3.0.0-LTS展开完整覆盖该组件的属性配置、消息对象结构、事件机制与组件特定动作CSA并结合frontend/src下的组件源码印证其底层实现。读完后你可以独立搭建一个接入 AI 插件的智能客服聊天机器人也能把 Chat 组件改造为任意数据源驱动的多用户会话界面。一、组件定位与适用场景Chat Component 用于在应用内实现聊天式界面。根据 官方概述它既可与 AI 插件集成构建 AI 聊天机器人也可用于传统的人对人聊天功能同时适合 AI 驱动与人工对话两类场景。组件的核心工作模式是“数据进出分离”消息入站通过Initial Chat属性注入初始会话或通过sendMessage、appendHistory等 CSA 动态写入消息出站用户发送消息触发On message sent事件由你配置的事件处理器通常是 Run Query去调用后端/AI 接口再把结果写回聊天历史。从源码结构看组件的默认尺寸为宽 15 列、高 400px完整配置定义在 chat.js。二、属性配置详解以下属性表完整继承自 Properties 文档并结合 chat.js 中properties与definition字段补充了默认值。属性说明期望值源码默认值Chat Title聊天组件标题String如ToolJet Support ChatbotChatInitial Chat聊天启动时加载的初始消息Array of Objects如{{[ { message: Hey! Welcome to ToolJet. How may I help you? } ]}}内置两条示例消息一条response、一条messageUser Name用户名称String如John Doe{{globals.currentUser.firstName}}User Avatar用户头像Image URL空字符串Respondent Name应答方名称String如ToolJet BotAssistantRespondent Avatar应答方头像Image URL空字符串除上表外源码中还存在一个文档未单列的属性placeholder输入框占位文本默认Ask me anything!对应输入框的Placeholder for input field配置项见 chat.js。三、消息对象Message Object结构与校验规则每条聊天消息都是一个 Message Object完整字段定义见 Properties 文档属性说明是否必填期望值Message消息内容必填String如Hey! How can I help you?Message ID消息 ID自动生成String如e3dd6f60-d5e8-46c5-b73b-006f2f4a34f2Timestamp消息时间自动生成ISO 8601 格式 DateTime如2025-02-05T09:33:32.468ZName发送者名称可选String如John DoeAvatar发送者头像可选Image URLType消息类型必填取值response、message或errorType的三个取值决定了消息在界面中的归属message渲染为用户侧气泡名称/头像默认取User Name/User Avatarresponse渲染为应答方气泡默认取Respondent Name/Respondent Avatarerror用于展示错误提示。这一行为在源码 index.js 的 createMessage 中可以直接验证const newMessage { message, messageId: uuidv4(), // Message ID 由 uuid 自动生成 timestamp: new Date().toISOString(), // 时间戳为 ISO 8601 格式 name: name || (type message ? userName : respondentName), avatar: avatar || (type message ? userAvatar : respondentAvatar), type, };此外源码 helpers.js 中的validateSingleMessageObject会对sendMessage/appendHistory的入参做严格校验入参必须是对象message必须是字符串type必须是字符串且只能是response、error、message三者之一否则组件会弹出 toast 错误提示并拒绝写入。setHistory的入参则要求必须是数组validateMessageHistory。编写 RunJS 调用 CSA 时可以据此提前做防御性判断。四、分步实战搭建 AI 聊天机器人以下六步完整继承自 Overview 文档以接入 OpenAI 插件查询名openai1、组件名chat1为例。第 1 步拖入 Chat 组件将Chat Component拖入画布。组件默认为chat1可在画布选中后确认。第 2 步自定义组件基础属性按第二节的属性表配置四项输入Chat Title如ToolJet Support Chatbot设置Initial Chat如{{[ { message: Hey! Welcome to ToolJet. How may I help you?, type: response } ]}}配置User Name与User Avatar配置Respondent Name与Respondent Avatar。第 3 步配置 AI 查询生成响应在 Query Manager 中新建一个 AI 查询如openai1。所有可用 AI 插件可在 Marketplace 中查阅也可以使用任意数据源查询甚至把组件当作多用户聊天使用。关键点写回消息时必须在 message object 中指定type: response这样返回内容才会渲染为应答方气泡。第 4 步为查询添加事件处理器为openai1查询添加如下事件EventQuery SuccessActionControl ComponentComponentchat1从下拉框中选择你的 Chat 组件名ActionAppend HistoryMessage{{{message: queries.openai1.data, type:response}}}第 5 步为 Chat 组件添加事件处理器为chat1组件添加如下事件EventOn Message SentActionRun QueryQueryopenai1从下拉框中选择你的 AI 查询名这样就形成了闭环用户发消息 →On Message Sent触发 Run Query → 查询成功后Query Success事件把 AI 返回内容appendHistory回组件。从源码看On Message Sent事件的触发时序值得注意index.js 中组件先用 ref 标记“待发事件”在chatHistory状态更新、渲染完成后才真正fireEvent(onMessageSent)确保事件执行时用户消息已入库避免竞态。第 6 步配置响应加载状态点击Response loading state属性前的fx图标填入{{queries.openai1.isLoading}}。查询执行期间组件会显示应答方的“正在输入”占位消息对应源码中的RespondentLoadingMessage见 index.js。至此 AI 聊天机器人搭建完成。五、事件EventsChat 组件支持两个组件事件完整定义见 chat.js事件说明On history cleared每次聊天历史被清空时触发On message sent每次有消息发送时触发注意两者的触发差异通过界面输入框发送消息会自动触发On message sent而通过 CSAsendMessage()写入的消息不会自动触发该事件——源码 index.js 中明确将 CSA 通道的事件标记置为false并注释说明“用户需手动触发事件”因此若你的sendMessage也需要驱动 AI 查询请在 RunJS 中手动触发。六、组件特定动作CSACSA 可通过 RunJS 查询如components.chat1.sendMessage({...})或事件中的 Control Component 动作调用。完整清单来自 CSA 文档动作说明调用示例sendMessage()在聊天中发送一条消息components.chat1.sendMessage({message: Hey! How can I help you?, type: response})clearHistory()清空聊天历史components.chat1.clearHistory()deleteMessage()按 MessageID 删除某条消息components.chat1.deleteMessage(MessageID)downloadChat()以 JSON 格式下载聊天记录components.chat1.downloadChat()setHistory()整体设置聊天历史components.chat1.setHistory(History Object)appendHistory()追加一条聊天历史components.chat1.appendHistory(Message Object)setResponderAvatar()设置应答方头像components.chat1.setResponderAvatar(Image URL)setUserAvatar()设置用户头像components.chat1.setUserAvatar(Image URL)从源码结构看当前版本的 chat.js actions 数组 中额外还暴露了文档未列出的动作setError设置错误提示默认文案为Some error occurred. Please retry.、setHistoryLoading、setResponseLoading、setInputDisable、setVisibility。这意味着你可以在Query Failure事件里调用setError把失败信息渲染成error类型气泡而不必依赖组件自身的容错逻辑。关于downloadChat的实现细节index.js 会把当前chatHistory数组序列化为 JSON生成以chat-history-ISO时间戳.json命名的文件触发下载若历史为空则提示No chat history available to download.。七、附加动作开关Additional Actions以下开关既可通过属性面板的 toggle 直接切换也可点击fx填入逻辑表达式做动态控制见 Properties 文档动作说明源码默认值Visibility控制组件可见性trueDisable input state启用/禁用输入框falseHistory loading state启用历史加载态常配合isLoading展示进度falseResponse loading state启用响应加载态常配合isLoading展示进度falseEnable clear history button启用/禁用清空历史按钮trueEnable download history button启用/禁用下载历史按钮true默认值依据 chat.js definition 中的visibility: {{true}}、disableInput: {{false}}等配置。八、暴露变量Exposed Variables暴露变量可动态访问见 CSA 文档并与源码 exposedVariables 定义 一一对应变量说明动态访问示例history聊天历史{{components.chat1.history}}isHistoryLoading历史是否加载中{{components.chat1.isHistoryLoading}}isResponseLoading响应是否加载中{{components.chat1.isResponseLoading}}isInputDisabled输入是否被禁用{{components.chat1.isInputDisabled}}isVisible组件是否可见{{components.chat1.isVisible}}lastMessage历史中最后一条message类型消息{{components.chat1.lastMessage}}lastResponse历史中最后一条response类型消息{{components.chat1.lastResponse}}从源码实现看lastMessage与lastResponse是在每次appendHistory时按消息类型分别更新的见 index.jsclearHistory时两者都会重置为空对象index.js。典型用法用lastMessage.message作为 AI 查询的输入变量实现“携带最新用户输入调用后端”的闭环。九、消息的 Markdown 渲染Chat 组件对用户消息与响应均支持 Markdown 渲染可提升对话的可读性与结构化程度。完整语法示例见 Supported Markdown Syntax 文档支持的语法范围包括标题H1H6#至######文本格式化粗体**Text**、斜体*Text*、粗斜体***Text***、删除线~~Text~~列表无序列表含嵌套、有序列表含嵌套、任务列表- [x]/- [ ]代码行内代码code、代码块 围栏代码块引用多级嵌套引用链接与图片Link Text与Alt表格标准 Markdown 表格分隔线---/___/***HTML 内容如div stylecolor: blue;、table等行内 HTML脚注[^1]: footnote text。对 AI 聊天机器人而言这一点价值明显模型返回的 Markdown 回答代码块、列表、表格可以直接在聊天气泡中结构化渲染。十、响应式与样式组件在Devices面板提供Show on desktop与Show on mobile两个开关均支持fx动态表达式从源码 definition 可见默认为桌面显示、移动端隐藏showOnDesktop: {{true}}、showOnMobile: {{false}}。样式方面组件提供 Message、Field、Container 三组配色名称、消息体、时间戳、背景、边框、强调色、圆角等默认值均取自--cc-前缀的 CSS 变量如var(--cc-primary-text)会自动跟随深色/浅色主题切换——这一点可从 index.js 读取darkMode并附加dark-theme类的逻辑得到印证。渲染消息的 UI 拆分在frontend/src/AppBuilder/Widgets/Chat/components/目录下ChatHeader、ChatMessage、ChatInput、MarkdownMessage、RespondentLoadingMessage等。十一、小结Chat 组件的设计思路是“无状态数据 显式事件驱动”组件本身不绑定任何数据源历史数据通过initialChat/CSA 注入发送行为通过On Message Sent事件外抛。掌握第二八节的属性、消息对象、事件与 CSA 后你可以按第四节的六步流程接入任意 AI 插件构建客服机器人也可以利用history、lastMessage、downloadChat等能力将其扩展为审计、导出、多轮上下文管理更复杂的会话系统。相关文档与源码入口文档overview、properties、csa、markdown源码组件配置、组件实现、入参校验【免费下载链接】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），仅供参考 ToolJet Chat 组件实战：属性、事件与 CSA 驱动的 AI 聊天机器人构建指南
ToolJet Chat 组件实战属性、事件与 CSA 驱动的 AI 聊天机器人构建指南【免费下载链接】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 的 Chat Component 官方文档version-3.0.0-LTS展开完整覆盖该组件的属性配置、消息对象结构、事件机制与组件特定动作CSA并结合frontend/src下的组件源码印证其底层实现。读完后你可以独立搭建一个接入 AI 插件的智能客服聊天机器人也能把 Chat 组件改造为任意数据源驱动的多用户会话界面。一、组件定位与适用场景Chat Component 用于在应用内实现聊天式界面。根据 官方概述它既可与 AI 插件集成构建 AI 聊天机器人也可用于传统的人对人聊天功能同时适合 AI 驱动与人工对话两类场景。组件的核心工作模式是“数据进出分离”消息入站通过Initial Chat属性注入初始会话或通过sendMessage、appendHistory等 CSA 动态写入消息出站用户发送消息触发On message sent事件由你配置的事件处理器通常是 Run Query去调用后端/AI 接口再把结果写回聊天历史。从源码结构看组件的默认尺寸为宽 15 列、高 400px完整配置定义在 chat.js。二、属性配置详解以下属性表完整继承自 Properties 文档并结合 chat.js 中properties与definition字段补充了默认值。属性说明期望值源码默认值Chat Title聊天组件标题String如ToolJet Support ChatbotChatInitial Chat聊天启动时加载的初始消息Array of Objects如{{[ { message: Hey! Welcome to ToolJet. How may I help you? } ]}}内置两条示例消息一条response、一条messageUser Name用户名称String如John Doe{{globals.currentUser.firstName}}User Avatar用户头像Image URL空字符串Respondent Name应答方名称String如ToolJet BotAssistantRespondent Avatar应答方头像Image URL空字符串除上表外源码中还存在一个文档未单列的属性placeholder输入框占位文本默认Ask me anything!对应输入框的Placeholder for input field配置项见 chat.js。三、消息对象Message Object结构与校验规则每条聊天消息都是一个 Message Object完整字段定义见 Properties 文档属性说明是否必填期望值Message消息内容必填String如Hey! How can I help you?Message ID消息 ID自动生成String如e3dd6f60-d5e8-46c5-b73b-006f2f4a34f2Timestamp消息时间自动生成ISO 8601 格式 DateTime如2025-02-05T09:33:32.468ZName发送者名称可选String如John DoeAvatar发送者头像可选Image URLType消息类型必填取值response、message或errorType的三个取值决定了消息在界面中的归属message渲染为用户侧气泡名称/头像默认取User Name/User Avatarresponse渲染为应答方气泡默认取Respondent Name/Respondent Avatarerror用于展示错误提示。这一行为在源码 index.js 的 createMessage 中可以直接验证const newMessage { message, messageId: uuidv4(), // Message ID 由 uuid 自动生成 timestamp: new Date().toISOString(), // 时间戳为 ISO 8601 格式 name: name || (type message ? userName : respondentName), avatar: avatar || (type message ? userAvatar : respondentAvatar), type, };此外源码 helpers.js 中的validateSingleMessageObject会对sendMessage/appendHistory的入参做严格校验入参必须是对象message必须是字符串type必须是字符串且只能是response、error、message三者之一否则组件会弹出 toast 错误提示并拒绝写入。setHistory的入参则要求必须是数组validateMessageHistory。编写 RunJS 调用 CSA 时可以据此提前做防御性判断。四、分步实战搭建 AI 聊天机器人以下六步完整继承自 Overview 文档以接入 OpenAI 插件查询名openai1、组件名chat1为例。第 1 步拖入 Chat 组件将Chat Component拖入画布。组件默认为chat1可在画布选中后确认。第 2 步自定义组件基础属性按第二节的属性表配置四项输入Chat Title如ToolJet Support Chatbot设置Initial Chat如{{[ { message: Hey! Welcome to ToolJet. How may I help you?, type: response } ]}}配置User Name与User Avatar配置Respondent Name与Respondent Avatar。第 3 步配置 AI 查询生成响应在 Query Manager 中新建一个 AI 查询如openai1。所有可用 AI 插件可在 Marketplace 中查阅也可以使用任意数据源查询甚至把组件当作多用户聊天使用。关键点写回消息时必须在 message object 中指定type: response这样返回内容才会渲染为应答方气泡。第 4 步为查询添加事件处理器为openai1查询添加如下事件EventQuery SuccessActionControl ComponentComponentchat1从下拉框中选择你的 Chat 组件名ActionAppend HistoryMessage{{{message: queries.openai1.data, type:response}}}第 5 步为 Chat 组件添加事件处理器为chat1组件添加如下事件EventOn Message SentActionRun QueryQueryopenai1从下拉框中选择你的 AI 查询名这样就形成了闭环用户发消息 →On Message Sent触发 Run Query → 查询成功后Query Success事件把 AI 返回内容appendHistory回组件。从源码看On Message Sent事件的触发时序值得注意index.js 中组件先用 ref 标记“待发事件”在chatHistory状态更新、渲染完成后才真正fireEvent(onMessageSent)确保事件执行时用户消息已入库避免竞态。第 6 步配置响应加载状态点击Response loading state属性前的fx图标填入{{queries.openai1.isLoading}}。查询执行期间组件会显示应答方的“正在输入”占位消息对应源码中的RespondentLoadingMessage见 index.js。至此 AI 聊天机器人搭建完成。五、事件EventsChat 组件支持两个组件事件完整定义见 chat.js事件说明On history cleared每次聊天历史被清空时触发On message sent每次有消息发送时触发注意两者的触发差异通过界面输入框发送消息会自动触发On message sent而通过 CSAsendMessage()写入的消息不会自动触发该事件——源码 index.js 中明确将 CSA 通道的事件标记置为false并注释说明“用户需手动触发事件”因此若你的sendMessage也需要驱动 AI 查询请在 RunJS 中手动触发。六、组件特定动作CSACSA 可通过 RunJS 查询如components.chat1.sendMessage({...})或事件中的 Control Component 动作调用。完整清单来自 CSA 文档动作说明调用示例sendMessage()在聊天中发送一条消息components.chat1.sendMessage({message: Hey! How can I help you?, type: response})clearHistory()清空聊天历史components.chat1.clearHistory()deleteMessage()按 MessageID 删除某条消息components.chat1.deleteMessage(MessageID)downloadChat()以 JSON 格式下载聊天记录components.chat1.downloadChat()setHistory()整体设置聊天历史components.chat1.setHistory(History Object)appendHistory()追加一条聊天历史components.chat1.appendHistory(Message Object)setResponderAvatar()设置应答方头像components.chat1.setResponderAvatar(Image URL)setUserAvatar()设置用户头像components.chat1.setUserAvatar(Image URL)从源码结构看当前版本的 chat.js actions 数组 中额外还暴露了文档未列出的动作setError设置错误提示默认文案为Some error occurred. Please retry.、setHistoryLoading、setResponseLoading、setInputDisable、setVisibility。这意味着你可以在Query Failure事件里调用setError把失败信息渲染成error类型气泡而不必依赖组件自身的容错逻辑。关于downloadChat的实现细节index.js 会把当前chatHistory数组序列化为 JSON生成以chat-history-ISO时间戳.json命名的文件触发下载若历史为空则提示No chat history available to download.。七、附加动作开关Additional Actions以下开关既可通过属性面板的 toggle 直接切换也可点击fx填入逻辑表达式做动态控制见 Properties 文档动作说明源码默认值Visibility控制组件可见性trueDisable input state启用/禁用输入框falseHistory loading state启用历史加载态常配合isLoading展示进度falseResponse loading state启用响应加载态常配合isLoading展示进度falseEnable clear history button启用/禁用清空历史按钮trueEnable download history button启用/禁用下载历史按钮true默认值依据 chat.js definition 中的visibility: {{true}}、disableInput: {{false}}等配置。八、暴露变量Exposed Variables暴露变量可动态访问见 CSA 文档并与源码 exposedVariables 定义 一一对应变量说明动态访问示例history聊天历史{{components.chat1.history}}isHistoryLoading历史是否加载中{{components.chat1.isHistoryLoading}}isResponseLoading响应是否加载中{{components.chat1.isResponseLoading}}isInputDisabled输入是否被禁用{{components.chat1.isInputDisabled}}isVisible组件是否可见{{components.chat1.isVisible}}lastMessage历史中最后一条message类型消息{{components.chat1.lastMessage}}lastResponse历史中最后一条response类型消息{{components.chat1.lastResponse}}从源码实现看lastMessage与lastResponse是在每次appendHistory时按消息类型分别更新的见 index.jsclearHistory时两者都会重置为空对象index.js。典型用法用lastMessage.message作为 AI 查询的输入变量实现“携带最新用户输入调用后端”的闭环。九、消息的 Markdown 渲染Chat 组件对用户消息与响应均支持 Markdown 渲染可提升对话的可读性与结构化程度。完整语法示例见 Supported Markdown Syntax 文档支持的语法范围包括标题H1H6#至######文本格式化粗体**Text**、斜体*Text*、粗斜体***Text***、删除线~~Text~~列表无序列表含嵌套、有序列表含嵌套、任务列表- [x]/- [ ]代码行内代码code、代码块 围栏代码块引用多级嵌套引用链接与图片Link Text与Alt表格标准 Markdown 表格分隔线---/___/***HTML 内容如div stylecolor: blue;、table等行内 HTML脚注[^1]: footnote text。对 AI 聊天机器人而言这一点价值明显模型返回的 Markdown 回答代码块、列表、表格可以直接在聊天气泡中结构化渲染。十、响应式与样式组件在Devices面板提供Show on desktop与Show on mobile两个开关均支持fx动态表达式从源码 definition 可见默认为桌面显示、移动端隐藏showOnDesktop: {{true}}、showOnMobile: {{false}}。样式方面组件提供 Message、Field、Container 三组配色名称、消息体、时间戳、背景、边框、强调色、圆角等默认值均取自--cc-前缀的 CSS 变量如var(--cc-primary-text)会自动跟随深色/浅色主题切换——这一点可从 index.js 读取darkMode并附加dark-theme类的逻辑得到印证。渲染消息的 UI 拆分在frontend/src/AppBuilder/Widgets/Chat/components/目录下ChatHeader、ChatMessage、ChatInput、MarkdownMessage、RespondentLoadingMessage等。十一、小结Chat 组件的设计思路是“无状态数据 显式事件驱动”组件本身不绑定任何数据源历史数据通过initialChat/CSA 注入发送行为通过On Message Sent事件外抛。掌握第二八节的属性、消息对象、事件与 CSA 后你可以按第四节的六步流程接入任意 AI 插件构建客服机器人也可以利用history、lastMessage、downloadChat等能力将其扩展为审计、导出、多轮上下文管理更复杂的会话系统。相关文档与源码入口文档overview、properties、csa、markdown源码组件配置、组件实现、入参校验【免费下载链接】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），仅供参考