Collapsible 组件契约¶
意图¶
Collapsible 通过一个披露触发器来显示和隐藏一个内容区域。它的箭头在两种有意的布局模式中传达相同的展开状态:一种是尾部状态指示器,另一种是在标签列之前对齐的前导披露箭头。
公共轴是箭头的逻辑位置。调用方不能提供任意的提示内容,也不能替换 Collapsible 的披露渲染。
兼容性与迁移¶
- 已发布默认行为保留:是。省略新位置将保留当前的尾部箭头和当前的无 prop 渲染。
- 兼容性类别:新增可选公共轴,且具有稳定默认值。
- 受控/非受控行为:不变。
- 迁移决策:
component:Collapsible/DEC-1。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 披露触发器、其
aria-expanded/aria-controls关系,以及表示展开状态的箭头; start | end逻辑箭头位置轴;- 折叠和展开状态下特定于位置的箭头方向;
- 箭头位置的组默认值、项目覆盖和嵌套项目隔离;以及
- 为保持位置契约所需的触发器标签布局。
不拥有 / 非目标
- 调用方提供的箭头、提示、图标或渲染函数逃生舱;
- TreeList、Table 或其他组件的披露指示符;
- 通用图标解析或图标定制;
- 同级展开值协调、组状态和分割组包装器 —— 由
component:CollapsibleGroup拥有; - 共享的响应式或方向性 API;或
- 新的内容揭示动画行为。本决策之外的现有行为保持不变,直到其自身的当前权威方更改它。
公共概念¶
| 概念 | 值或状态 | 含义 | 可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 箭头位置 | start, end |
拥有 Collapsible 披露箭头的触发器标签的逻辑侧 | Collapsible 和 CollapsibleGroup | end |
component:Collapsible |
稳定 | 由公共类型拒绝 |
| 披露状态 | 折叠、展开 | 受控区域是隐藏还是显示 | 每个 Collapsible | 现有状态所有者 | component:Collapsible 或组状态所有者 |
稳定 | 现有的受控/非受控行为 |
| 组位置默认值 | 无, start, end |
提供给直接组项目的公共位置 | CollapsibleGroup | 无,因此项目默认解析为 end |
component:Collapsible |
稳定 | 由公共类型拒绝 |
| 动画布局 | 无,一个 useAnimatedLayout 句柄 |
打开和关闭是否会让 Collapsible 之后的内容滑动,直至该句柄的容器(spec:AST-105) |
每个 Collapsible | 无:之后的内容立即就位 | spec:AST-105 |
稳定 | 由公共类型拒绝 |
公共 prop 名为 chevronPosition。导出的值类型为 CollapsibleChevronPosition。placement、side 和渲染术语不是该轴的并行公共名称。
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | Collapsible MUST 暴露 chevronPosition?: 'start' \| 'end';省略时解析为 end。 |
所有者 API 决策;保留已发布默认值 |
| FR2 | end MUST 在逻辑顺序中于触发器标签之后渲染 Collapsible 的箭头。折叠的 end 指向下方;展开的 end 指向上方。 |
已发布的尾部行为加上已批准的位置契约 |
| FR3 | 在逻辑顺序上,start MUST 将 Collapsible 的箭头渲染在触发器标签之前。折叠状态的 start 朝内指向标签/内容,因此其内联方向在 RTL 下镜像反转;展开状态的 start 朝下指向。 |
已批准的前置披露行为 |
| FR4 | 位置会同时改变箭头的字形/方向以及 DOM 顺序。复用垂直向下的箭头并将其侧向旋转 MUST NOT 使折叠状态的 start 背离其内容。 |
方向与呈现决策 |
| FR5 | 对于两种位置,Collapsible 都拥有并渲染箭头。位置轴 MUST NOT 接受 none、任意 React 内容、提示回调、渲染器或任何其他替代性逃生通道。 |
受约束的公开轴决策 |
| FR6 | 触发器标签内容 MUST 在任一位置保留组合标签所需的可用行宽。将箭头移动到 start MUST NOT 将标签困在另一侧边缘,或阻止组合标签内容使用剩余行宽。 |
已批准的布局理由与现有增长行为 |
| FR7 | CollapsibleGroup 可以为其直接 Collapsible 项提供一个 chevronPosition 默认值。直接项的显式位置 MUST 覆盖组默认值。 |
已批准的组一致性行为 |
| FR8 | 嵌套在另一个项的已展开内容中的 Collapsible MUST 开启一个新的呈现作用域,并使用自身的显式位置或组件默认值。外层组的位置 MUST NOT 泄漏到嵌套的披露区域中。 | 已批准的嵌套隔离行为 |
| FR9 | 箭头位置 MUST NOT 改变展开语义。同一触发器仍然是按钮,保留 aria-expanded,通过 aria-controls 标识受控区域,并遵循现有的状态所有者。 |
现有可访问性和行为契约 |
| FR10 | Collapsible MUST 接受 animatedLayout?: AnimatedLayout。提供 handle 时,打开和关闭通过它上报内容的尺寸变化,使 Collapsible 之后的内容在 handle 的容器内滑动,且被展开的内容与箭头以相同的动画移动(spec:AST-105 FR1–FR4;spec:AST-108 FR4a)。未提供时,打开和关闭行为不变。该 prop MUST NOT 改变展开语义。 |
spec:AST-105 FR1, FR2 |
允许的变体¶
- AV1 — 图标图形实现。 只要 FR2–FR4 在视觉和方向上仍然成立,内部 Icon 的确切名称和变换实现可以更改。
- AV2 — 间距机制。 Margin、gap 或等效的内部布局可以将前导箭头与标签分隔开,同时保持 FR6 成立。
- AV3 — 组一致性。 项可以显式覆盖其组的 position。混合位置通过优先级得到支持,但应保持为刻意为之的例外,而非偶然出现的逐行变化模式。
- AV4 — 现有的非箭头行为。 打开状态所有权、禁用行为、分隔线/密度呈现、内容布局和展开动画仍受其现有权威规范约束,且不因本决策而改变。
- AV5 — 内部区域元素。 内容区域始终将其子元素包裹在一个内部元素中,因此边缘处的展开或隐藏会使其在该区域的 clip 下滑动(
spec:AST-105FR9)。该元素是内部的:它不是样式目标,也不是承诺提供的结构。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 省略位置,收起 | 箭头跟随标签并指向下方 | 内部图标实现 |
| 省略位置,展开 | 箭头跟随标签并指向上方 | 内部旋转实现 |
start,收起,LTR |
箭头位于标签之前,并指向 inline-end 方向(朝向内容) | 内部图形 |
start,收起,RTL |
箭头位于逻辑起始端、标签之前,并指向 inline-end 方向(朝向内容) | 内部图形/镜像机制 |
start,展开 |
箭头位于标签之前并指向下方 | 内部过渡机制 |
组为 start,子项省略 |
直接子项解析为 start |
呈现上下文实现 |
组为 start,子项为 end |
直接子项解析为 end |
呈现上下文实现 |
组为 start,嵌套子项省略 |
嵌套子项解析为组件默认值 end |
上下文重置实现 |
转换与优先级顺序¶
- ORD1 — 位置优先级。 子项
chevronPosition→ 直接外层的 CollapsibleGroupchevronPosition→ 组件默认值end。 - ORD2 — 方向解析。 先解析位置和展开状态;再将文档方向应用于
start的向内 inline-end 方向。end仍为垂直的向下/向上指示器,不会被镜像为水平提示。
无障碍契约¶
- AR1 — 展开/收起语义保持首要地位。 触发器必须(MUST)独立于箭头图形地暴露其展开状态以及受控区域关系。
- AR2 — 位置是视觉顺序,而非阅读重复。 移动装饰性箭头不得(MUST NOT)复制无障碍名称,也不得增加第二个焦点目标。
- AR3 — 方向保持可理解。 收起状态下的前导提示在 LTR 和 RTL 中都必须(MUST)指向内容;在 RTL 下不得(MUST NOT)保留 LTR 的物理方向。
- AR4 — 焦点离开正在关闭的内容。 当 Collapsible 关闭时,如果焦点位于其内容内部,则无论它以何种方式关闭(由所有者设置的
isOpen,或组的值),焦点都会移动到其触发器,包括在内容播放退出效果期间(FR10)。其他任何位置的焦点都不会被移动(WCAG 2.2 SC 2.4.3)。
设计关系¶
这两种位置表达了既定的展开/收起模式:
end是尾部状态指示器:收起时向下,展开时向上;start是前导的树形/文件浏览器展开箭头:收起时向内,展开时向下。
本契约选择这些关系,但不暴露任意图标或提示的选择。主题可以样式化所属 Collapsible 的目标,而不改变语义方向或位置状态。
主题结构¶
{
"Container": {"target": "collapsible"},
"Trigger": {"target": "collapsible-trigger"},
"Chevron": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Content": {"target": "collapsible-content"},
"Group container": {"target": "collapsible-group"}
}
容器拥有分栏行装饰,而触发器与内容各自拥有独立的绘制表面和展开状态选择器表面。箭头保留 Icon 的目标;Collapsible 拥有其语义位置和方向。CollapsibleGroup 是本契约的聚合子组件,因此其条件包装器目标在此映射到 Group container 结构。
家族与系统关系¶
architecture:component-theming-surface拥有结构限定、目标放置、视觉轴与状态反映,以及委托的 Icon 所有权。- 公共
useCollapsiblehook 保留其现有的状态行为和使用者文档。此组件拥有渲染后的触发器、箭头,以及聚合的组件/组协议。 architecture:public-component-api拥有获准的 position prop 与导出类型的可达性和兼容性。architecture:react-component-runtime拥有上下文身份/生命周期;本记录拥有呈现值和嵌套作用域结果。spec:AST-002/DEC-1允许此轴,因为除此之外完全相同的展开/收起布局要求前导与尾部模式由调用者控制。它不允许自定义提示渲染。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR5 | Collapsible 的 prop/类型、DOM 顺序、字形/方向以及无额外值测试 | omitted/end/start;collapsed/expanded;LTR/RTL | 默认值发生改变、start 跟随标签、折叠状态的前导提示指向外侧,或接受了不受支持的提示值 |
audit:Collapsible/public-api |
| FR6 | 组合 trigger 的布局与几何测试 | 纯文本;带尾部内容的组合标签;start/end | 标签被收缩包裹或孤立,或组合内容无法使用剩余行空间 | audit:Collapsible/layout |
| FR7–FR8, ORD1 | 组继承、项覆盖和嵌套重置测试 | 组 start/end;项覆盖;嵌套省略 | 组值被忽略、项无法覆盖,或位置泄漏到嵌套内容中 | audit:Collapsible/behavior |
| FR9, AR1–AR3, ORD2 | 通过 DISCLOSURE_PATTERN 实现的 disclosure 语义,以及组件自有的 chevron 与真实 RTL 渲染 |
collapsed/expanded;controlled/uncontrolled;enabled/disabled;start/end;LTR/RTL | 位置改变状态行为、trigger 失去与受控内容的关系、内容可见性与状态不一致、无障碍输出重复,或前导方向无法镜像 | audit:Collapsible/accessibility |
| FR10 | animatedLayoutAdopters.test.tsx(有无 handle 两种情况;owner 设置的 isOpen 与组的受控值平滑过渡;StrictMode 下有一次测量,拒绝变更时无测量;退出期间保持 inert 直到结束)以及 animatedLayoutAdopters.interaction.browser.spec.ts(通过 ScrollableArea ref 打开和关闭 Core/Animated layout story) |
无 handle;有 handle;点击、owner 设置和组驱动的变更;打开和关闭 | 带 handle 时内容发生跳跃、owner 设置的变更立即落定、关闭内容在退出前消失或在退出期间仍可访问,或没有 handle 时发生任何变化 | audit:Collapsible/behavior |
| AR4 | Collapsible.test.tsx 关闭焦点测试套件;animatedLayoutAdopters.test.tsx 在退出期间焦点位于内部时关闭;CollapsibleCloseFocus.a11y.chromium.spec.ts |
焦点在内容内部、owner 设置的关闭、有无 handle;焦点在外部;trigger 将其关闭;打开 | 焦点停留在隐藏或 inert 内容内部、落在页面 body 上,或在焦点本不在内容内部时被移动,均视为失败。 | audit:Collapsible/accessibility |
| Theming anatomy | 聚焦的 target-reflection 断言以及 themingTargets.test.ts |
standalone/grouped;open/closed;enabled/disabled;start/end;divided/density | 驱动样式的轴或状态从其所属 target 上消失、target 失去其 anatomy 所有者,或 chevron 不再委托给 Icon | audit:Collapsible/theming |
决策日志¶
DEC-1 — Chevron 位置是公共轴¶
参考: component:Collapsible/DEC-1
决策者: cixzhang,2026-09-07
调用方可以选择逻辑上的 chevron 位置 start 或 end。Collapsible 拥有该提示符号,并据此派生特定位置的字形与方向。start 用于前置展开模式(如树形/文件浏览器行);end 保留已发布的尾部指示符。
已拒绝:chevronPlacement、none、hasChevron、由调用方提供的提示内容,以及渲染回调。这些方案会暴露渲染机制,或允许组件的展开提示消失,而非表达经批准的调用方拥有的布局区分。
DEC-2 — 组默认值不会通过内容泄漏¶
参考: component:Collapsible/DEC-2
决策者: cixzhang,2026-09-07
CollapsibleGroup 可以为其直接子项提供位置,子项也可以覆盖该位置。嵌套在子项主体内部的 Collapsible 会开启一个新的呈现作用域,因此外层列表的视觉惯例不会静默改变一个独立的展开提示。
待解决问题¶
无。
内容边界¶
本文件承载 Collapsible 的持久化语义概念、chevron 位置行为、优先级和证据。消费方属性表/示例保留在 Collapsible.doc.mjs 和 CollapsibleGroup.doc.mjs 中。确切的 Icon 名称、变换、StyleX 声明、上下文字段、实现计划、审计结果和 pull-request 结论不属于此处。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx