跳转至

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-105 FR9)。该元素是内部的:它不是样式目标,也不是承诺提供的结构。

代表性状态

状态 必需不变量 允许的变化
省略位置,收起 箭头跟随标签并指向下方 内部图标实现
省略位置,展开 箭头跟随标签并指向上方 内部旋转实现
start,收起,LTR 箭头位于标签之前,并指向 inline-end 方向(朝向内容) 内部图形
start,收起,RTL 箭头位于逻辑起始端、标签之前,并指向 inline-end 方向(朝向内容) 内部图形/镜像机制
start,展开 箭头位于标签之前并指向下方 内部过渡机制
组为 start,子项省略 直接子项解析为 start 呈现上下文实现
组为 start,子项为 end 直接子项解析为 end 呈现上下文实现
组为 start,嵌套子项省略 嵌套子项解析为组件默认值 end 上下文重置实现

转换与优先级顺序

  • ORD1 — 位置优先级。 子项 chevronPosition → 直接外层的 CollapsibleGroup chevronPosition → 组件默认值 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 所有权。
  • 公共 useCollapsible hook 保留其现有的状态行为和使用者文档。此组件拥有渲染后的触发器、箭头,以及聚合的组件/组协议。
  • 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