ToolJet App-Builder 右侧边栏（Right Sidebar）完全指南：组件库、属性面板与配置检查器实战
【免费下载链接】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 的可视化应用编辑器中，右侧边栏是构建界面时使用频率最高的区域之一：它既承载着用于搭建 UI 的组件库（Components Library），也承载着用于精细化控制选中组件的属性面板（Properties Panel）。本文以 right-sidebar.md 为主体，结合 ToolJet 前端源码逐层拆解右侧边栏的组成结构、组件分区的真实映射关系、搜索匹配机制，以及属性面板如何打开、如何分区组织属性并支持事件处理。读完本文，你将能够熟练完成"从右侧组件库取组件拖入画布 → 点击组件手柄打开属性面板 → 设置值、改名、绑定数据并创建事件处理器"的完整工作流，并理解其背后对应的前端实现。
说明：文中出现的源码路径均以仓库根目录为起点，读者可按路径深入阅读；图片位于 docs/static/img/v2-beta/app-builder/rightsidebar/ 目录，为 App-Builder 右侧边栏的真实截图。
一、右侧边栏的整体定位
ToolJet App-Builder 将编辑器划分为若干区域：中央是 Canvas 画布（组件实际摆放的位置），左侧是文件/页面管理边栏，右侧就是本篇文章的主角——Right Sidebar。官方对 right-sidebar.md 的定义非常明确：
右侧边栏上的Components Library（组件库）包含所有可用的组件。你可以用它把组件从库中拖拽（drag-and-drop）到画布上。组件库将组件按分区（sections）组织，你还可以输入搜索词快速定位所需组件。
从前端实现看，右侧边栏并非单一视图，而是由 zustand store 中的状态activeRightSideBarTab驱动的多 Tab 容器。在 RightSideBar.jsx 中可以看到三种视图分支：
PAGES：页面设置（Pages / Page Settings）；COMPONENTS：组件库（Components Library，本文第二节）；CONFIGURATION：组件配置面板（Properties Panel / Config Inspector，本文第三节）。
Tab 枚举定义在 rightSidebarConstants.js：
export const RIGHT_SIDE_BAR_TAB = { COMPONENTS: 'components', CONFIGURATION: 'configuration', PAGES: 'pages', };其中COMPONENTS（组件库）与CONFIGURATION（属性面板）正是官方文档重点讲解的两个能力，对应源码目录 frontend/src/AppBuilder/RightSideBar/ComponentManagerTab/ 与 frontend/src/AppBuilder/RightSideBar/Inspector/。当画布中未选中任何组件、且当前 Tab 不是 PAGES 时，配置面板会展示"未选中组件"的空状态提示（见 ComponentConfigurationTab.jsx），并引导用户"点击画布上的组件以查看并编辑其属性"。
二、组件库：按区组织的拖拽面板
2.1 核心交互：拖放即生成组件
组件库的职责非常单一且高效：将组件从右侧拖拽到中央画布。ToolJet 的组件全部是可复用构件，官方组件目录文档将其归纳为"用于构建应用程序 UI 的构建块"（见 docs/docs/widgets/overview.md），支持拖放、选中、复制粘贴、批量框选等操作。
在画布侧，拖放由 AppCanvas/Hooks/useCanvasDropHandler.js 等 Hook 承接；在右侧组件库侧，DragLayer.jsx 为每个组件卡片提供可拖拽层。因此鼠标按住某一组件卡片拖到画布上方松开，ToolJet 便会基于该组件的定义（componentTypeDefinitionMap）在画布落点实例化一个真实组件。
2.2 分组结构：官方"分区"背后是 sectionConfig
文档强调组件库"将组件组织进多个分区（sections）"。这套分区的真实配置位于 sectionConfig.js，ComponentsManagerTab.jsx 会遍历它并用 Accordion（手风琴折叠面板）渲染每个分区。各分区与其包含的组件对应关系如下：
| 分区（Section） | 包含组件（valueSet） |
|---|---|
| Commonly used（常用） | Table、Button、Text、TextInput、DatetimePickerV2、Form |
| Buttons（按钮） | Button、ButtonGroupV2、PopoverMenu、FileButton |
| Data（数据） | Table、Chart、KeyValuePair |
| Layouts（布局） | Form、ModalV2、Container、Accordion、Tabs、Listview、Kanban、Calendar |
| Text inputs（文本输入） | TextInput、TextArea、EmailInput、PasswordInput、RichTextEditor |
| Number inputs（数字输入） | NumberInput、PhoneInput、CurrencyInput、RangeSliderV2、StarRating |
| Select inputs（选择输入） | TagsInput、DropdownV2、MultiselectV2、ToggleSwitchV2、RadioButtonV2、Checkbox、TreeSelect、Cascader |
| Date and time inputs（日期与时间输入） | DaterangePicker、DatePickerV2、TimePicker、DatetimePickerV2 |
| Navigation（导航） | Navigation、Link、Pagination、Steps |
| Media（媒体） | Icon、Image、SvgImage、PDF、Map、AudioRecorder、Camera |
| Presentation（展示） | Text、Tags、CircularProgressBar、ProgressBar、Timeline、Divider、VerticalDivider、Spinner、Statistics、Timer、JSONExplorer |
| Custom（自定义） | CustomComponent、Html、IFrame |
| Miscellaneous（杂项） | FilePicker、CodeEditor、ColorPicker、BoundedBox、QrScanner、Chat、ReorderableList、JSONEditor |
| Legacy（旧版） | Modal、Datepicker、RadioButton、ToggleSwitch、DropDown、Multiselect、RangeSlider、ButtonGroup |
源码中数组componentList由componentTypes.map((component) => component.component)派生并过滤掉IGNORED_ITEMS得到（见 ComponentsManagerTab.jsx），而每个组件的名称与displayName均来自 WidgetManager 的组件类型定义。也就是说：UI 上"分区折叠面板"与"组件元信息"是解耦的，添加新组件只需要向componentTypes注册，并把该组件名放进某个分区的valueSet即可。
2.3 搜索：基于 displayName 的模糊匹配
文档提到"可以输入搜索词快速找到组件"，其实现并非简单的字符串 includes，而是引入了fuse.js对组件的displayName做模糊搜索（fuzzy search）。相关逻辑见 ComponentsManagerTab.jsx：
const fuse = new Fuse(searchList, { keys: ['displayName'], shouldSort: true, threshold: 0.4, }); const results = fuse.search(value);几点实践细节值得注意：
- 搜索针对
displayName（如 "Text Input"）而非内部组件名（如TextInput），与用户的直觉输入习惯对齐； - 输入使用125ms 防抖（
debounce，见同文件handleSearchQueryChange），避免高频键入触发无谓搜索； - 命中后仍会调整列表中
ToggleSwitchLegacy与ToggleSwitch的展示顺序，保持新旧组件位置的稳定； - 无结果时会展示空状态（"No results found"）并提供"clear query"按钮一键清空搜索词（见 ComponentsManagerTab.jsx）；
- 在非 CE 且具备模块访问权限时，组件库顶部还会出现Components / Modules两个 Tab，可切换到模块管理（
ModuleManager），模块可像组件一样被拖入画布复用。
💡 想知道某一具体组件的每个属性、事件与使用样例？官方建议直接查阅Components Catalog / 组件目录，其中包含 Text、Table、Button、Chart、Form 等各组件专文，以及通用概念（如事件处理器、绑定、组件属性）的完整讲解。
三、属性面板（Properties Panel / Config Inspector）
3.1 属性面板是什么
官方文档对属性面板的定义是：
Properties Panel（属性面板）包含选中组件的全部可用设置，你可以在这里设置值（set values）、更新组件名（update component names）、以及创建事件处理器（create event handlers）。属性面板将设置组织为不同的分区（sections），例如Properties与Styles。
换句话说，属性面板是"无代码配置选中组件"的中央控制台：数据字段、禁用开关、可见性、事件动作、外观样式等都在此完成。工具链上它由 Inspector 目录实现，不同组件会渲染各自的专用配置界面（Table、Chart、Form、Modal、Tabs、Steps 等均有独立组件，见 Inspector/Components），通用组件则回退到DefaultComponent的默认表单。源码还维护了一份NEW_REVAMPED_COMPONENTS清单（见 Inspector.jsx），用于区分新一代组件与旧版组件在检查器中的呈现方式。
3.2 如何打开：点击组件手柄（Component Handle）
在 ToolJet 中，画布上的每一个组件顶部都悬浮着一个组件手柄（component handle），其形态是⚙️（齿轮图标）+ 组件名称。单击该手柄即可在右侧打开当前组件的属性面板。此处涉及两篇文档联动：
- 手柄本身属于画布交互，官方在 canvas.md 的 "Arrange Components" 小节说明：编辑态下所有组件都是可交互的，若要移动组件需按住组件手柄拖拽；同理，手柄也是打开配置检查器（config inspector）的入口；
- 组件手柄的核心实现位于 AppCanvas/ConfigHandle/ConfigHandle.jsx，画布选中与右侧面板的联动状态由 rightSideBarSlice.js 管理。
例如官方文档演示：当我们需要"勾选某个复选框后禁用某个按钮"时，只需点击按钮的手柄打开属性面板，在按钮的Disable属性中写入表达式{{components.checkbox1.value}}——该表达式在复选框勾选时求值为true、取消勾选时求值为false，从而实现组件间的动态联动。这正是"属性既可以手工设置，也可以用Bindings（绑定/JS 表达式）动态求值"的体现（机制详见 widgets/overview.md 的 "Bindings" 小节）。
3.3 属性面板的顶栏操作与通用结构
从前端实现 Inspector.jsx 的INSPECTOR_HEADER_OPTIONS常量可以看出，打开属性面板后其顶栏为选中组件提供五个快捷操作：
| 操作 | 说明 |
|---|---|
| Inspect | 查看组件当前状态（含运行期可访问属性、值等） |
| Rename | 重命名组件，组件名会用于表达式引用（如components.xxx.value） |
| Duplicate | 复制选中组件到画布 |
| Component permission | 配置组件级权限（Enterprise 能力，带皇冠标识） |
| Delete | 删除组件（红色E54D2E删除图标） |
在内容区，属性面板按组件类型自动组织成多个可折叠分区。文档明确提到了Properties（属性）与Styles（样式）两类典型分区：
- Properties 分区：控制组件的"数据与行为"，例如 Table 的数据源、按钮的文本、TextInput 的默认值、是否 Disabled / 是否可见（Visibility）等。这些字段支持手填与绑定表达式两种赋值方式；
- Styles 分区：控制组件的"外观"，例如背景色、文字颜色、边框、内边距、圆角等。多数样式字段同样可接入表达式以做到运行时动态样式。
补充提示：需要为整个应用页面级别定制 CSS（例如
.app-inspector等作用域类）时，可以查看 customcss.md。而工具栏（toolbar）上还提供编辑器设置、页面切换、全局设置入口等能力，可参考 toolbar.md 与 left-sidebar.md。
3.4 在属性面板中创建事件处理器
除了设置静态属性，属性面板还是**事件处理器（Event Handlers）**的创建入口。ToolJet 允许你为组件的关键事件绑定动作：例如按钮的On click、文本输入的On change、表格的On row selected等。每个事件处理器在触发时执行预定义的Action（动作），如：
- 运行某个查询（Run Query）；
- 打开/关闭弹窗、控制其他组件；
- 触发 Alert / 生成下载 / 打开链接等。
在面板中创建事件处理器的典型步骤为：点击组件手柄打开属性面板 → 找到目标事件的onClick / onChange设置区域 → 添加事件处理器 → 选择动作类型并配置参数。关于事件处理器与全部可用动作的权威参考，见组件目录文档的 "Component Event Handlers" 小节（docs/docs/widgets/overview.md）以及 Actions Reference 分类文档（docs/docs/actions/）。
四、右侧边栏与画布/其他面板的协作闭环
从官方系列文档的结构可以还原出右侧边栏在 App-Builder 完整工作流中的位置：
- 从右侧组件库拖出组件—— 本文第二节（来源：right-sidebar.md）；
- 在画布上摆布、嵌套、缩放组件—— 参见 canvas.md：组件可嵌套进 Container/Form 形成分组；可通过
cmd/ctrl + d快速克隆；可用方向键精确微调位置；按住组件手柄拖动可改变位置而不触发组件自身的交互行为； - 用右侧属性面板配置选中组件—— 本文第三节：设置值、重命名、配置 Properties/Styles、添加事件处理器；
- 用查询面板处理数据—— 数据源与查询逻辑在底部/独立的 query-panel.md 中配置，查询结果可通过
{{queries.xxx.data}}绑定回组件属性； - 预览、分享与发布—— 完成布局与逻辑后，使用编辑器右上角的 Preview 预览 查看运行效果，并通过 share.md 进行应用分发。
值得强调的是：右侧边栏的状态（是否展开、激活哪个 Tab、选中哪个组件）都由全局 store 统一管理，因此画布选中组件 → 右侧自动切换到 CONFIGURATION 视图、关闭面板后画布自动归还操作权等交互，都能保持严格同步；读者若需自定义编辑器行为，可从 frontend/src/AppBuilder/_stores/slices/rightSideBarSlice.js 与 rightSidebarToggle.jsx 切入阅读。
五、小结
右侧边栏是 ToolJet App-Builder "所见即所得"构建体验的枢纽：
- 组件库（COMPONENTS）：把 100+ 组件按Commonly used / Buttons / Data / Layouts / Text inputs / Number inputs / Select inputs / Date and time inputs / Navigation / Media / Presentation / Custom / Miscellaneous / Legacy等分区组织（映射源：sectionConfig.js），支持拖放到画布，并可通过 displayName 模糊搜索快速定位（ComponentsManagerTab.jsx）；
- 属性面板（CONFIGURATION）：点击画布组件顶部⚙️ + 组件名手柄打开，承载设置值、重命名、事件处理器、Properties/Styles 分区等全部配置能力，底层由 Inspector 按组件类型渲染（ComponentConfigurationTab.jsx）。
掌握了右侧边栏，再配合左侧页面管理、底部查询面板与顶部工具栏，就构成了完整的 ToolJet 应用搭建闭环。若要在某一具体组件（Table、Form、Chart、Kanban……）上继续深挖，直接进入 组件目录（Components Catalog） 按图索骥即可。
【免费下载链接】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），仅供参考
