跳转至

LayoutPanel 组件契约

契约概览

领域 契约
公共契约 children、width、resizable、hasDivider、isScrollable、padding、label、role、根 BaseProps 以及根 ref。
行为 位于逻辑起始端或结束端的固定宽度侧边区域,默认滚动,并可在其朝向内容的一侧设置可选分隔线。
最终用户影响 用户会看到一个保持自身宽度、独立滚动,并在从右到左布局中镜像到另一侧的侧边面板。
构建者影响 resizable 直接接收 useResizable 的输出,或像以前一样接收其 props(FR8);可折叠的可调整大小面板会滑动,可滚动面板会获得 role 和名称,且无需更改代码。
兼容性/就绪状态 resizable 也接收 useResizable 的输出(FR8)。可折叠面板会滑动(FR7),将焦点移出并进入 inert 状态(AR2),可滚动面板会被命名(AR3)。补丁:[feat] 类型与滑动,[fix] 焦点与名称。
审查检查 拒绝位于外边缘的分隔线、会收缩的面板、推断的 landmark、width 优先于 resizable,或任何进一步的发布不匹配。
治理规则 family:layout-regions FR1、FR2、FR4–FR8、FR10;architecture:container-padding;architecture:public-component-api INV5–INV8。

此表是审查投影;下文正文为权威内容。

意图

LayoutPanel 是调用方放置在 Layout 的 start 或 end 插槽中的侧边区域。它拥有面板的宽度、内边距、滚动、分隔线以及 调用方提供的 landmark 语义;调用方拥有其内容。

消费者语法和示例属于 LayoutPanel.doc.mjs。

兼容性与迁移

  • 已发布默认值保持:yes — 无分隔线、可滚动、自动内边距、内容宽度。
  • 兼容性类别:patch。resizable 也接收 useResizable 的输出(FR8, [feat]);没有其他公共 prop、目标或样式输出发生变化,且 省略的 prop 行为与之前相同。可折叠的可调整大小面板现在会滑动(FR7, [feat],仅在 spec:AST-017/DEC-17 下为视觉变化),且其内部焦点会移动 到相邻的 ResizeHandle,同时折叠后的面板变为 inert(DOM: inert 和 aria-hidden;AR2,[fix],位于 spec:AST-017 FR53 下)。在滚动时, 没有调用方 role 的面板会获得 role="group" 和 aria-label(DOM;AR3,[fix],位于 spec:AST-017 FR53 下)。
  • 受控/非受控行为:不适用
  • 迁移决策:无

消费者迁移说明属于消费者文档和发布说明。

当前状态影响

  • 两个分隔线所有者可能绘制同一边界(FR4)。 带有 hasDivider 的面板紧邻绘制同一条线的 ResizeHandle 时, 会绘制两次边界;没有任何机制阻止这一点,因此当 ResizeHandle 拥有该线条时,调用方需保持 hasDivider={false} (family:layout-regions FR5)。

所有权边界

拥有

  • 面板根元素,其承载 layout-panel 目标,由 component:Layout 映射。
  • 面板宽度、内边距、滚动、分隔线,以及调用方提供的 role 和 label。

不拥有 / 非目标

  • 插槽放置和 Layout 边缘内边距 — 由 component:Layout 拥有。
  • 调整大小交互和调整大小手柄 — 由 useResizable 和 ResizeHandle 拥有(family:layout-regions FR10)。
  • 面板内容及其含义 — 由调用方拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
Width number(px);CSS 长度字符串;未设置 面板的内联尺寸。 始终 内容宽度 component:LayoutPanel 稳定 —
Resizable useResizable 的值 提供可调整大小的宽度,优先于 width。 始终 无 component:LayoutPanel 稳定 —
Divider true、false 在面板朝向内容的一侧绘制一条线。 起始或结束插槽 false component:LayoutPanel 稳定 —
Scrolling true、false 滚动溢出内容,或裁剪它。 始终 true component:LayoutPanel 稳定 —
Inset 间距步长;0;未设置 替换自动内边距的均匀内边距;0 表示完全出血。 始终 自动 component:LayoutPanel 稳定 封闭联合;由类型拒绝。
Landmark 调用方的 role 和 label 将面板暴露为调用方所指定的 role,并带有该可访问名称。 始终 无 调用方 稳定 —

行为与布局契约

ID 不变量 依据
FR1 LayoutPanel 渲染一个 div,该 div 带有 layout-panel 目标,不会收缩,并直接容纳子元素。width 设置其内联尺寸,数字按像素计;resizable 值的尺寸优先于 width。默认情况下它会滚动溢出内容;isScrollable={false} 则将其裁剪。 当前源码和测试;family:layout-regions FR7、FR10
FR2 在 start 插槽中,面板面向内容的一边是其 inline end;在 end 插槽中,则是其 inline start;两者都遵循书写方向。 当前源码和测试;family:layout-regions FR2
FR3 在没有 padding 时,面板的外侧内联边采用 Layout 边缘内边距,没有页眉或页脚相邻的块边采用 Layout 边缘内边距,其他边采用内部内边距;其中 Layout 边缘内边距来自 Layout 的 padding,否则来自最近的 padding 容器,内部内边距来自最近的 padding 容器(Card、Section、Dialog、Drawer 或 BottomSheet),否则每个间距步长为 4。padding 步长会替换全部四条边,0 会移除它们。面板发布的 container-padding 值等于它所应用的内边距,因此全出血(full-bleed)子元素会与它的外边缘对齐。 当前源码;family:layout-regions FR4;architecture:container-padding
FR4 hasDivider 会在面向内容的一边上绘制一条 1px 实线 --color-border;LayoutPanel 不读取 Layout 的分隔线默认值。在没有分隔线且使用自动内边距时,面板会按内部内边距与内容区域重叠,从而使两者共享同一个间隙。一个边界只有一个分隔线所有者(family:layout-regions FR5)。实现差距:没有任何机制阻止面板分隔线与相邻的 ResizeHandle 线条同时绘制(当前状态影响)。 当前源码和文档;family:layout-regions FR5、FR6
FR5 role 和 label 设置根元素的 role 和 aria-label;LayoutPanel 仅在其滚动时(AR3)才会自行添加 role 和名称。 当前源码和测试;family:layout-regions FR8
FR6 ref 到达根元素。受支持的 DOM、data、ARIA 和事件 props 在组件自身属性之后到达根元素;xstyle、className 和 style 在组件样式之后组合。 当前源码与测试;architecture:public-component-api INV5–INV8
FR7 一个 LayoutPanel,其尺寸来自调整大小控制器,会通过内部通道将其元素提供给其内容朝向边缘上的 ResizeHandle 的控制器;因此,当面板的区域折叠或展开时,面板会通过 spec:AST-105 FR9 的边缘显露而滑动关闭和打开:其内容朝向边缘(FR2)移动,该边缘一侧的内容以相同的运动移动(component:Resizable FR8)。给定配置对象形式的面板(即手工构建的、并非 useResizable 返回的 ResizableProps 对象,通过 resizable 传入),以及没有调整大小控制器的面板,永远不会滑动;而通过 resizable 传入的 useResizable 自身的 props 则会滑动。LayoutPanel 不新增任何 prop。在该手柄旁边、尺寸为该区域大小的面板不会滑动。 spec:AST-105 FR9;component:Resizable FR8
FR8 resizable 直接接受 useResizable 的输出;区域的 props 仍被接受(所有者决定,2026-11-04)。面板通过该槽位 prop 获取 hook 的值(所有者决定,2026-11-04)。 component:Resizable FR9;architecture:public-component-api INV21

允许的变体

  • AV1 — 内容。 任何调用者内容都可以填充面板。
  • AV2 — 位置。 调用者将面板放置在起始端、结束端或两端。

代表性状态

状态 必需的不变量 允许的变体
起始面板 分隔线和共享间隙位于 inline-end 边缘。 宽度。
结束面板 分隔线和共享间隙位于 inline-start 边缘。 宽度。
从右到左 起始端和结束端镜像对调。 —
可调整大小 可调整大小的尺寸设置宽度。 尺寸。
折叠中 面板从内容朝向边缘滑动关闭;其内部焦点移至 ResizeHandle;随后它处于惰性状态。 起始端或结束端;减少动态效果;不带滑动效果的配置对象形式。
导航地标 role="navigation" 以及调用者在根元素上的名称。 名称。

转换与优先级顺序

  • ORD1 — 宽度。 resizable 尺寸 → width → 内容宽度。
  • ORD2 — 内边距。 padding → 每条边自动应用 inset。

性能与资源

  • PR1 — 无外部生命周期。 LayoutPanel 读取自身的 slot 以及其 Layout 所填充的 slots。除了在可能滚动时执行 AR3 的溢出观察外,它不添加任何自身的监听器、观察器、定时器或测量逻辑;滑动的测量由 resize 控制器负责(FR7)。

无障碍契约

  • AR1 — 仅显式地标。 仅当调用方提供 role 时,面板才是地标(landmark),且其名称只能来自调用方的 label(family:layout-regions FR8)。
  • AR2 — 焦点离开折叠中的面板。 当面板区域在焦点位于面板内部时折叠,在任意 resize 控制器下(包括配置对象形式,FR7),焦点都会移动到面板面向内容边缘上的相邻 ResizeHandle——即重新打开面板的控件;折叠后的面板随即变为 inert 并设置 aria-hidden,直到它重新打开(spec:AST-105 FR9)。打开操作不会移动焦点。从 Handle 或面板外部控件发起的折叠会让焦点保持在原处。只有滑动(slide,FR7)不涉及配置对象形式。
  • AR3 — 滚动的面板具有名称。 当面板滚动时,其滚动元素具有 role="group"(除非调用方设置了 role)和一个可访问名称(调用方的 label,或翻译后的“Content”),这样当屏幕阅读器到达它(包括作为浏览器生成的 Tab 停留点)时就会播报它;Tab 行为由浏览器决定(所有者决定,2026-11-04)。调用方的 role 只接受调用方的 label(AR1)。当浏览器不将其作为 Tab 停留点时,如果滚动区域的内容中没有任何可聚焦项,则无法通过键盘滚动该区域。此时调用方需要添加一个可聚焦子项,或使用 ScrollableArea。

设计关系

解剖结构或状态 设计需求 表示权威 层级角色 组件契约
面板(Panel) 固定的侧边区域,带有可选的面朝内容的分隔线。 当前源代码与文档 支撑(Supporting) FR1–FR4

主题化:根元素带有 layout-panel 目标,该目标由 Layout.doc.mjs 声明并由 component:Layout 映射。LayoutPanel.doc.mjs 未声明自身的解剖结构,因此此处不声明解剖结构主题块。

家族与系统关系

  • family:layout-regions 负责区域方向、内边距替换、边界归属、分隔线间距、滚动、地标和 resize 委托;FR1–FR5 与 AR1 应用这些规则。
  • spec:AST-105 FR9 负责 FR7 所播放的边缘揭示,以及 AR2 所应用的焦点规则;component:Resizable FR8 负责其播放时机。
  • architecture:container-padding 负责 inset 发布;FR3 应用该规则。
  • component:Layout 负责 slot 放置、Layout 边缘 inset 以及 layout-panel 目标映射。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, ORD1 LayoutSlots.test.tsx 的 class、宽度和 resizable 测试;collapsedPanel.interaction.browser.spec.ts 中针对宽度 0 的测试 数值、字符串与零宽度;resizable;折叠区域 丢失 layout-panel class、缺少宽度,或 width 优先于 resizable 都会失败。缺口:不可收缩的根元素、滚动行为以及 isScrollable={false} 均没有检查。当面板内没有可聚焦内容时,没有任何需求或检查覆盖键盘用户如何到达滚动面板的溢出内容。 audit:LayoutPanel/layout
FR2 LayoutSlots.test.tsx 的 start 与 end slot 测试;Layout.a11y.chromium.spec.ts 的 start-end-navigation-rtl 状态 Start 与 end 面板;从右到左(RTL) 面板在任一 slot 中渲染失败即为失败。缺口:没有检查断言哪条边承载分隔线或共享间距。 audit:LayoutPanel/layout
FR3, ORD2 nestedPadding.test.tsx 中的 LayoutPanel 发布测试;LayoutPanelAudit.a11y.chromium.spec.ts 中的 inset 与 full-bleed 验收 自动、显式和零内边距 如果发布后的边缘与面板应用的内边距不一致、边缘的 inset 错误,或 full-bleed 子元素超出面板的外边缘,则测试失败。 audit:LayoutPanel/layout
FR4 源码审查 hasDivider;无分隔线 缺口:没有测试覆盖分隔线、共享间隙,或 ResizeHandle 旁的面板分隔线。 audit:LayoutPanel/layout
FR5, AR1 LayoutSlots.test.tsx 中的 landmark 测试;Layout.a11y.test.tsx 和 Layout.a11y.chromium.spec.ts 中的 start-end-navigation-rtl 与 nested-panel-region 状态 调用方的 navigation 和 region 角色及标签 角色或名称丢失即失败,包括在无障碍树中的丢失。缺口:没有测试断言不带 role 的面板不暴露任何角色或名称。 audit:LayoutPanel/accessibility
FR6 LayoutSlots.test.tsx 中的 ref 与 className 测试 Ref;调用方类名 ref 指向另一个元素或类名丢失会导致失败。缺口:没有测试覆盖 style、DOM、data 或事件属性,也未覆盖 xstyle 的合并顺序。 audit:LayoutPanel/api
FR7, AR2 paneSlide.interaction.browser.spec.ts:一个起始和一个结束面板进行折叠与展开,焦点位于面板内,同时使用 hook 自身的值与手工构建的值 起始与结束;切换、Enter 键及超过阈值的拖拽;配置对象形式;减弱动态效果 如果出现跳跃而非滑动、移动边缘旁出现间隙、在配置对象形式下未滑动、焦点留在已折叠面板中、已折叠面板可通过 Tab 聚焦或暴露给辅助技术,或新属性失败,则测试失败。 audit:LayoutPanel/behavior
AR3 useScrollRegionProps.test.tsx LayoutPanel 测试;scrollRegionName.a11y.chromium.spec.ts 中的 panel-scrolls;collapsedPanel.interaction.browser.spec.ts 滚动面板;调用方的 navigation 角色与标签;折叠到宽度为 0 的滚动面板 当面板内容溢出时缺少 group 角色或名称则失败,在 Chromium 的无障碍树中同样失败;调用方的角色或标签丢失也失败。宽度为 0 时仍保留 group 角色则失败。 audit:LayoutPanel/accessibility
PR1 源码审查 每种状态 缺口:如果 LayoutPanel 添加了监听器、计时器或测量逻辑,没有任何自动化检查会失败。 audit:LayoutPanel/behavior
RTL 关系 针对 Content width with start panel story 的 RTL 审计精选 D2 目标(apps/storybook/rtl-audit/targets.json) 起始面板紧邻内容;LTR 与 RTL 在两种方向下,如果起始面板不在内容的行内起始位置,则 D2 失败。 audit:LayoutPanel/i18n-rtl
FR8 resizableSlot.test.tsx 区域和 props 用例 该区域;其 props 忽略区域大小的面板,或折叠后仍使其可访问的情况,均判定为失败。 audit:LayoutPanel/api

决策日志

无记录。

未决问题

无。

内容边界

本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤、Layout 插槽规则、调整大小交互或容器内边距机制。它链接到相应的负责人。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx