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-017FR53 下)。在滚动时, 没有调用方role的面板会获得role="group"和aria-label(DOM;AR3,[fix],位于spec:AST-017FR53 下)。 - 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 两个分隔线所有者可能绘制同一边界(FR4)。 带有
hasDivider的面板紧邻绘制同一条线的 ResizeHandle 时, 会绘制两次边界;没有任何机制阻止这一点,因此当 ResizeHandle 拥有该线条时,调用方需保持hasDivider={false}(family:layout-regionsFR5)。
所有权边界¶
拥有
- 面板根元素,其承载
layout-panel目标,由component:Layout映射。 - 面板宽度、内边距、滚动、分隔线,以及调用方提供的 role 和 label。
不拥有 / 非目标
- 插槽放置和 Layout 边缘内边距 — 由
component:Layout拥有。 - 调整大小交互和调整大小手柄 — 由 useResizable 和
ResizeHandle 拥有(
family:layout-regionsFR10)。 - 面板内容及其含义 — 由调用方拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 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-regionsFR8)。 - AR2 — 焦点离开折叠中的面板。 当面板区域在焦点位于面板内部时折叠,在任意 resize 控制器下(包括配置对象形式,FR7),焦点都会移动到面板面向内容边缘上的相邻 ResizeHandle——即重新打开面板的控件;折叠后的面板随即变为 inert 并设置
aria-hidden,直到它重新打开(spec:AST-105FR9)。打开操作不会移动焦点。从 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-105FR9 负责 FR7 所播放的边缘揭示,以及 AR2 所应用的焦点规则;component:ResizableFR8 负责其播放时机。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