HyperDX 页面布局指南：深入解析 PageHeader 与 PageLayout 共享页头体系

可观测性云原生运维【免费下载链接】hyperdxResolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors powered by ClickHouse and OpenTelemetry.项目地址https://gitcode.com/gh_mirrors/hy/hyperdx点击查看免费下载HyperDX 的 App 页面共用一套「粘性顶栏 可滚动内容区」的页面骨架左导航AppNav 统一滚动容器之上是吸顶的PageHeader页头页头下方才是各自页面的内容区。本文以 agent_docs/page_layout.md 为骨架结合 PageHeader.tsx、PageLayout.tsx 及 Alerts、Service Map、Kubernetes Dashboard、Sessions、Dashboard 等真实页面源码系统讲解两个共享布局原语primitive的完整 API、三种页面形态的选型规则、常见反模式与迁移步骤。读完本文你将掌握在 HyperDX 中新增或改造页面时如何用一致的方式组织标题、面包屑、来源选择器、时间范围与主操作按钮保证 Search、列表页与工具页Service Map、Kubernetes、Chart Explorer的视觉与交互一致。为什么需要统一的页头体系HyperDX App 的所有受保护页面都运行在同一套外壳中。查看 packages/app/src/layout.tsxwithAppNav负责把页面包装进HDXSpotlightProvider与PageWrapperPageWrapper左侧渲染AppNav右侧是带有APP_CONTENT_SCROLL_CONTAINER_ID的滚动容器overflowY: scroll所有页面内容都在这个容器内滚动。这意味着页面的吸顶是相对于这个滚动容器而言的而非整个浏览器窗口任何页面若各自用Text sizexl写一个标题、再手动拼一个Group justifyspace-between工具条都会在边距、字号、吸顶层级和滚动行为上与相邻页面产生肉眼可见的差异。统一页头page chrome的职责由此而来让标题、控件与间距在 Search、列表页和工具页之间保持一致。两个核心组件PageHeader 与 PageLayoutpage_layout.md 给出了两个组件的选型结论仓库中两个组件相邻位于packages/app/src/components/组件路径使用场景PageHeaderpackages/app/src/components/PageHeader.tsx只需要页头栏页面已有自己的内容包装器PageLayoutpackages/app/src/components/PageLayout.tsx需要页头 flex 内容列一个包装器搞定新页面推荐两者都位于withAppNavpackages/app/src/layout.tsx之下后者提供左侧导航与滚动容器。从源码看PageLayout本质上是PageHeader的薄封装PageLayoutProps通过PickPageHeaderProps, title | leading | actions | breadcrumbs | children透传页头插槽未传入自定义header时内部自动构造一个PageHeaderPageLayout.tsx。因此插槽语义完全继承自PageHeader。PageHeader API 详解PageHeader.tsx 的类型定义中PageHeaderProps提供了两种组合形式源码注释按优先级明确标注结构化插槽title/leading/actions/breadcrumbs。适用于标题或面包屑轨迹 水平工具条能清晰拆成左侧组 右侧组的标准页头自定义children用于工具条无法表达为leading actions的页面例如 Sessions 全宽混合控件行仅在结构化插槽会歪曲预期布局时才使用。基础用法PageHeader titleAlerts / {/* 粘性栏包含输入控件时不传 title把面包屑传进页头 */} PageHeader breadcrumbs{Breadcrumbs.../Breadcrumbs} leading{SourceSelectControlled ... /} actions{TimePicker ... /} / PageHeader {/* 自定义标题行例如 Team 设置里可编辑的团队名 */} /PageHeaderProps 语义对照表Prop用途title纯文本页面标题h1。仅当粘性栏没有输入控件时使用列表/设置页。如果栏上有选择器、搜索、滑块或 Run 按钮必须省略title改用breadcrumbs或仅靠导航 文档标题表达位置。源码中toolbarInner仅在title ! null时渲染h1 className{styles.title}PageHeader.tsxbreadcrumbs粘性页头内部的位置轨迹当leading/actions存在时渲染在工具条上方。使用 MantineBreadcrumbs如Dashboards→ 当前页。不要与title重复同一页面名称。渲染逻辑见hasBreadcrumbs hasToolbar分支此时页头应用headerStacked样式PageHeader.tsxleading左侧簇来源选择器、徽章或其他控件。存在输入控件时不要与同一页面名的title配对actions右侧簇时间范围、Run/Save、采样、刷新children插槽不够用时的完整自定义页头。除非走纯面包屑分支否则不要与title/leading/actions/breadcrumbs混用growing启用块级内边距只在工具条超过min-height时出现的行为。Sessions 的多行搜索使用它纯标题页省略它stickyRow指定页头中唯一吸顶的行其余页头 chrome 随页面滚动消失用于 Dashboard 这类面包屑 可编辑名 查询工具条的高页头见下文进阶章节className/data-testid页头样式类与 E2E 测试定位锚点样式与行为细节源码级样式定义在 PageHeader.module.scss吸顶与分隔.header设置position: sticky; top: 0带border-bottom: 1px solid var(--color-border)与 Search 页的pxsm对齐水平内边距为var(--mantine-spacing-sm)最小高度单行页头保持min-height: 60px堆叠页头面包屑 工具条通过.headerStacked改为纵向布局flex-direction: column、min-height: auto随内容生长层级z-index: 2源码注释明确说明该应用顶层抽屉渲染在contextZIndex 10即 10页头保持比抽屉低 8 层保证抽屉遮罩始终覆盖页面 chrome同时页头仍浮于普通滚动内容之上PageHeader.module.scssgrowing行为.header.growing:not(.notSticky)增加padding-block: var(--mantine-spacing-xs)。块级内边距在静止时被吸收只有当行超过页头高度Sessions 的多行搜索才显现避免查询框贴边而纯标题页保持零块内边距60px 单行不产生位移PageHeader.module.scss行内排版.start标题 leadingflex: 1.actions固定不收缩且gap: 12px.title继承字号/字重、white-space: nowrap避免标题换行破坏单行布局。PageLayout API 详解PageLayout >PageLayout >// ❌ 在页面主体里临时写标题 Group justifyspace-between Text sizexlService Map/Text TimePicker ... / /Group // ✅ 工具页面包屑进页头、输入控件在同一个粘性块中无 title PageLayout breadcrumbs{Breadcrumbs.../Breadcrumbs} leading{SourceSelect ... /} actions{TimePicker ... /} content{.../} / // ❌ title 与面包屑重复同一页面名 PageLayout titleKubernetes Dashboard breadcrumbs{Breadcrumbs… Kubernetes/Breadcrumbs} / // ❌ 用 Box 把整个页面包括标题包一层重复 padding Box psm Text sizexlAlerts/Text ... /Box // ✅ 页头在 padding 区之外 PageHeader titleAlerts / Container pylg.../Container几点原理补充禁止主体内Text sizexl标题这样的标题不在粘性页头内、不参与统一排版滚动时也不会吸顶破坏跨页一致性禁止title与breadcrumbs文案重复两者表达同一定位信息会产生冗余若栏上有输入控件title还会导致h1与工具条争夺单行空间禁止重复 padding 包裹PageHeader自带--mantine-spacing-sm水平内边距页面主体再包一层psm会造成双重留白正确做法是页头在 padding 区之外内容用Container/padded自行控制。迁移现有页面六步走用PageLayout或PageHeader插槽替换Text sizexl标题 Group justifyspace-between把时间选择器与主操作按钮移到actions把来源选择器和徽章移到leading如果粘性栏有输入控件不要设置title当路由存在层级时把breadcrumbs传给PageLayout面包屑渲染在粘性PageHeader内部而不是content里在PageLayout/ 页面根节点保留data-testid供 E2E 测试使用——例如 AlertsPage.tsx 的data-testidalerts-page被 tests/e2e/page-objects/AlertsPage.ts 的page.locator([data-testidalerts-page])引用Service Map 的data-testidservice-map-page与 Kubernetes Dashboard 的data-testidkubernetes-dashboard-page同理运行受影响的 Playwright 测试packages/app/tests/e2e/。变更后记得跑 Knippackages/app的 Knip 入口根是pages/、scripts/和 e2e 测试。新增或移动PageLayout导入后请从仓库根目录运行yarn knip若packages/app单独配置了则在其目录下执行yarn knip确保新增的消费方仍然被正确接线、没有未使用或未声明的导入残留。小结选型一句话只差页头用PageHeader页头 内容一体的新页面用PageLayout输入控件决定 title 取舍粘性栏有任何输入控件就省略title用breadcrumbs在页头内部表达位置全局控件在actions、上下文控件在leading全高画布加fillViewport复杂形态走自定义槽Search/Chart Explorer 保留定制工具条Sessions 用header承载单行工具条Dashboard 用stickyRow钉住查询工具条保持可测性与可维护性data-testid落在布局根节点改动后跑 e2e 与yarn knip。这套体系的源码、样式与全部真实用例都集中在packages/app/src/components/PageHeader.tsx、packages/app/src/components/PageLayout.tsx与各自.module.scss中新增页面时直接对照上述规则即可与既有页面保持一致。赞分享可观测性云原生运维【免费下载链接】hyperdxResolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors powered by ClickHouse and OpenTelemetry.项目地址https://gitcode.com/gh_mirrors/hy/hyperdx点击查看免费下载相关推荐YouTube.js 节点解析实战深入剖析 PageHeader 页面头部节点类YouTube.js 节点解析实战深入剖析 PageHeader 页面头部节点类 PageHeader 是 YouTube.jsInnerTube API后端AntdUI页头控件PageHeader的标题显示与面包屑导航AntdUI页头控件PageHeader的标题显示与面包屑导航 还在为WinForm应用缺乏现代化界面而烦恼吗AntdUI的PageHeader控件为你提供UI组件桌面应用如何快速美化你的Terminal终端Terminator Themes终极指南如何快速美化你的Terminal终端Terminator Themes终极指南 你是否厌倦了单调的黑色终端界面想让你的编程环境既美观又高效Terminat上一篇本地离线语音转文字工具TMSpeech上手指南让电脑声音实时变字幕会议记录提速3倍下一篇NumPy 1.17.5 补丁版本技术解析关键 Bug 修复、构建改进与升级注意事项创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考