ToolJet Table 组件属性完全指南：数据、事件、行选择与服务端分页实战

ToolJet Table 组件属性完全指南：数据、事件、行选择与服务端分页实战

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

Table（表格）组件是 ToolJet 中展示与管理数据的核心组件，它能够与数据库、API 无缝对接，让用户在表格内直接查看和编辑数据。本文以 Table 组件属性文档为主线，结合 Table 组件源码、组件配置定义 与官方进阶指南，系统讲解 Data、Columns、Action Buttons、Events、Row Selection、Search/Sort/Filter、Pagination、Additional actions、Devices 与 Styles 全量属性的含义、默认值与底层实现，帮助你掌握如何用 Table 组件搭建可交互、可服务端分页的数据管理界面。

Data：为表格填充数据

Table 组件的Data属性接受对象数组（array of objects）作为数据源。你可以直接在属性框中粘贴一个数组字面量，也可以通过{{queries.xxx.data}}引用某个查询（Query）的返回结果来填充表格。

示例——直接传入数组：

{{[{ id: 1, name: 'Sarah', email: '[e-mail]', contact:{number: 8881212, address: '25, Huntley Road, Newark'} }]}}

示例——引用查询数据（将restapi1替换为你的查询名称）：

{{queries.restapi1.data}}

从源码角度看，Table 组件在渲染时会读取dataSourceSelector与data两个属性：当dataSourceSelector为rawJson时，直接使用data字段的值；否则将dataSourceSelector本身作为数据来源（见 Table.jsx）。组件的默认数据（table.js 配置）是一组包含 id、name、email、date、phone、interest、photo 等字段的示例记录，覆盖了字符串、数字、日期、数组、图片等常见数据类型。

Table 组件会在提供数据后自动生成全部所需列，并自动加载一层嵌套数据（例如上例中contact对象内的number与address字段）。自动生成列的行为对应配置中的autogenerateColumns（默认true，见 table.js），底层逻辑在 autoGenerateColumns.js 中实现。

Columns：列配置

列的详细配置（列名、列类型、可编辑性、列宽、排序等）是一个独立的主题，请参阅 Columns 文档 获取完整说明。

提示：任何旁边带有fx按钮的属性都可以通过编程方式（表达式、变量）动态配置，这一规则适用于本文介绍的所有属性。

Action Buttons：操作按钮

操作按钮位于表格的最后一列，用于对当前行执行自定义动作。按钮的外观可以自定义，并且可以通过On click动作绑定事件处理器。点击某个操作按钮后，Table 的selectedRow暴露变量会更新为当前行的数据。

从源码实现看（ActionButtons.jsx），点击操作按钮时会先更新selectedRowId（行索引）与selectedRow（行原始数据）两个暴露变量，随后触发onTableActionButtonClicked事件；按钮的禁用状态支持通过disableActionButton表达式按行计算（可引用rowData与cellValue）。

下表列出了操作按钮相关的文本属性：

Property	Description
Button text	设置操作按钮上显示的文本。
Button position	将按钮位置设置为左或右。
Background color	设置操作按钮的背景色（默认值#375FCF，见 table.js）。
Text color	设置操作按钮文字的颜色（默认值#fff，见 table.js）。
Disable Action Button	开启后禁用操作按钮。也可点击旁边的fx按钮以编程方式设置，若设置为{{true}}则按钮被禁用且不可用。默认值为{{false}}。
New event handler	通过New event handler按钮为操作按钮的On click动作创建事件处理器。

Events：组件事件

Table 组件支持一系列事件，可在 Inspector 的 Events 区域中为每个事件绑定处理逻辑（如运行查询、触发其他动作）。源码中事件的完整清单定义于 table.js 的 events 段，事件的触发与暴露变量的更新集中在 TableExposedVariables.jsx 中实现。

事件	触发时机	相关暴露变量
Row hovered	鼠标指针悬停在一行上时触发	hoveredRowId（悬停行的 ID）、hoveredRow（该行数据的对象）
Row clicked	点击表格中的某一行时触发	selectedRowId、selectedRow
Save changes	点击表格页脚的Save changes按钮时触发（仅当单元格被编辑后出现）	changeSet、dataUpdates
Page changed	启用服务端分页后切换当前页时触发	pageIndex
Search	在搜索框中输入文本时触发	searchText
Cancel changes	点击页脚的Discard changes按钮时触发	—
Sort applied	点击列头应用升序或降序排序时触发	sortApplied（含column、columnKey、direction的对象）
Cell value changed	编辑表格中的任一单元格时触发	changeSet、dataUpdates
Filter changed	在筛选区域添加、移除或更新筛选条件时触发	filters（每个对象含condition、value、column）
Add new rows	点击Add new row弹窗中的Save按钮时触发	newRows

下面详解几个关键事件。

Row hovered

鼠标指针悬停于某一行时触发。hoveredRowId变量捕获悬停行的 ID，hoveredRow变量以对象格式存储该行数据。

Row clicked

点击表格某一行时触发。Table 的selectedRowId与selectedRow暴露变量分别存储所选中行的 ID 与数据。源码中该事件仅在allowSelection开启且存在lastClickedRow时触发（TableExposedVariables.jsx）。

Save changes / Cancel changes

当表格中的任一单元格被编辑后，表格页脚会出现Save changes与Discard changes两个按钮。点击Save changes触发 Save changes 事件（源码中对应onBulkUpdate），点击Discard changes触发 Cancel changes 事件（对应onCancelChanges）。编辑过程中，changeSet记录被修改的字段，dataUpdates记录被修改的行，二者可在事件处理器中用于构造更新数据源的查询。

Page changed

启用服务端分页后，切换当前页时触发。该事件在pageIndex变量更新后触发，可用于执行查询以加载下一页数据。源码实现（TableExposedVariables.jsx）显示：仅当通过分页按钮或页脚输入框换页时才触发onPageChanged，而通过setPage动作编程换页时不会触发，以保持向后兼容。

Search

在表格搜索框中输入文本时触发。触发前会先更新searchText变量。源码中搜索文本变化即同步暴露searchText并触发onSearch（TableExposedVariables.jsx）。

Sort applied

点击列名表头应用升序（asc）或降序（desc）排序时触发。sortApplied变量更新为包含column与direction的对象（源码中还额外暴露了columnKey，见 TableExposedVariables.jsx）。排序被清除时同样会触发该事件，此时sortApplied为空数组。

Cell value changed

编辑表格中的任一单元格后触发，可用于实时监听数据变更。源码中每当编辑行或编辑字段集合发生变化时即触发onCellValueChanged（TableExposedVariables.jsx）。

Filter changed

在筛选区域添加、移除或更新筛选条件时触发。filters变量更新为当前生效的筛选条件集合，每个对象包含condition、value与column三个属性。源码在筛选条件变化时暴露filters并触发onFilterChanged（TableExposedVariables.jsx）。

Add new rows

点击Add new row弹窗中的Save按钮时触发，可配合newRows变量执行查询，将新行写入数据源。

Row Selection：行选择

Allow selection

该选项默认开启。开启后用户可以通过每行旁边的**复选框（checkbox）**选中行；若关闭，则无法高亮选中行，也无法进行批量选择。

Highlight selected row

开启后，视觉上突出显示最后点击的行，行选择外观将从复选框主题切换为高亮主题。

Bulk selection

在 Inspector 中开启Bulk selection后，可以选中当前页的一行或多行。选中行的值会保存在selectedRows暴露变量中。从源码看，selectedRows仅在allowSelection与showBulkSelector同时开启时才会被填充（TableExposedVariables.jsx），并且还额外暴露了selectedRowsId。

Default selected row

默认选中行仅在Allow selection开启时可用。要设置默认选中行，需要提供一个仅包含单个键值对的对象，例如使用id作为键、从变量x动态取值：

{{{"id": variables.x}}} // 假设 variables.x 已设置为一个合法的数值 id

请确保对象中提供的值对应表格中的真实 id，否则该功能无法正常工作。源码实现（TableExposedVariables.jsx）会取对象第一个键作为匹配键，在数据中查找匹配项并设置为选中行，同时更新selectedRow与selectedRowId。

Select row on cell edit

为列开启Make editable属性后，应用用户即可编辑该列。编辑时相关行会默认被选中；若希望编辑时不自动选中行，请关闭Select row on cell edit。

Search、Sort 与 Filter：搜索、排序与筛选

Table 的搜索、排序与筛选默认在客户端（浏览器内）执行，同时也支持切换到服务端模式，将搜索词、排序与筛选条件通过事件暴露出来，交由查询去数据源端处理。

Show search

Show search属性控制表格上的搜索框。客户端搜索默认开启；服务端搜索可在 Inspector 的 events 区域启用。每当搜索文本变化时，searchText暴露变量都会更新。

Server-side search

若启用服务端搜索，Search事件会在searchText变量内容变化后触发。你可以用searchText运行特定查询，在数据源中检索记录。

Enable column sorting

关闭此选项可锁定列排序，用户点击列头时不会进行排序。

Server-side sort

启用服务端排序后，点击列头不会自动对表格排序，而是触发Sort applied事件，并在sortApplied暴露变量中暴露当前排序。你可以利用这一信息执行查询，按指定排序更新表格内容。源码中sortApplied的典型结构为[{ column, columnKey, direction }]，其中direction为asc或desc（TableExposedVariables.jsx）。

Enable filtering

Table 表头的筛选按钮默认可见，关闭此选项可将其隐藏。表格数据可以通过左上角的 Filter data 选项进行筛选，可选的筛选条件包括：

• contains（包含）
• does not contain（不包含）
• matches（匹配）
• does not match（不匹配）
• equals（等于）
• does not equal（不等于）
• is empty（为空）
• is not empty（不为空）
• greater than（大于）
• greater than or equal to（大于等于）
• less than（小于）
• less than or equal to（小于等于）

这些筛选条件的完整清单在源码 filterConstants.js 中定义，对应的执行逻辑位于 filterUtils.js。

Server-side filter

启用服务端筛选后，应用筛选条件不会自动过滤表格，而是触发Filter changed事件，并在filters暴露变量中暴露当前筛选条件。你可以利用这些数据执行查询，按所应用的筛选条件更新表格内容。filters中每个对象的属性为condition、value和column（见 TableExposedVariables.jsx）。

Pagination：分页

分页通过将大数据集划分为可管理的分段来优化显示。客户端分页默认开启。开启后会出现额外属性Number of rows per page（每页记录数），默认值为10；若禁用分页，则所有记录显示在同一页。

在源码配置中，分页相关属性包括enablePagination（默认true）、rowsPerPage（默认10）以及serverSidePagination（默认false，见 table.js）。

Server-side pagination

服务端分页可用于在切换页面时运行查询。在 events 区域可以使用Page changed事件执行查询，并配合pageIndex暴露变量使用。pageIndex可用于在换页时查询下一组结果（例如结合 SQL 的LIMIT与OFFSET）。启用服务端分页后，还会出现另外三个 Table 属性：

• Enable previous page button：关闭以禁用表格中的上一页按钮。
• Enable next page button：关闭以禁用表格中的下一页按钮。
• Total records server side：设置一个数值以显示特定数量的记录（默认10）。

提示：可参考官方进阶指南 Using Server Side Pagination in Tables，了解如何基于 PostgreSQL 等支持limit和offset的数据库实现服务端分页：例如查询SELECT * FROM users LIMIT {{(components.table1.pageIndex - 1) * 10}} OFFSET 0，并配合Page changed事件与pageIndex变量分块拉取数据。

Additional actions：附加操作

Show add new row button

Add new row 按钮位于表格右下角，默认可见，关闭此选项可隐藏。点击该按钮会弹出模态框，用户可插入新行。用户在该行输入的数据会保存在 Table 关联的newRows暴露变量中；点击Discard按钮会清空该变量中的数据；但如果用户未保存也未放弃就关闭弹窗，数据会保留。Table 内置了Add new rows事件处理器，可在点击Save按钮时执行查询将数据写入数据源。源码中newRows由 addNewRow 状态推导并暴露（TableExposedVariables.jsx），弹窗实现位于 AddNewRow.jsx。

Show download button

表格页脚的下载按钮默认可见，关闭此选项可隐藏。下载按钮允许用户以三种格式下载表格数据——CSV、Excel 和 PDF。

下载文件的命名格式为：

Tablename_DD-MM-YYYY_HH-mm.filetype

示例：Customers_25-03-2022_16-10.csv

从源码看，导出逻辑在 exportData.js 中实现：CSV 使用 Papa Parse 序列化，Excel 使用 zipcelx 生成，PDF 则按需动态加载 jsPDF 与 jspdf-autotable（约 600KB，懒加载以减小初始包体积）；文件名统一由getExportFileName生成，格式为组件名_时间戳（exportData.js）。

Hide column selector button

表格页脚的列选择器按钮默认可见，关闭此选项可隐藏。列选择器允许你定义要在表格中查看哪些列。

Loading state

Loading state 为 Table 显示加载骨架屏，可在数据加载期间展示加载状态。查询的isLoading属性可用于获取查询的状态。

Show update buttons

更新按钮默认开启。每当单元格被编辑时，表格页脚会显示Save changes和Discard changes两个更新按钮，关闭此选项可隐藏更新按钮。

Visibility

Visibility（可见性）条件允许你控制 Table 在画布上是显示还是隐藏。默认开启，可关闭以隐藏 Table。

Disable

Disable（禁用）条件允许你控制 Table 在画布上是启用还是禁用。默认开启，可关闭以禁用 Table；禁用后 Table 将不可交互。

Devices：设备可见性

Property	Description	Expected value
Show on desktop	使组件在桌面视图中可见。	可通过开关设置，或点击fx输入逻辑表达式动态配置值。
Show on mobile	使组件在移动视图中可见。	可通过开关设置，或点击fx输入逻辑表达式动态配置值。

两个属性的默认值分别为{{true}}与{{false}}（见 table.js）。

Styles：样式

Data（数据区样式）

Style Property	Description	Configuration Options
Text color	更改组件的文本颜色。	提供hex 颜色代码、从取色器中选择，或通过fx以编程方式设置。
Row style	选择表格行的样式。	从下拉框选择：Bordered、Regular 或 Striped，也可通过fx以编程方式设置（对应源码中的table-classic、table-bordered、table-striped）。
Cell height	决定表格单元格的大小。	在Condensed或Regular之间选择，也可通过fx以编程方式设置。
Max row height	当启用Content wrap时控制行的最大高度。	选择Auto或定义Custom尺寸，也可通过fx以编程方式设置。

Action Button（操作按钮样式）

Action	Description	Configuration Options
Button radius	设置所有操作按钮的圆角半径。	输入数值（默认0）或通过fx动态配置。

Container（容器样式）

Style Property	Description	Configuration Options
Border radius	为 Table 的边框添加圆角。	输入数值（默认8）或通过fx动态配置。
Border	定义 Table 的边框颜色。	通过提供hex 颜色代码、从取色器中选择或通过fx以编程方式更改颜色。
Box shadow	设置组件的盒阴影属性。	选择盒阴影颜色、调整相关属性，或通过fx以编程方式设置。

样式属性的完整定义（含默认值、类型与所属分组）可在 table.js 的 styles 段 中查看，例如容器背景containerBackgroundColor、选中行颜色selectedRowColor、列头分组下的标题颜色与背景等，均可按需调整。

小结

Table 组件通过Data属性灵活接入静态数组或查询结果，自动生成列并支持嵌套数据；通过selectedRow、selectedRows、newRows、changeSet、dataUpdates、pageIndex、searchText、sortApplied、filters等一整套暴露变量与 Row hovered、Row clicked、Save changes、Page changed、Search、Sort applied、Filter changed、Add new rows 等事件，与查询系统紧密联动；搜索、排序、筛选与分页均可在客户端与服务端两种模式间切换，满足从小数据集到大规模数据源的各种场景。深入阅读 Table 组件实现、组件属性配置 以及 列配置文档，即可在此基础上构建完整的数据管理界面。

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