ToolJet App-Builder 中的 Inspector 面板使用指南：调试查询、组件与全局变量的实战手册-迪斯科星球

ToolJet App-Builder 中的 Inspector 面板使用指南：调试查询、组件与全局变量的实战手册

【免费下载链接】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（当前仓库 docs/versioned_docs/version-2.50.0-LTS/how-to/use-inspector.md）的 Inspector 功能为主题，系统讲解如何在可视化 App-Builder 中利用左侧 Inspector 面板查看查询结果、组件属性、全局变量、用户自定义变量、页面变量与工作区常量。读者完成阅读后，将掌握 Inspector 六大分区的含义、全局变量的完整字段与取值时机，并能结合事件处理器、RunJS 与常量语法在应用内引用与调试这些数据。

Inspector 是什么

Inspector 是 ToolJet App-Builder 内置的调试与检视面板，位于画布左侧边栏。它把应用运行时暴露出来的各类数据组织成一棵层级化的 JSON 对象树，让你无需写代码就能直观查看与查询（queries）、组件（components）、全局变量（globals）、用户自定义变量（variables）、页面（page）以及工作区常量（constants）相关的所有数据。

从源码结构看，Inspector 的数据来源是应用状态仓库（Zustand store）中通过getAllExposedValues()暴露的整份运行时状态快照，见 frontend/src/AppBuilder/LeftSidebar/LeftSidebarInspector/LeftSidebarInspector.jsx：

exposedComponentsVariables对应state.getAllExposedValues().components；
exposedQueries对应.queries；
exposedVariables对应.variables；
exposedConstants对应.constants；
exposedPageVariables对应.page；
exposedGlobalVariables对应.globals。

面板头部（InspectorHeader.jsx）提供标题、关闭按钮与一个实时搜索框（data-cy="inspector-search-input"），输入关键字即可在当前视图中快速定位查询名、组件名或变量路径。搜索路径集合在源码中固定为['queries', 'components', 'globals', 'variables', 'page', 'constants']（见 LeftSidebarInspector.jsx），与官方文档所列六大分区一一对应。面板默认最小宽度为 288px，且支持水平拖拽调整宽度，方便查看长路径数据。

Inspector 面板共包含 6 个主要分区：

Queries：查看查询的详情与执行结果数据；
Components：查看画布上各组件的属性与当前值；
Globals：访问与应用相关的全局信息；
Variables：查看用户通过事件处理器或查询设置的变量（键值对）；
Page：查看当前页面的属性（页面名、handle、页面变量等）；
Constants：查看工作区中定义的常量（通常是 token / 密钥 / API key）。

补充说明：当应用类型为module（模块）时，源码还会在树中追加一个Input分区，用于展示模块的输入（input）数据（见 LeftSidebarInspector.jsx），方便在模块编辑器中调试模块对外暴露的输入。

Queries：检视查询数据

Queries 分区用于检视应用中所有查询的具体信息。需要特别注意的是：查询相关数据只有在查询被执行（或触发）之后才会可见。也就是说，新建但从未运行过的查询在 Inspector 中不会显示结果数据；执行后，你可以在该查询节点下展开查看其返回的响应、请求参数与状态等信息。

源码中的格式化逻辑（utils.js）会通过queryNameIdMapping的反向映射把查询 ID 还原为查询名称，并按名称排序展示，因此即使底层以 ID 存储，面板中看到的仍是可读的查询名。

Inspector 为 Queries 分区提供了两个快捷操作（定义于 useCallbackActions.js）：

Run Query：直接重新触发该查询，适合在调试时快速重跑以刷新结果；
View query：定位并打开查询面板（Query Panel）中对应的查询编辑器。

这些操作让"在 Inspector 里看到数据 → 一键回到查询编辑器修改 → 再运行"形成闭环，极大提升数据源调试效率。

Components：分析组件属性与值

Components 分区展示你添加到画布上的所有组件（默认标注为 "Components (current page)"，即当前页面的组件）。在这里可以查看并分析每个组件的属性和当前值，了解各个组件在应用中的工作方式——例如一个表格组件的data数组、一个文本输入框当前的value、按钮的loading状态等，都可以在此展开观察。

组件数据经过formatInspectorComponentData格式化（见 LeftSidebarInspector.jsx），同时配合组件 ID 到名称的映射（componentIdNameMapping），保证树中显示的是易读的组件名而非内部 ID。

该分区同样提供上下文操作（useCallbackActions.js）：

Select Widget：在画布上选中对应组件，方便回到属性面板调整配置；
Go to component：自动滚动定位到画布中该组件的位置（若组件位于弹窗等其他容器中，会给出提示引导先打开对应容器）；
Delete Component：删除该组件（在应用处于"冻结/锁定"状态时该操作不会出现）。

提示：组件实例通常是动态的。例如在 ListView 中，同一组件会按行生成多个实例，Inspector 中展示的是当前选中行（当前作用域）下的组件值；这与源码中按行作用域（row scope）解析组件值的机制一致（参见 componentsSlice.js 中buildRowScopedState/prepareRowScope相关实现）。

Globals：访问应用级全局信息

Globals 分区让你访问与应用相关的全局信息，包含以下数据：

字段	说明
`currentUser`	当前登录用户的详细信息，如email、firstName、lastName等
`groups`	当前登录用户所属的组名列表；`all_users`组是所有用户的默认组
`theme`	当前正在使用的主题名称（如 light / dark）
`urlparams`	应用 URL 的查询参数详情（由`queryString.parse(location.search)`解析而来，见 useAppData.js）
`environment`	包含两部分：id（自动生成的唯一标识符）与name（当前应用版本所处环境的名称）
`modes`	应用的运行模式：edit（编辑模式）、preview（点击 App-Builder 中的预览按钮时的预览模式）、view（通过共享 URL 打开应用时的查看模式）

这些全局变量由源码中的setResolvedGlobals在运行时写入状态仓库。例如theme在主题切换（DarkModeToggle.jsx、AppModeToggle.jsx）时更新；currentUser、environment与theme在应用数据加载阶段统一填充（useAppData.js）；urlparams则随应用地址栏参数解析而更新。

:::info 所有全局变量都可以在 ToolJet 应用中的任何位置被访问。例如{{globals.currentUser.email}}可以直接用于文本组件或查询参数中。可参考官方示例 Access Current User 了解这些变量的典型用法（该示例文档位于仓库 docs/docs/how-to/ 目录，最新版文档中亦有对应介绍）。 :::

Variables：查看用户自定义变量

Variables 分区以键值对（key-value）格式展示用户自定义变量。这些变量通过事件处理器或查询设置，创建后可在整个应用中访问（即应用级作用域）。

你可以通过以下两种方式设置变量：

事件处理器（Event Handler）的 Set variable 动作：在组件事件或查询事件中添加该动作，为其指定Key（变量名，字符串）与Value（可以是字符串、数字、布尔表达式、数组或对象），并可设置可选的Debounce毫秒数（例如300）延迟执行。详见 docs/versioned_docs/version-2.50.0-LTS/actions/set-variable.md。
通过 JavaScript（RunJS 查询）设置：在 RunJS 查询中调用await actions.setVariable('<variableKey>', <variableValue>)完成赋值，适合在复杂逻辑中动态设置变量。相关说明见 run-actions-from-runjs。

设置完成后，即可在 Inspector 的 Variables 分区看到对应键值对；在应用的任意表达式（如{{variables.myVar}}）中引用。

Page：查看页面级属性与变量

Page 分区用于查看页面级属性，包括：

页面名称（name）；
页面 handle（即页面在 URL 中使用的路径标识）；
页面变量（variables）。

页面变量与普通变量（Variables）的关键区别在于作用域：页面变量被限制在其所属页面内，不能在应用全局范围内访问。这一设计非常适合多页面（Multipage）应用中的局部状态管理，例如某一页独有的筛选条件或临时状态。

页面变量同样可以通过事件处理器的Set page variable动作或 RunJS 查询await actions.setPageVariable('<variablekey>', <variablevalue>)进行设置，详见 set-page-var.md。注意：variablekey必须用引号包裹为字符串；variablevalue为数值时无需引号。

在源码中，Page 分区对应getAllExposedValues().page，其内部variables会按页面结构展开（utils.js 中对page.variables路径做了专门的层级限制处理），当页面没有任何变量时会显示 "No page.variables found" 之类的占位提示。

Constants：使用工作区常量

Constants 分区展示工作区常量（Workspace Constants）——即通常存放 token、密钥（secret keys）、API key 等预定义值，可在整个应用中统一使用，从而保持一致性并便于后续统一更新。

工作区常量的核心特性（详见 workspace_constants.md）：

环境特定配置：可为不同环境（Community 版仅有 production；Cloud / EE 版支持 development、staging、production 等多环境）设置不同的常量值；
服务端解析：常量只在服务端解析，网络请求的 payload 不会携带常量真实值，避免泄露到客户端；常量在入库前会加密存储（加密自 ToolJet 2.34.1 起引入，旧版本升级后已有常量会被自动加密）；
访问控制：创建、更新、删除常量仅限工作区Admins；所有具备应用编辑权限的用户都可以在 App-Builder 与全局数据源连接表单中消费常量；常量仅限本工作区使用；
使用语法：通过{{constants.constant_name}}引用。例如名为psql_host的常量，用{{constants.psql_host}}获取其值。

在 Inspector 的 Constants 分区中，你可以直接展开查看当前环境中各常量的名称与取值，确认表达式{{constants.xxx}}能否正确解析。

:::info 关于版本差异：environment 与 mode（modes）这两个全局变量仅在 ToolJet Enterprise Edition v2.2.3 及以上版本中可用。Community Edition 或更早的 EE 版本中，Inspector 的 Globals 分区不会包含这两个字段。 :::

在 Inspector 中复制与引用数据

Inspector 不仅是只读的检视器，还提供了便捷的数据引用辅助。所有树节点（尤其是查询、组件、变量）都支持两个通用操作（见 useCallbackActions.js）：

Copy value：把该节点当前的值（JSON 字符串）复制到剪贴板，方便在查询参数或组件属性中直接粘贴使用；
Copy path：复制该值在 Inspector 中的完整路径（例如components.employeesTable.data），配合{{ }}表达式即可快速写出引用，如{{components.employeesTable.data}}。

其中路径复制逻辑会把数组下标转换为方括号写法（如queries.getEmployees.data[0]），见 utils.js 中的formatPathForCopy，确保复制出的路径在表达式中合法可用。

典型调试工作流

综合以上功能，一个典型的 Inspector 调试流程如下：

在 App-Builder 左侧边栏打开Inspector，先查看Queries分区确认目标查询是否已执行、返回数据是否符合预期（未执行则点击Run Query触发）；
若查询数据正常但组件未显示，切到Components分区检查组件属性绑定（如表格的data是否指向{{queries.getEmployees.data}}），必要时使用Select Widget / Go to component快速回到画布修正绑定；
需要跨组件共享状态时，通过事件处理器或 RunJS 的actions.setVariable写入变量，然后在Variables分区确认其值；
需要在多页面间传递状态时，使用页面变量，并在Page分区核对页面名、handle 与变量；
涉及密钥、API key 等敏感配置时，统一存放在工作区常量中，通过{{constants.xxx}}引用，并在Constants分区核对当前环境下的实际取值。

通过把"运行时数据可视化"与"一键跳转 / 复制引用"结合，Inspector 让应用调试从盲猜变成了可观测、可定位、可复用的高效流程，是每个 ToolJet 应用开发者都应熟练掌握的核心工具。

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

企业官网建设流程全解析