Astryx Stepper 折叠机制全解112px 阈值、Summary 行与 collapsed 导航配置【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 的Stepper是一个为多步骤工作流表单向导、结账流程、onboarding设计的步骤进度组件。本篇围绕其最独特的行为——窄屏自动折叠collapse——展开水平 Stepper 会在每步可用宽度不足时丢弃标签、退化为纯分段进度条并在轨道下方渲染一条承载当前步骤名 上一步/下一步控件的 Summary 行。读完本文你将掌握折叠的触发阈值与测量原理、折叠后 Summary 行两个半区的独立开关当前步骤名与导航控件、Step的完整状态模型以及为什么用 CSS 隐藏折叠行是被明令禁止的反模式。组件定位与导入Stepper属于 Astryx core 包中的 Navigation 类别官方组件文档将其归类为多步工作流的编号步骤序列Stepper.doc.mjs推荐用于表单向导、onboarding 流程与结账流程。它渲染为有序列表ol而非nav地标——因为 Stepper 表达的是穿过一个序列的进度不是一组站点导航链接这样不会污染页面的 landmark 地图见 Stepper.tsx 顶部注释。import {Step, Stepper} from astryxdesign/core/Stepper;使用上Stepper负责管理步骤状态activeStep、注册/注销、上下文发布Step负责渲染单个步骤的指示器、标签、描述与轨道分段。组件本身不画任何东西——每条进度条、每个指示器、每段标签都来自其Step子元素。折叠行为水平 Stepper 的响应式退化水平Stepper渲染一个编号序列每个步骤下方带一个标签。关键特性是它自己测量自己的宽度一旦每个步骤可用的宽度不足约 112pxStepper 就进入折叠状态——标签从 DOM 中消失不只是视觉隐藏只剩一段分段进度轨道轨道下方出现一行Summary 行承载当前步骤的名称并且在设置了onStepClick时承载上一步/下一步控件。从源码看折叠判定位于 Stepper.tsxconst isCompact isHorizontal rootWidth 0 stepCount 0 rootWidth / stepCount minimumStepWidth;即水平方向 已测得宽度 已注册步骤数 0 每步均摊宽度 阈值时折叠。默认阈值DEFAULT_MIN_STEP_WIDTH 112Stepper.tsx。阈值按每步而非整个组件应用所以折叠发生的位置随步骤数变化4 步在 448px 以下折叠7 步则需要 784px。一次测量、同步回调observeResize在订阅时立即回调一次使得折叠在浏览器绘制未折叠版本之前就完成避免闪烁。值得注意的实现选择为什么用 JS 测量宽度而不是 CSS Container Query源码注释给出明确理由——因为折叠改变的是渲染什么而非长得怎样标签和它们的点击目标会完全离开 DOM。如果只是用查询把标签藏起来文本仍留在树中消费者的getByText会撞上幽灵文本折叠后的步骤也仍然持有焦点停留点却无可视内容。垂直 Stepper 则完全不同每个标签独占一行永远不会缺少宽度因此垂直 Stepper 永不折叠——从源码看非水平方向直接提前返回、渲染与全宽时完全相同的 DOMStepper.tsx。Props 全表与折叠相关配置prop类型默认值activeStepnumber—childrenReactNode—onStepClick(index: number) void—labelstringProgressorientationhorizontal \| verticalhorizontaldensitycompact \| balanced \| spaciousbalancedindicatorPositionseparated \| on-trackseparatedhasCollapsedControlsbooleantruehasCollapsedLabelbooleantrueactiveStep是当前步骤的零基索引。onStepClick让步骤可点击实现非线性导航例如允许用户跳回已完成的步骤。折叠行的两个半区可以独立关闭hasCollapsedControls控制折叠状态下是否在轨道下方渲染上一步/下一步控件。控件只在设置了onStepClick时才出现——没有导航回调时控件无处可点。hasCollapsedLabel控制折叠状态下是否在轨道下方显示当前步骤的名称。无论取值如何步骤名都保留在无障碍序列accessible sequence中屏幕阅读器始终能听到完整步骤列表。两者在 Stepper 宽度足够展示标签时均不生效——它们是纯折叠态配置。这两个开关的典型动机是去冗余页面往往已经有自己的 Back/Continue 按钮和自己的分步标题Stepper 不应在手机上再复制一份。折叠行的落地形态horizontalOptions.collapsedVariant需要说明的是当前仓库源码中这一能力以horizontalOptions承载而非两个独立布尔Stepper.tsxexport type StepperCollapsedVariant withLabelAndControls | withLabel | hiddenLabel; export interface StepperHorizontalOptions { minimumStepWidth: number; // 默认 112每个步骤的最小宽度 collapsedVariant: StepperCollapsedVariant; // 默认 withLabelAndControls }两种表达方式的语义完全等价对应关系如下布尔表达arm-a 文档枚举表达当前源码折叠行内容hasCollapsedControlstruehasCollapsedLabeltrue默认withLabelAndControls默认步骤名 上一步/下一步hasCollapsedLabeltruehasCollapsedControlsfalsewithLabel仅步骤名两者均为falsehiddenLabel裸轨道无折叠行源码中showsControls与showsSummary的推导与此对应Stepper.tsxconst showsControls collapsedVariant withLabelAndControls onStepClick ! null; const showsSummary isCompact collapsedVariant ! hiddenLabel;这段命名之争并非偶然internal/vibe-tests/stepper-collapse-naming-test/目录就是一个完整的 vibe testPLAN.md它用 4 个提示词构成 2×2 矩阵页面是否已有自己的导航、是否已有自己的标题让 22 个独立 agent 在四种命名臂hasCollapsed*/has*/hasSummary*/collapsedSummary枚举下完成任务最终结论是两个独立布尔 Collapsed限定词优于枚举和Summary词汇——召回测试 5/5 的 agent 都自发产出两个独立布尔无人选择枚举因为枚举强迫你重述不想改的那一半。这也是本文沿用hasCollapsedControls/hasCollapsedLabel命名的出处。Step状态模型与可选配置Step接收step零基索引、label以及可选的description、status与isOptionalstatusaccent | success | warning | error只用于语义着色需要更丰富的指示器时应传入自定义 icon。isOptional标记可选步骤。description标签下方的辅助说明文字。从 Step.tsx 看步骤的可点击性与折叠直接相关isClickable !isDisabled onStepClick ! null !isCompact——折叠后每个步骤节点变为纯展示presentational导航职责移交折叠行的控件控件会通过注册的getIsDisabled回调跳过被禁用的步骤Stepper.tsx。示例开箱即用与关闭一半默认配置无任何折叠定制Stepper activeStep{step} onStepClick{setStep} Step step{0} labelCart / Step step{1} labelAddress / Step step{2} labelPayment / /Stepper关闭折叠行的一半——页面已有自己的底部导航按钮时隐藏折叠态的 Previous/NextStepper activeStep{step} onStepClick{setStep} hasCollapsedControls{false} Step step{0} labelCart / Step step{1} labelAddress / Step step{2} labelPayment / /Stepper等价于当前源码 APIStepper activeStep{step} onStepClick{setStep} horizontalOptions{{collapsedVariant: withLabel}} Step step{0} labelCart / Step step{1} labelAddress / Step step{2} labelPayment / /Steppervibe test 的提示词矩阵给出了三种真实场景prompts.json页面自带 Back/Continue如结账流程关控件、留步骤名hasCollapsedControls{false}/withLabel每步面板自带大标题如导入向导关步骤名、留控件hasCollapsedLabel{false}两者页面都有全关只要裸轨道hasCollapsedControls{false} hasCollapsedLabel{false}/hiddenLabel页面什么都没有负向对照什么都不设默认值即正确。无障碍设计折叠行是视觉上的装饰折叠行为的无障碍处理非常讲究是本文档中最值得学习的设计决策之一Summary 行步骤名部分通过 portal 渲染进一个aria-hiddentrue的容器Stepper.tsx因为上方的ol已经承载了每个步骤的名称与状态再朗读一次就是重复播报。折叠后每个Step恢复自身的隐藏文本标签与状态文本VisuallyHidden见 Step.tsx列表始终保持完整的无障碍有序序列aria-currentstep完整保留。因此hasCollapsedControls/hasCollapsedLabel都是纯视觉开关——无论怎么关屏幕阅读器听到的内容一字不少。这正是 PLAN.md 决策记录里Step 无需任何改动的原因Step已经按summarySlot ! null门控其 summary portalStep.tsx不提供插槽就实现了隐藏标签的整个逻辑。与 TabList 的滚动箭头装饰性、aria-hidden、跳过键盘不同折叠态的 Previous/Next 是真实控件、有真实名字、可以聚焦——因为它们是折叠 Stepper 唯一的通行方式。控件文案来自 i18nastryx.stepper.previousStep/nextStep并在 RTL 环境下镜像箭头。列表的label属性默认取翻译后的ProgressuseTranslator可用labelprop 覆盖。反模式不要用 CSS 隐藏折叠行/* 不要这样做 */ [data-astryx-stepper-summary] { display: none; }这条规则的理由非常具体Summary 行里的控件是真实可聚焦的见上节用 CSS 隐藏整行会留下仍在 tab 顺序中、却没有任何可见物对应的控件——键盘用户会聚焦到空气上。正确做法永远是通过组件 APIhasCollapsedControls/hasCollapsedLabel或等价的collapsedVariant关闭对应半区让组件自己决定渲染什么。事实上vibe test 的召回分析发现这个 CSS 选择器名summary曾让测试 agent 误以为summary是组件的内部实现词汇——这正是Collapsed限定词胜出的理由之一它描述的是行为而非内部结构。折叠态的测试困境与组件文档线索折叠行为无法被强制预览——它完全由运行时宽度驱动这也是 Stepper.test.tsx 里测试必须手工重定义Element.prototype.clientWidth的原因。这被 vibe test 记录为后续改进项Storybook 预览缺口。组件文档 Stepper.doc.mjs 也给出了三条官方最佳实践步骤标签保持简短Payment 而非 Enter your payment information长描述用垂直方向水平方向由组件自己处理窄容器折叠页面自带 Back/Continue 时选withLabel页面连标题和导航都有时选hiddenLabel。需要深入时推荐阅读 Stepper.tsx折叠判定与 Summary 行渲染、Step.tsx状态模型与 summary portal、Stepper.test.tsx含clientWidth重定义以及 Stepper.public.test.ts公开上下文边界再结合 Stepper.stories.tsx 观察实际渲染形态。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考