跳转至

ChatComposerDrawer 组件契约

契约速览

领域 契约
公共契约 新增一个可选的 collapsedSummary?: ReactNode 插槽,名称取自规范结构部件 Collapsed summary,用于由调用方组合的视觉内容。
行为 count 仍用于启用披露。省略 collapsedSummary 时,保持中性 Badge 计数加已解析标签;提供该插槽时,会替换这一完整视觉摘要,但不会改变折叠行为或命名。
最终用户影响 默认情况下,用户仍保有既有的 Badge 层级。需要更低调或以不同方式组合折叠行的产品,可以提供一个本地化的视觉摘要,同时不削弱披露语义。
构建者影响 现有调用点无需更改。选择该插槽的构建者负责其视觉内容和本地化,而 label 仍用于标识受控内容,以提供组件自身的无障碍名称。
兼容性/就绪度 新增且保持默认不变。本记录为当前权威依据;该插槽及其对应的实现、消费者文档、测试和渲染证据尚未发布。
审查检查 应拒绝:纯文本默认实现、第二个摘要 API、会改变命名或折叠状态的自定义内容、视觉摘要内可达的交互式后代,或对无插槽与无计数路径的任何回归。
治理规则 component:ChatComposerDrawer/FR1–FR10, AR1–AR4, DEC-1–DEC-2;architecture:public-component-api/INV3–INV4, INV9, INV13;spec:AST-002/DEC-1, DEC-2。

此表是审查投影;下文正文具有权威性。

意图

ChatComposerDrawer 在 ChatComposer 输入框上方组合补充内容。当存在 count 时,构建者可以让用户折叠该内容,同时保留一个紧凑摘要供使用。

两个在其他方面完全相同的抽屉,在折叠状态下可能需要不同的视觉层级。产品构建者知道是既有的 count Badge 还是更低调、针对产品定制的摘要更适合该上下文,而 ChatComposerDrawer 无法从 count、内容、布局、语言区域或折叠状态中推导出这一区别。因此,该组件暴露一个视觉组合接缝,同时保留其现有默认行为,并拥有全部披露行为。

兼容性与迁移

  • 已发布默认行为得到保留:是。省略 collapsedSummary 时,保持中性 count Badge,其后跟随已解析标签。
  • 兼容性类别:新增式可选组合插槽,无默认行为变更。
  • 受控/非受控行为:不变。
  • 迁移决策:无。现有调用点无需任何编辑。

消费者迁移说明应放入消费者文档和发布说明。

所有权边界

拥有

  • 抽屉表面、可选披露状态、披露关联,以及折叠后代的可用性。
  • 受控与非受控折叠请求。
  • 保留 Badge 的默认摘要,以及一个由调用方组合的折叠摘要的纯展示边界。
  • 披露控件的本地化无障碍名称,不受视觉摘要内容影响。

不拥有 / 非目标

  • 调用方提供的抽屉子内容或自定义摘要内容的含义、样式或本地化。
  • 自定义摘要内部的交互行为;摘要仅为视觉内容,绝不创建另一个焦点或激活目标。
  • ChatComposer 输入、提交、状态和操作行为。
  • 呈现枚举、Badge 开关、渲染回调、摘要专用主题目标,或第二个无障碍名称属性。

公共概念

概念 封闭值或状态 含义 按状态的可用性 默认值 拥有者 稳定性 无效值行为
抽屉内容 任意 React 节点 组合在聊天输入框上方的补充内容。 始终 无 component:ChatComposerDrawer 稳定 缺少内容会被必需类型拒绝。
折叠支持 不可用、已展开、已折叠 count 存在(包括为 0)时,启用一个披露控件并提供其摘要计数。 省略 count 时不可用 不可用 component:ChatComposerDrawer 稳定 没有 count 时,折叠输入不会产生可见效果。
折叠控制 非受控、受控 由内部状态或 isCollapsed 决定当前披露状态。 当折叠支持可用时 非受控 component:ChatComposerDrawer 稳定 受控状态优先于初始默认值。
collapsed summary 默认、调用方组合 折叠披露所展示的视觉内容。 当折叠支持可用时 中性 Badge 加上 label 调用方选择;组件接缝 已接受,未发布 省略时使用默认值;没有 count 时不暴露任何摘要。
collapse request 下一状态 激活请求相反的有效折叠状态。 当折叠支持可用时 无 component:ChatComposerDrawer 稳定 没有披露控件时不发出任何请求。

collapsedSummary 是规范 Collapsed summary 解剖部件的 camelCase 公共 API 投影。它是完整的自定义视觉摘要,而不是默认内容之前或之后的附加内容。该组件不会解析、克隆、装饰或向该节点提供数据。构建者已经拥有他们作为 count 和 label 传入的值;当自定义摘要构成句子或格式化数字时,其调用点拥有完整的本地化消息。

行为与布局契约

ID 不变量 依据
FR1 当存在 count 时,包括其为 0 时,组件 MUST 公开一个带有 aria-expanded 和可解析的 aria-controls 关系的命名披露控件。 已发布 API 和实现;WAI-ARIA 披露语义
FR2 指针激活、Enter 和 Space MUST 恰好请求一次相反的有效折叠状态。 已发布实现和公共回调契约
FR3 在受控模式下,isCollapsed MUST 保持权威;在非受控模式下,激活 MUST 在下次渲染前更新内部状态。 已发布实现和消费者文档
FR4 折叠抽屉的内容可以保持挂载以进行网格过渡,但其后代 MUST 不参与键盘和辅助技术导航。 WAI-ARIA 披露语义;WCAG 2.4.3 和 2.4.7
FR5 通过共享的焦点指示器机制,披露控件上的键盘焦点 MUST 保持清晰可感知。 architecture:interaction-modality/INV1–INV4
FR6 省略 count 时,MUST 直接渲染抽屉内容,MUST NOT 创建披露控件,且 MUST NOT 暴露 collapsedSummary。在此状态下,现有的折叠输入继续不产生可见效果。 已发布的 no-count 行为和兼容性
FR7 根节点 MUST 继续转发其 ref、BaseProps 属性和样式接缝,而不将它们移动到内部子节点。 已发布公共表面和 architecture:public-component-api/INV5–INV6, INV8–INV9
FR8 collapsedSummary MUST 保持为规范 Collapsed summary 解剖部件的 camelCase 公共名称。省略时,折叠披露 MUST 保留现有的中性 Badge,其中包含 count,后接解析后的 label;提供时,该节点 MUST 恰好一次替换该完整解剖部件。 经批准的解剖对齐调用方组合边界和已发布默认值
FR9 自定义摘要 MUST 仅影响视觉内容。它 MUST NOT 改变折叠是否可用、有效折叠状态、切换控件激活、回调值、受控区域或组件拥有的无障碍名称。 受限插槽契约与 spec:AST-002/DEC-2
FR10 摘要子树 MUST 保持仅呈现:disclosure 是唯一的焦点和激活目标;摘要后代 MUST 不出现在 Tab 顺序和无障碍树中;自定义内容 MUST NOT 添加另一个操作。 WAI-ARIA disclosure 语义与组件拥有的无障碍边界

允许的变体

  • AV1 — Drawer 子内容组合。 构建者选择 drawer 内容及其自身语义。
  • AV2 — 自定义摘要组合。 构建者可以组合任何符合仅呈现边界的内容,包括本地化文本或现有的 Astryx 显示组件。
  • AV3 — 摘要生命周期。 组件可以在视觉展开期间保持默认或自定义摘要的挂载,以保留动画。调用方 MUST NOT 依赖挂载或卸载时机。
  • AV4 — 自定义摘要样式。 调用方组合的内容保留其所使用组件的样式和主题接缝。ChatComposerDrawer 不会添加摘要特定的目标。

代表性状态

状态 必需的不变量 允许的变体
count 省略 内容可见;不暴露任何 disclosure 或摘要。 子内容与根样式。
默认摘要,已折叠 一个 disclosure 显示中性计数的 Badge 以及解析后的 label。 计数值与本地化标签。
自定义摘要,已折叠 一个 disclosure 显示调用方节点,而非两个默认摘要部分。 仅呈现的自定义内容与样式。
自定义摘要,已展开 disclosure 保留其状态和名称;自定义摘要可保持挂载,但在视觉上和语义上隐藏。 内部交叉淡化与挂载时机。
受控已展开或已折叠 渲染状态遵循 isCollapsed;激活时报告请求的下一个状态。 父级时机及其是否接受请求。

转换与优先级顺序

  • ORD1 — 折叠可用性。 count 存在 → disclosure 启用;count 省略 → 无 disclosure 或已折叠摘要。
  • ORD2 — 有效状态。 定义了 isCollapsed 时 → 使用该值;否则使用由 defaultIsCollapsed 初始化的内部状态。
  • ORD3 — 视觉摘要。 调用方提供的 collapsedSummary → 否则是 count 的中性 Badge 后跟解析后的 label。
  • ORD4 — 无障碍名称。 从 prop 或区域设置目录解析 label → 对有效状态使用目录中的展开或折叠操作消息。视觉摘要内容永远不会进入或覆盖此管道。

性能与资源

  • PR1 — 仅本地状态。 摘要接缝 MUST NOT 需要 Effect、观察器、监听器、计时器或外部资源。

无障碍契约

  • AR1 — Disclosure 关系。 该切换控件暴露一个本地化名称、展开状态,以及一个可解析的受控内容 ID。
  • AR2 — 命名保持组件所有。 label 在展开/折叠目录消息中标识受控的 drawer 内容。默认或自定义视觉摘要文本 MUST NOT 替换、重复或拼接到该无障碍名称中。
  • AR3 — 隐藏内容不可用。 视觉上折叠的 drawer 后代在展开之前不可用。
  • AR4 — 自定义摘要保持仅呈现。 自定义内容不能在 disclosure 内添加第二个焦点停留点、激活目标、角色或公告。

设计关系

目前没有任何设计规范约束这种组件局部的表示。

结构或状态 设计要求 表示权威 层级角色 组件契约
根表面 现有已发布表面不因该决定而改变。 已发布行为 支持 FR7
展开/收起开关 一个可操作且具名控件拥有折叠交互。 组件所有 辅助 FR1–FR5, AR1
折叠摘要 Badge 层级保持默认;调用方可选择一个视觉组合插槽。 组件默认或调用方选择的组合 辅助 FR8–FR10, AR2–AR4
内容区域 折叠后的后代内容保持对键盘和辅助技术不可用。 组件所有 辅助 FR4, FR6, AR3

现有的 chat-composer-drawer 目标仍保留在已绘制的根元素上。保留 Badge 的默认实现将计数绘制委托给 Badge。调用方组合的摘要内容保留其所提供组件的主题所有权。此决定不会新增 ChatComposerDrawer 摘要目标,也不会将任意插槽内部内容纳入 ChatComposerDrawer 的主题 API。

家族与系统关系

  • architecture:public-component-api 负责新增插槽的可达性、命名语法和兼容性;本组件拥有其局部含义和默认值。
  • architecture:interaction-modality 负责共享的焦点可见性机制;本组件拥有该展开控件并作为其语义焦点所有者。
  • architecture:component-theming-surface 负责目标和结构映射规则;自定义摘要不会创建新目标,也不会转移调用方内容的所有权。
  • architecture:knowledge-contracts 将当前权限限制为本记录中的明确声明。
  • spec:AST-002/DEC-1 允许该插槽存在,因为其他方面完全相同的抽屉可能需要调用方拥有的、组件无法推导的视觉层级。DEC-2 要求该接缝保留可靠且无障碍安全的结果。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1–FR3, FR6, ORD1–2 聚焦 ChatComposerDrawer 状态和键盘测试 无计数;零计数;受控;不受控;指针;Enter;Space 存在性/真值变化改变折叠可用性、状态权威发生变化,或回调报告错误的下一状态。 audit:ChatComposerDrawer/behavior
FR8–FR9, ORD3 聚焦默认/自定义摘要测试和消费者文档投影检查 默认;自定义节点;展开;折叠;无计数 默认 Badge 消失、默认与自定义内容同时渲染、自定义内容改变行为,或无计数情况将其暴露。 audit:ChatComposerDrawer/api
FR4, FR10, AR2–AR4 聚焦惰性状态和自定义后代测试,以及 exact-head 无障碍 CI 默认文本;自定义文本;可聚焦的自定义后代;折叠/展开 隐藏的抽屉内容或自定义摘要变为可聚焦、可被播报,或成为第二个动作;视觉文本替换目录名称。 audit:ChatComposerDrawer/accessibility
FR5, AR1 KeyboardFocus Storybook 测试脚本和 exact-head 视觉/无障碍门禁 代表性浅色和深色主题下的键盘焦点 焦点缺少共享的可见指示器,或披露关系/名称被破坏。 audit:ChatComposerDrawer/accessibility
FR7 聚焦 DOM/类型测试和包检查 ref、BaseProps、xstyle、className、style 根所有权或样式接缝移动或消失。 audit:ChatComposerDrawer/api
AV4 和主题边界 默认和自定义摘要的源代码/运行时主题检查 默认 Badge;调用方组合的 Astryx 内容 出现新的摘要目标、Badge 失去其目标,或调用方拥有的内容被重新定位为 ChatComposerDrawer 的结构。 audit:ChatComposerDrawer/theming

决策日志

DEC-1 — 一个视觉插槽保留 Badge 默认

引用: component:ChatComposerDrawer/DEC-1 决策人: cixzhang,2026-09-21

ChatComposerDrawer 允许一个可选的 collapsedSummary 节点作为完整视觉摘要。产品构建者自行决定某个折叠行是否需要既有的 Badge 层级,还是更简洁的局部组合;组件无法推导这种视觉层级。省略该插槽会保留现有的中性 Badge 加标签,因此现有构建者不会获得新的选项或迁移要求。

已拒绝的方案:用 {count} {label} 句子替换默认,为 Badge 添加布尔值或有限的呈现枚举,为调用方已拥有的值添加渲染回调,或暴露并行的摘要接缝。这些形态要么破坏已发布的默认值,要么将呈现机制编码化,要么招致区域设置不安全的字符串拼接,要么增加超出调用方自有区分所需的 API。

DEC-2 — 视觉组合不拥有披露语义

参考: component:ChatComposerDrawer/DEC-2 决策者: cixzhang,2026-09-21

自定义摘要仅用于展示。现有的 label 和语言环境目录继续为展开/折叠操作命名;count 继续启用披露;组件将摘要后代排除在焦点、激活和辅助技术导航之外。该接缝无法替代这些义务。

已拒绝:从任意摘要内容派生可访问名称,或让自定义摘要在披露内部引入另一个操作。这两种做法都会使正确的语义依赖于组件无法验证的调用方标记。

未决问题

此契约部分没有未决问题。

内容边界

本文件拥有 ChatComposerDrawer 的折叠摘要组合边界、保留 Badge 的默认行为、折叠门控与状态行为、可访问命名、兼容性以及所需证据。它不会重复完整的消费者 prop 参考、实现步骤、当前审计分数或无关组件缺口。当前权威性仅适用于上述明确需求,并不认证 ChatComposerDrawer 的每一种行为。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx