ToolJet 多页面应用（Pages）完全指南：页面面板、页面选项与页面变量

ToolJet 多页面应用Pages完全指南页面面板、页面选项与页面变量【免费下载链接】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 官方文档中关于 Pages多页面的教程完整讲解在 ToolJet App Builder 中构建多页面应用的完整流程从打开 Pages Panel 添加页面、配置导航侧边栏到管理单个页面的 Handle、首页、隐藏、复制、禁用与删除再到通过事件处理器和 RunJS 调用 Switch Page、Set/Unset Page Variable 实现页面跳转与页面级状态管理。读完本文你将掌握在 ToolJet 中搭建结构化多页面内部工具应用并借助暴露变量{{page.*}}编写动态交互的全部实战技巧。为什么需要 Pages让单个应用承载多个页面ToolJet 的 Pages 功能允许你在一个应用内创建多个页面从而让内部工具、仪表盘和业务应用的组织方式更接近真实应用形态而不是把所有内容堆叠在一个无限滚动的画布上。Pages allow you to have multiple pages in a single application, making your ToolJet applications easier to navigate and more user-friendly.多页面模式带来的直接收益包括导航更清晰通过页面导航侧边栏快速在功能模块间切换职责更聚焦每个页面承载独立业务场景如客户列表与客户详情URL 可直达每个页面拥有独立的 handleslug可通过 URL 直接定位页面级状态通过页面变量实现仅作用于当前页的局部状态避免污染全局。从源码结构看多页面能力在前端由 frontend/src/AppBuilder/AppCanvas/PageMenu/PageGroup.jsx 等组件实现它负责渲染页面导航列表、判断页面隐藏/禁用/受限状态isPageHidden || page.disabled || (page?.restricted currentMode ! edit)时不渲染并依据homePageId高亮首页。这说明页面的显示/隐藏、首页标记、禁用等配置会直接影响导航栏的实际渲染结果。打开 Pages Panel在 App Builder 中点击左侧边栏的 Pages 图标即可打开Pages PanelPages Panel 集中管理应用中全部页面是执行本文后续所有操作添加、设置、置顶、页面级操作的入口。Pages Panel 面板选项Pages Panel 的头部提供了一组面板级选项控制面板本身的行为与整个应用的导航侧边栏外观。添加页面Add Page在 Pages Panel 的头部找到按钮点击即可为应用新增页面输入新页面的名称并按 Enter 确认。设置Settings点击设置按钮后右侧会打开一个新的设置面板用于自定义应用内的页面导航侧边栏包含两个页签Properties 页签配置项说明Collapsable是否允许页面导航侧边栏折叠/收起开启后用户可将侧边栏折叠为图标模式Style导航侧边栏的展示样式可选Text only仅文本、Text icon文本图标、Icon only仅图标Hide page menu in viewer mode在**查看器模式viewer mode**下隐藏页面导航侧边栏源码印证在 PageGroup.jsx 中labelStyle?.label?.hidden与labelStyle?.icon?.hidden两个标志分别控制导航项中文本与图标是否渲染第 37、61、74 行正是上述 Style 选项三种模式的底层实现。当侧边栏未置顶!isSidebarPinned或标签被隐藏时导航项会退化为仅显示图标并配以 tooltip 展示页面名称第 37-46 行。Style 页签Style 页签用于进一步定制页面导航侧边栏的视觉样式如配色、间距等外观细节可在右侧设置面板的 Style 页签中调整。固定面板Pin默认情况下当你在面板外部点击时Pages Panel 会自动关闭。点击Pin 按钮可以将 Pages Panel 固定之后直到你再次取消固定unpin面板都不会因外部点击而关闭。页面级选项Page Options每个页面卡片右侧都有一个kebab menu竖排三点菜单点击即可展开该页面专属的操作列表页面 HandlePage HandlePage Handle 是附加在应用 URL 末尾的 slug。默认情况下handle 由页面名称自动生成全部转为小写、空格替换为连字符hyphen。以文档中的示例 URL 为例https://app.tooljet.com/applications/crm2/home其中crm2是应用名app namehome就是页面的handle。你可以点击 handle 旁边的Edit 符号手动修改 handle。从源码看前端在保存 handle 时会做标准化处理——AddNewPagePopup.jsx 中通过updatePageHandle(page.id, transformedPageHandle)更新 handle并在 eventsSlice.js 中切换页面时将 handle 统一转为小写pageHandle?.toLowerCase()因此 handle 是小写且不含空格的 slug。注意handle 是 URL 的一部分修改后请同步更新任何硬编码引用该页面 URL 的地方。重命名RenameRename允许重命名页面。关键点是重命名页面不会改变页面的 slug / page handle。因此你可以自由调整页面显示名称而不用担心破坏已有 URL 或外部链接。标记为首页Mark HomeMark Home可将某个页面设为应用的默认落地页。打开应用时被标记为 home 的页面将第一个展示。源码层面首页通过homePageId标识在 PageGroup.jsx 中通过page.id homePageId判断首页并为其显示IconHome2图标作为视觉标识。此外首页拥有一系列特权约束见下文隐藏、禁用、删除的限制确保应用始终有可访问的入口页。从应用菜单中隐藏页面Hide Page on app menuHide Page可让页面从查看器模式下的页面导航侧边栏中隐藏。需要恢复时再次进入选项菜单选择unhide即可重新显示。限制与注意点标记为 home 的页面不能被隐藏隐藏后页面不会出现在导航侧边栏中但仍然可以通过 Switch Page Action 或直接访问页面 URL 访问——隐藏只影响导航可见性不影响页面的可访问性。源码印证隐藏状态在 PageGroup.jsx 第 29-34 行生效——isPageHidden对应 getPagesVisibility为 true 的页面在导航栏中直接返回null不渲染同时禁用页面、以及查看模式下受限页面page.restricted也会被过滤这正是导航隐藏 ≠ 无法访问的实现基础。复制页面DuplicateDuplicate会在页面列表中创建并添加原页面的一个副本复制出的页面是原页面的精确复制品包含其组件、布局与配置。事件处理器Event Handlers与其他 ToolJet 组件一样页面也可以绑定事件处理器。页面专属事件为On page load页面加载时可绑定该事件的所有可用 Actions并额外支持以下页面专属 ActionsSwitch Page切换到应用内的其他页面Set Page Variable在当前页面创建并赋值页面级变量Unset Page Variable清除由 Set Page Variable 创建的页面变量。典型用法在客户详情页的On page load事件中绑定 Run Query查询指定 id 的客户数据再配合 URL 中的查询参数实现详情页的自动数据加载。实战Switch Page 动作Switch Page 动作用于在事件处理器中切换到多页面应用内的另一个页面Debounce 字段默认留空可填入数值表示执行动作前的延迟毫秒数例如300。Query Params查询参数可以随 Switch Page 一起传递查询参数参数会以?开头追加到应用 URL 末尾格式为keyvalue键值对点击按钮可添加多组参数。例如key填usernamevalue填{{globals.currentUser.email}}动态获取当前登录用户邮箱触发 Switch Page 后目标页面 URL 将携带该参数可用于过滤、分页、排序等场景。RunJS 方式调用// 仅切换页面 await actions.switchPage(page-handle) // 切换页面并携带查询参数数组形式 actions.switchPage(pageHandle, [[param1, value1], [param2, value2]])源码印证在 eventsSlice.js 的 action 解析逻辑中若事件未提供pageId但提供了pageHandle会执行pages.find((p) p.handle pageHandle.toLowerCase())?.id将 handle 解析为页面 id第 1035-1047 行若 handle 无效则抛出Invalid page handle错误随后调用switchPage(page.id, page.handle, resolvedQueryParams, moduleId)完成切换第 1072 行。实战Set / Unset Page Variable页面变量page variable与普通变量不同它被限定在创建它的那个页面内不能在整个应用中全局访问适合存放仅当前页面需要的临时状态。Set Page Variable建立变量并赋值。Debounce字段可填延迟毫秒数如300。RunJS 方式调用// 设置页面变量variablekey 必须用引号包裹为字符串 await actions.setPageVariable(variablekey, variablevalue)注意variablekey必须以字符串带引号形式提供variablevalue若为数值则不需要加引号。Unset Page Variable清除之前用 Set Page Variable 建立的变量。// 清除页面变量variablename 为创建变量时提供的 key await actions.unsetPageVariable(variablename)禁用页面Disable PageDisable Page可以禁用某个页面。被禁用的页面在查看器模式下将不可访问。限制标记为 home 的页面不能被禁用。从 PageGroup.jsx 的渲染逻辑看page.disabled为 true 的页面同样不会出现在导航栏中第 34 行从 UI 与访问两个层面共同保证禁用效果。删除页面Delete PageDelete可从应用中删除页面。限制标记为 home 的页面不能被删除。这意味着应用在任何时候都至少保留一个页面作为默认落地页。暴露变量Exposed Variables每个页面在 ToolJet 中都暴露一组可动态访问的变量供你在组件属性、查询参数和 RunJS 中通过{{ }}语法引用变量说明handle页面在应用内的 slug。在 URLhttps://app.tooljet.com/applications/crm2/home中crm2是应用名home是 handle。handle 在页面创建时自动设置也可通过 Page Options 重命名。动态访问{{page.handle}}name页面创建时设置的名称。动态访问{{page.name}}id每个页面在创建时获得的应用内唯一标识符。动态访问{{page.id}}variables一个对象包含通过Set Page Variable动作为该页面创建的全部变量。动态访问{{page.variables.pageVariableName}}其中pageVariableName是创建变量时指定的名称典型用法{{page.handle}} → 当前页面的 slug例如 home {{page.name}} → 当前页面的显示名称 {{page.id}} → 当前页面的唯一 ID {{page.variables.selectedCustomer}} → 当前页面中名为 selectedCustomer 的页面变量值源码印证前端左侧检查器Inspector对page.variables做了专门的展示支持——frontend/src/AppBuilder/LeftSidebar/LeftSidebarInspector/utils.js 中page.variables路径允许展开到第二层普通路径只展开一层path page.variables ? level 2 : level 1方便在运行时检查每个页面变量的实时值LeftSidebarInspector/Node.jsx 也对其做了对应的树形节点渲染支持。这说明页面变量是运行时状态管理的一等公民可在调试面板中直接观测。综合实战构建一个多页面 CRM 应用综合以上全部能力一个典型的多页面 CRM 应用可以这样组织添加页面在 Pages Panel 点击依次创建Dashboard、Customers、Customer Detail三个页面设置首页将Dashboard通过Mark Home标记为首页使其成为应用打开时的默认落地页调整导航样式在 Settings → Properties 中开启Collapsable并将Style设为Text icon让侧边栏更紧凑美观传递上下文在客户列表页的按钮上绑定Switch Page事件目标页选择Customer Detail并携带查询参数id {{table.selectedRow.id}}按参数加载数据在Customer Detail页的On page load事件中运行查询查询参数引用{{page.id}}、{{globals.urlparams.id}}等实现详情自动加载维护页面局部状态通过Set Page Variable保存当前页面的筛选条件/临时选择再通过{{page.variables.名称}}在页面内多处引用收尾管理对尚未完成的功能页使用Disable Page临时下线对长期不需要导航展示的页面使用Hide Page从菜单隐藏但仍可通过 URL 访问重复使用的页面模板用Duplicate快速复制后再改造。总结Pages 是 ToolJet 应用组织形态的基石。本文覆盖了从打开 Pages Panel、添加与设置页面到页面级 Handle/Rename/Home/Hide/Duplicate/Disable/Delete 管理再到 Switch Page、Set/Unset Page Variable 三种页面专属 Actions以及{{page.handle}}、{{page.name}}、{{page.id}}、{{page.variables.*}}四类暴露变量的完整使用方式并辅以 PageGroup.jsx、eventsSlice.js、LeftSidebarInspector 等源码证据验证其底层行为。遵循首页不可隐藏/禁用/删除、隐藏不等于不可访问等关键约束即可构建出结构清晰、可直达 URL、状态可控的专业级多页面应用。【免费下载链接】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），仅供参考