CollapsibleGroup 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | CollapsibleGroup 协调 single 或 multiple 模式下的公共 Collapsible 子项,支持受控和非受控值,并可选地提供分隔线、密度和 chevron 位置的呈现默认值。 |
| 行为 | 带有 value 的直接子项读取组状态;打开一个项目会根据模式替换或扩展打开值集合。除非启用了分隔线样式,否则组不渲染任何包装器。 |
| 最终用户影响 | 人们可以展开一个或多个部分,而无需展开状态在兄弟行之间漂移;分隔组保持一致的整体视觉和方向处理。 |
| 构建者影响 | 构建者选择状态所有权和选择模式,为参与的项目提供稳定的值,并可以选择采用分隔行呈现。 |
| 兼容性/就绪程度 | 记录已发布行为;无公共变更。三个实现差距,列在“当前状态影响”下。 |
| 评审检查 | 拒绝丢失的 single/multiple 协调、在内部变更的受控状态、停止更新的非受控状态、泄漏到嵌套展开项中的呈现,以及在缺少分隔线时出现的包装器。 |
| 治理规则 | component:Collapsible/FR7–FR9,DEC-2; architecture:public-component-api/INV1,INV5–INV9; architecture:react-component-runtime/INV1,INV8–INV9; architecture:component-theming-surface/INV3–INV7. |
此表是一个评审投影;下面的正文为权威内容。
意图¶
协调一组展开项,使它们的打开状态遵循一个组所有者,同时每个 Collapsible 继续拥有自己的触发器、区域和展开语义。
兼容性与迁移¶
- 已发布默认值保留:是
- 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:不变
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 禁用的头部会脱离 Tab 顺序。 禁用的直接项的头部带有
aria-disabled,但会从 Tab 顺序中移除,因此键盘用户无法到达它以了解其不可用的原因。spec:AST-085FR1 保持禁用的控件可聚焦;该头部由component:Collapsible拥有。 - 相等的值可以重建协调上下文。 相等的新受控数组,或新的
onChange(如内联处理程序),会在每次父级渲染时重建协调上下文,因此被 memoized 的直接项会重新渲染。architecture:react-component-runtimeINV9 使未更改的负载不会广播新的标识(FR7)。 - 手风琴绑定将已采纳的行作为咨询运行。 该绑定将头部到头部的 Tab 步骤、single 模式兄弟折叠以及无方向键移动作为咨询行运行,因此那里的回归不会导致绑定通道失败。
spec:AST-020FR9 使一项已采纳的期望在本记录采纳它后成为必需(AR4)。
所有权边界¶
拥有
- 在 single 和 multiple 模式下的兄弟打开值协调;
- 受控和非受控组状态所有权以及传递给
onChange的形态; - 可选的分隔行包装器、密度默认值和组呈现上下文;以及
- 密度和 chevron 位置的直接项默认值。
不拥有 / 非目标
- 展开触发器、区域、chevron 图形、语义或嵌套呈现重置——由
component:Collapsible拥有; - 调用方内容、项标签,或调用方提供的值的含义和唯一性——由产品调用点拥有;或
- 超出已发布的 single 和 multiple 模式的任意选择模型。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 协调模式 | single、multiple |
替换打开集合或切换其中的一个成员。 | 每个组。 | single |
component:CollapsibleGroup |
稳定 | 被公共类型拒绝 |
| 状态所有权 | 非受控、受控 | 内部状态从 defaultValue 开始,或者 value 保持由调用方拥有。 |
每个组。 | 非受控 | component:CollapsibleGroup |
稳定 | 普通 React 语义 |
| 分隔呈现 | 不存在、存在 | 添加一个包装器,并要求直接项绘制行分隔线。 | 每个组。 | 不存在 | component:CollapsibleGroup |
稳定 | 被公共类型拒绝 |
| 行密度 | unpadded、compact、balanced、spacious |
为直接项提供块级内边距;divided 分组回退到 balanced。 | 直接分组项。 | unpadded;divided 时回退到 balanced | component:CollapsibleGroup |
稳定 | 被公开类型拒绝 |
| chevron 默认值 | absent、start、end |
提供由 component:Collapsible 拥有的位置默认值。 |
直接分组项。 | absent;项解析为 end |
component:Collapsible |
稳定 | 被公开类型拒绝 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 在 single 模式中,切换一个已关闭的直接项 MUST 用该项替换展开值集合;切换当前打开的项 MUST 清空该集合。 |
已发布的源码、消费者文档及针对性的交互测试 |
| FR2 | 在 multiple 模式中,切换一个直接项 MUST 仅添加或移除该值,同时保留其他值的状态。 |
已发布的源码、消费者文档及针对性的交互测试 |
| FR3 | 提供 value 时 MUST 保持状态由调用方所有,并通过 onChange 报告请求的更改;省略它时 MUST 在从 defaultValue 初始化后保持内部状态。 |
architecture:react-component-runtime/INV1,INV8;已交付的受控与非受控测试 |
| FR4 | 带 value 的直接 Collapsible MUST 使用分组协调;没有 value 的项 MUST 保留独立所有权。 |
已交付的 hook 行为及针对性的分组/独立测试 |
| FR5 | 当 hasDividers=false 时,分组 MUST 不添加 DOM 包装器。启用 dividers 时,它 MUST 渲染一个包装器,该包装器接收文档化的根 props 和 collapsible-group 目标。 |
architecture:public-component-api/INV5–INV8;architecture:component-theming-surface/INV3–INV7 |
| FR6 | 密度、divider 和 chevron 默认值 MUST 到达直接项,而不会通过直接项展开后的内容泄漏到嵌套的独立 disclosure 组件。 | component:Collapsible/FR7–FR8,DEC-2;针对性的嵌套测试 |
| FR7 | 当 divider、density 和 chevron 输入未变化时,呈现上下文标识 MUST 保持稳定;协调标识 MUST 在未变化的受控字符串、相同的受控数组引用或未变化的内部状态以及相同的 type 和 onChange 情况下,跨重新渲染保持稳定。实现差距:一个相等的新受控数组或新的 onChange 会重建它(当前状态影响)。 |
architecture:react-component-runtime/INV9;记忆化的源码与交互测试 |
允许的变体¶
- AV1 — 内部状态表示。 分组可以使用数组或其他私有结构来表示展开值,同时保持 FR1–FR4 和回调输出。
- AV2 — 包装器实现。 Divider 模式可以更改内部布局技术,同时保留一个绘制包装器、公开目标、根 props 可达性以及直接项结果。
- AV3 — 项组合。 调用方可以在不参与协调的内容旁边放置直接 Collapsible 项;只有带
value的 Collapsible 子项参与协调。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 单一(single)、非受控 | 至多一个有值项或无项保持展开,内部状态在每次切换后更新。 | 项标签与内容。 |
| 多重(multiple)、非受控 | 任意数量的有值项都可以保持展开。 | 项顺序与内容。 |
| 受控 | 渲染状态跟随 value;onChange 报告请求的下一状态。 |
父级更新时机。 |
| 分组(divided)、密度省略 | 一个包装器绘制组目标,直接项使用均衡(balanced)密度。 | 主题绘制。 |
| 朴素(plain)、密度省略 | 不出现包装器,直接项保持无内边距。 | 调用方周边布局。 |
| 分组位置与嵌套内容 | 直接项继承组位置;嵌套的折叠区重置该位置。 | 项级显式覆盖。 |
转换与优先级顺序¶
- ORD1 — 状态所有权。 受控
value(存在时)→ 否则内部值由defaultValue初始化 → 模式专属切换 → 按该模式文档化的输出形状调用回调。 - ORD2 — 密度。 显式组密度 → 启用分隔线时为
balanced→ 无组密度。 - ORD3 — Chevron 位置。 显式项位置 → 直接组位置 → Collapsible 默认
end,由component:Collapsible/ORD1拥有。
性能与资源¶
- PR1 — 渲染持有的协调。 组从 props、state 和 context 派生输出,不持有任何 Effect、监听器、观察器、定时器、请求、订阅或命令式浏览器资源。
- PR2 — 稳定广播。 记忆化的 context 值使 FR7 名称的身份对直接消费者保持稳定。
无障碍契约¶
- AR1 — 子元素语义保持首要地位。 组协调 MUST 保留每个 Collapsible 按钮的可访问名称、
aria-expanded、aria-controls、受控区域和键盘激活行为。 - AR2 — 呈现层不增加竞争性交互。 分隔线包装器 MUST NOT 添加 role、焦点目标、可访问名称或键盘行为。
- AR3 — 方向由 Collapsible 负责。 组 Chevron 默认值 MUST 保留
component:Collapsible/AR1–AR3,包括 LTR 和 RTL 下的向内引导提示。 - AR4 — 组采用 APG Accordion 模式所要求的组成部分(
spec:AST-020/FR15):每个直接项的表头是一个button,其可访问名称为该项的标题;aria-expanded反映其面板状态,aria-controls指名其揭示的面板;当无法切换时设置aria-disabled;每个启用的表头都位于页面 Tab 顺序中,Enter 或 Space 切换其面板,并在single模式下折叠已打开的兄弟项;禁用的表头带有aria-disabled且无法切换,只在 Tab 顺序上留下空缺(当前状态影响)。未采用:每个表头外的 heading 元素(本记录不要求任何 heading;调用方的文档结构提供标题)、面板上可选的region角色,以及表头之间的方向键或 Home/End 移动 —— 本组是一组独立的折叠区,而非单个复合控件。
设计关系¶
| Anatomy 或状态 | 设计要求 | 表征权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 组容器(Group container) | 可选的分隔线外观将兄弟折叠区在视觉上关联为一个集合。 | 已观察到的已发布表征 | 聚合容器 | FR5–FR6, AR2 |
| 直接项 | 密度与 Chevron 默认值在兄弟行之间保持一致。 | component:Collapsible/FR7–FR8 |
折叠行 | FR6, AR3 |
当前没有设计记录规定 CollapsibleGroup 的精确像素。本记录涵盖已发布的分组(divided)与朴素(plain)关系,而不决定新的视觉方向。
主题结构¶
{
"Container": {"target": "collapsible"},
"Trigger": {"target": "collapsible-trigger"},
"Chevron": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Content": {"target": "collapsible-content"},
"Group container": {"target": "collapsible-group"}
}
Group container 是 CollapsibleGroup 的条件聚合包装器。其余 anatomy 行仍归 component:Collapsible 所有;它们之所以重复出现在此子组件映射中,只是因为已发布的消费者 anatomy 与目标清单是共享的。Trigger、content、chevron、展开状态、禁用状态、密度内边距和逐项分隔线仍保留在 Collapsible 的契约中。
家族与系统关系¶
component:Collapsible拥有直接项的折叠(disclosure)语义、chevron 表征、项级主题结构以及嵌套呈现重置。architecture:public-component-api拥有导出可达性、文档化的根属性行为、受控 API 稳定性、样式组合以及条件 ref 可达性。architecture:react-component-runtime拥有渲染派生状态、稳定的 context 广播身份以及受控状态所有权边界。architecture:component-theming-surface拥有目标资格、目标放置、视觉轴反映以及委托项所有权。architecture:component-test-sufficiency拥有跨越状态协调、浏览器无障碍、方向和渲染呈现的合理证据集。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR4, ORD1 | CollapsibleGroup.test.tsx; useCollapsible.test.tsx |
单/多;受控/非受控;有值/无值 | 单模式下同级项保持展开、多模式下同级项关闭、受控状态在内部发生变更,或无值项丢失本地状态。 | audit:CollapsibleGroup/behavior |
| FR5–FR6, ORD2–ORD3 | CollapsibleGroup.test.tsx; Collapsible.test.tsx; themingTargets.test.ts |
普通/分隔;每种密度;组/项/嵌套位置 | 包装器/目标的可达性发生变化、默认样式不再命中直接项,或表现样式渗入嵌套内容。 | audit:CollapsibleGroup/theming |
| AR4 | Collapsible.test.tsx(禁用触发器:aria-disabled 且无切换行为;其“移出 Tab 顺序”的断言固定了该差距,待符合性确认);CollapsibleGroup.test.tsx(单/多模式协调、aria-expanded、Enter 键激活);Collapsible.a11y.test.tsx 和 Collapsible.a11y.chromium.spec.ts(披露语义、Space、单个项的 Tab 可达性);CollapsibleGroup.a11y.test.tsx 和 CollapsibleGroupAccordion.a11y.chromium.spec.ts(对分组标题按 Space;标题到标题的 Tab 步骤、单模式下同级项折叠,以及无方向键移动均作为建议性行运行) |
单/多;展开/收起;禁用项(展开或收起);Tab 顺序;Enter/Space 往返操作 | 标题失去其按钮角色、名称、aria-expanded 或 aria-controls;Enter 或 Space 停止切换;方向键在标题之间移动焦点 |
audit:CollapsibleGroup/accessibility |
| AR1–AR3 | DOM 与 Chromium 无障碍测试套件;组件自带的 Storybook 夹具;RTL 审计 | 展开/收起;单/多;前导/尾随;LTR/RTL | 披露语义与状态不一致、包装器变为可交互,或前导方向不再镜像。 | audit:CollapsibleGroup/accessibility |
| PR1–PR2, FR7 | 源代码审查及上下文和交互测试 | 未变更和已变更的状态/呈现输入 | 出现 Effect/资源、未变更的 payload 广播了新身份,或变更后的组行为无法传递给消费者。 | audit:CollapsibleGroup/code-health |
| 消费方文档 | CLI 组件投影、文档检查和 CollapsibleGroup.stories.tsx |
每个公开概念和代表性组合 | 已发布的 prop/默认值无法被发现,或所属浏览器路由失去了代表性状态覆盖。 | audit:CollapsibleGroup/docs |
从源代码中读取,尚无聚焦测试:
- AR4:标题之间不进行 Home/End 移动。
- FR7:在 divider、density 和 chevron 输入未变更时,呈现上下文身份保持稳定;协调身份在相同数组引用、未变更内部状态及相等新数组之间保持稳定;目前仅测试了受控字符串场景。
- PR1:该组不拥有任何 Effect 或浏览器资源。
决策日志¶
DEC-1 — 采用 Accordion 的必需部分;保持标题独立¶
参考: component:CollapsibleGroup/DEC-1
决策者: cixzhang,2026-10-13
该组的标题已经承担了 Accordion 标题的角色,因此它们承载其名称、状态、关系以及 Enter/Space 激活行为(AR4)。它们保留在页面的 Tab 键顺序中,不使用方向键或 Home/End 移动,因为该组协调的是独立展开区域,而不是作为一个复合控件运作;标题包装元素交由调用方的文档结构自行决定。
已拒绝:标题之间的方向键移动;为每个标题强制设置标题元素。
未决问题¶
无。本记录不会扩大已发布的协调模式,也不会决定新的呈现方式。
内容边界¶
本文件不会重复消费方 prop 表格、示例、当前审计分数、实施步骤,或 Collapsible 的展开与 chevron 规则。它会链接到这些内容的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx