跳转至

SideNavCollapseButton 组件契约

契约概览

领域 契约
公共契约 SideNavCollapseButton,接受 collapsible({isCollapsed, onCollapsedChange})、handleRef(已弃用)、label、size 和 children(替代图标)。
行为 一个仅图标的幽灵 Button,在 SideNav 或页面任意位置将 SideNav 轨道在展开与折叠之间切换。当折叠不可用或 AppShell 处于移动端布局时,它不渲染任何内容。
最终用户影响 用户可通过一个有名称的按钮折叠和展开侧边轨道,该按钮的 chevron 在任一书写方向下都指向正确方向。
构建者影响 无。
兼容性/就绪状态 记录已发布行为;无公共变更。一处实现差距(参见当前状态影响)。
评审检查 拒绝以下情况:调用方传入的 onClick 替换了切换行为、按钮在 AppShell 的移动端布局中渲染、或 chevron 在从右到左(RTL)方向下未镜像。
治理规则 architecture:public-component-api INV7;design:bidirectionality DR4;component:Button。

此表是评审投影;以下正文为权威内容。

意图

SideNavCollapseButton 是折叠和展开 SideNav 轨道的控件。它拥有其折叠状态的来源、名称和 chevron。消费者用法见 SideNavCollapseButton.doc.mjs。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:记录已发布行为;无公共变更
  • 受控/非受控行为:从 collapsible 读取状态,否则从已弃用的 handleRef 读取,否则从外层 SideNav 读取(FR1)
  • 迁移决策:无

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

当前状态影响

  • 触摸屏上减弱动态效果时立即变化。 在减弱动态效果下,chevron 的旋转在每次指针操作时立即变化;design:reduced-motion DR2 要求触摸屏变化在 200 ms 内进行交叉淡入淡出。

所有权边界

拥有

  • 状态来源、可见性、名称、切换行为与 chevron(FR1–FR5)。

不拥有 / 非目标

  • 轨道的折叠、调整大小和持久化行为——由 SideNav 拥有。
  • Button 的渲染、尺寸和焦点环——由 component:Button 拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可获得性 默认值 拥有者 稳定性 无效值行为
状态来源 collapsible、handleRef(已弃用)、外层 SideNav 折叠状态的读取和切换位置。 所有位置。 外层 SideNav component:SideNavCollapseButton 稳定;handleRef 已弃用 不适用。

行为与布局契约

ID 不变量 依据
FR1 当提供了 collapsible 时,状态来自 collapsible(始终可折叠;切换时以 isCollapsed 的相反值调用 onCollapsedChange),否则来自已弃用的 handleRef 所指向的 SideNav,再否则来自外层 SideNav。 当前源代码与测试
FR2 当状态来源不可折叠,或 AppShell 报告其移动端布局时,它不渲染任何内容。 当前源代码与测试
FR3 它渲染一个仅含图标的幽灵 Button,其名称由 label 指定;否则根据当前状态使用翻译后的 @astryx.sideNavCollapseButton.collapseSidebar 或 .expandSidebar,尺寸为 size,并转发 ref 和其他 props。 当前源码与测试
FR4 调用方的 onClick 先运行,然后执行切换;若调用方的 onClick 调用了 preventDefault(),则该次点击的切换会被取消。 当前源码与测试
FR5 默认图标是一个 V形箭头,展开时指向行内起始方向,折叠时转向;它在从右到左的布局中会镜像;其旋转动画仅在无减少动态偏好时播放;在减少动态下,对于精细指针它会立即改变,而在触摸屏上它 MUST 在 200 毫秒内交叉淡入淡出(design:reduced-motion DR2、DR3)。实现缺口:在触摸屏上它也会立即改变。children 可替换它。 当前源码

允许的变化

  • AV1 — 图标。 children 可替换该 V形箭头。

代表性状态

状态 必需不变项 允许的变化
位于 SideNav 内 切换该 SideNav。 —
带有 handleRef 时在外部 切换所引用的 SideNav。 —
受控 调用 onCollapsedChange;状态跟随该 prop。 —
移动端布局 不渲染。 —

转换与优先级顺序

  • ORD1 — 状态来源。 依照 FR1 的顺序。
  • ORD2 — 名称。 label,然后是依赖于状态的默认名称。

性能与资源

  • 无资源规则。

无障碍契约

  • AR1 — 已命名的控件。 该按钮始终具有描述其动作的名称(FR3)。

设计关系

解剖部位或状态 设计要求 表示权威 层级角色 组件契约
V形箭头 指向折叠方向。 当前源码 支持性 FR5

SideNavCollapseButton.doc.mjs 未声明自身的解剖结构,因此不记录解剖主题映射。

家族与系统关系

  • component:Button 渲染该控件。
  • design:bidirectionality DR4 管控 V形箭头的镜像。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
FR1, FR2 SideNav.test.tsx 中的 handleRef、外部按钮和折叠所有权测试 内部、handleRef、受控 过时或错误的状态来源会导致失败。 audit:SideNavCollapseButton/behavior
FR1, FR3, ORD2 SideNav.test.tsx 中的外部按钮和受控可折叠测试 自有 collapsible;label 覆盖;展开和折叠的默认名称 错误的状态来源、被忽略的 label 或过时的默认名称会导致失败。 audit:SideNavCollapseButton/accessibility
FR4 SideNav.test.tsx 中的消费者 onClick 测试 带有 handleRef 时在外部 替换了切换行为会导致失败。 audit:SideNavCollapseButton/behavior
FR3 SideNav.test.tsx 中的页脚图标行尺寸测试 内置按钮;导航外显式 size 使用 Button 默认尺寸或忽略显式尺寸会导致失败。 audit:SideNavCollapseButton/behavior
RTL 关系 针对 SideNav / Collapsible sidebar 的自动 D1 RTL 审计,由 apps/storybook/rtl-audit/targets.json 中的仅路由条目路由 折叠按钮的 chevron;LTR 和 RTL 未镜像的 chevron 会导致 D1 失败。 audit:SideNavCollapseButton/i18n-rtl

从源码中读取到以下内容,尚无针对性测试:

  • FR2:当状态源不可折叠或 AppShell 处于移动端布局时,不渲染任何内容。
  • FR3:ghost 变体以及转发的 ref。
  • FR4:调用方的 onClick 在切换之前运行,并且其 preventDefault() 会取消切换。
  • FR5。

决策日志

未记录任何组件局部的决策。

待解决问题

无。

内容边界

本文件不重复展示使用方的 prop 表格或示例,而是链接到其所有者。

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