跳转至

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-085 FR1 保持禁用的控件可聚焦;该头部由 component:Collapsible 拥有。
  • 相等的值可以重建协调上下文。 相等的新受控数组,或新的 onChange(如内联处理程序),会在每次父级渲染时重建协调上下文,因此被 memoized 的直接项会重新渲染。architecture:react-component-runtime INV9 使未更改的负载不会广播新的标识(FR7)。
  • 手风琴绑定将已采纳的行作为咨询运行。 该绑定将头部到头部的 Tab 步骤、single 模式兄弟折叠以及无方向键移动作为咨询行运行,因此那里的回归不会导致绑定通道失败。spec:AST-020 FR9 使一项已采纳的期望在本记录采纳它后成为必需(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