Astryx Stepper 组件完全指南水平折叠机制、属性体系与最佳实践【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx本文基于internal/vibe-tests/stepper-collapse-naming-test/docs/arm-c-summary.md展开并结合packages/core/src/Stepper/目录下的真实源码Stepper.tsx、Step.tsx、StepperContext.ts、Stepper.test.tsx进行纵深验证。读完本文你将掌握 Astryx 设计系统中Stepper组件的完整 API、水平方向窄宽度自动折叠的核心机制、折叠摘要行的开关控制以及如何避免常见的无障碍反模式。Stepper 是什么多步骤流程的进度表达Stepper是 Astryx 核心包astryxdesign/core提供的多步骤流程组件用于表达购物车 → 地址 → 支付这类线性或非线性序列中的当前位置与完成进度。它渲染为语义化的有序列表ol/li而非nav地标——因为步骤表达的是穿越序列的进度而不是站点导航链接集合。每个步骤由编号指示器完成显示对勾、进行中显示圆环、标签文本、可选描述和一个 4px 的进度条分段构成。导入方式import {Step, Stepper} from astryxdesign/core/Stepper;核心行为是自我测量与自动折叠水平Stepper会测量自身宽度一旦每个步骤分到的宽度不足约 112px组件便折叠——所有步骤标签消失只留下分段式进度轨道轨道下方出现一行摘要承载当前步骤的名称并在设置了onStepClick时附带 上一页/下一页 控件。垂直Stepper永远不会折叠每个标签都独占一行不存在宽度不足的问题。水平折叠机制的源码级拆解折叠不是 CSS 容器查询实现的视觉隐藏而是改变渲染内容的真实状态切换。在 Stepper.tsx 中可以看到判定逻辑const isCompact isHorizontal rootWidth 0 stepCount 0 rootWidth / stepCount minimumStepWidth;逐步骤阈值minimumStepWidth默认值为DEFAULT_MIN_STEP_WIDTH 112单位像素。阈值作用于每个步骤而非整个组件因此折叠发生的宽度随步骤数量变化4 个步骤可坚持到 448px7 个步骤则需 784px见 Stepper.tsx 注释。宽度来源组件通过observeResize共享的 ResizeObserver 封装观察根ol的clientWidth。ref 回调在 commit 阶段同步回调一次确保折叠状态在浏览器绘制未折叠版本之前就已落地避免闪烁见 Stepper.tsx。步骤计数stepCount由各Step在挂载时通过registerStep注册得到useLayoutEffect而不是读取children——因此把步骤分组在 Fragment 或数组中不会改变计数结果折叠判定依旧准确。为什么用 JS 测量而非容器查询因为折叠改变的是渲染什么而不是长什么样。标签及其点击目标会整体离开 DOM。如果仅用 CSS 隐藏测试里的getByText会撞上残留文本折叠后的步骤还会残留无可见对象的焦点停留点详见 Stepper.tsx 注释。服务端渲染安全rootWidth与stepCount任一为零SSR 首帧、observer 触发前组件按完整形态渲染不存在水合不一致。Props 完整表格与语义详解prop类型默认值activeStepnumber—必填childrenReactNode—onStepClick(index: number) void—labelstringProgressorientationhorizontal \| verticalhorizontaldensitycompact \| balanced \| spaciousbalancedindicatorPositionseparated \| on-trackseparatedhasSummaryControlsbooleantruehasSummaryLabelbooleantrue核心行为型 PropsactiveStep当前步骤的从零开始的索引。Step据此推导自身状态step activeStep为进行中、step activeStep为已完成、否则为未开始并通过aria-currentstep标记活动步骤见 Stepper.test.tsx 的测试断言。onStepClick步骤点击回调传入被点击步骤的索引。设置后启用非线性导航可点击已完成步骤回跳不设置时所有步骤为纯展示。测试中可见其按钮可访问名为Go to step 1: Step 1, completed形式见 Stepper.test.tsx。label描述整个步骤序列的无障碍标签。未设置时使用翻译后的 Progress。测试用screen.getByRole(list, {name: Checkout progress})验证自定义值见 Stepper.test.tsx。orientation水平或垂直。垂直模式走独立渲染分支不挂载折叠逻辑与摘要行。折叠摘要行控制折叠后轨道下方会出现一行摘要。它由两个独立布尔开关控制来自本文档 arm-c-summary.md 的 API 设计hasSummaryControls控制折叠态是否显示 上一页/下一页 控件。控件仅在同时设置了onStepClick时才会出现——若步骤本身不可导航就没有可用的控件。hasSummaryLabel控制折叠态是否在轨道下方显示当前步骤名称。无论是否显示该名称始终保留在无障碍序列中屏幕阅读器始终能听到当前步骤名。两者在步骤足够宽、标签可见时均无任何效果——它们只作用于折叠形态。当前仓库的实际演进horizontalOptions.collapsedVariant需要说明的是本文档描述的hasSummaryControls/hasSummaryLabel来自组件命名振动测试的一个候选方案arm C。根据 PLAN.md 的记录该测试最终裁决并演进为horizontalOptions下的collapsedVariant枚举——当前packages/core实际发货的 API 为export interface StepperHorizontalOptions { /** 每个步骤折叠前的最小宽度像素默认 112 */ minimumStepWidth: number; /** 折叠后的呈现形式 */ collapsedVariant: | withLabelAndControls // 当前步骤名 导航控件 | withLabel // 仅当前步骤名 | hiddenLabel; // 裸进度轨道无摘要行 }两者语义一一对应见 Stepper.tsx 与 Stepper.doc.mjs 的 props 表。使用时等价写法为// 文档方案两个独立布尔 Stepper activeStep{step} onStepClick{setStep} hasSummaryControls{false} / // 当前发货方案枚举页面已有 Back/Continue 时 Stepper activeStep{step} onStepClick{setStep} horizontalOptions{{minimumStepWidth: 112, collapsedVariant: withLabel}} /实现层面Stepper.tsxconst showsControls collapsedVariant withLabelAndControls onStepClick ! null; const showsSummary isCompact collapsedVariant ! hiddenLabel;即控件出现需要变体要求控件且存在导航回调双重条件摘要行出现在isCompact且变体非hiddenLabel时。hiddenLabel直接省略整行连 frame 的空隙布局都不浪费。Step 子组件属性Step的公开属性见 Step.tsxprop类型说明stepnumber从零开始的索引用于相对父级activeStep推导进度labelstring步骤标签文本descriptionstring标签下方的可选描述statusaccent \| success \| warning \| error语义状态仅影响指示器颜色与字形永不改变进度条/轨道颜色isOptionalboolean在标签后追加 Optional可选提示isDisabledboolean禁用该步骤交互indicatorauto \| number \| none \| ReactNode指示器预设或自定义节点childrenReactNode内容槽适合垂直步骤中展示表单字段关键语义细节status是语义着色与进度无关。测试专门验证了statuserror的已完成步骤进度条类名不变永远使用--color-accent填充 /--color-border未填充只有指示器变色见 Stepper.test.tsx。进行中的步骤无论status为何始终保持当前步骤圆环指示器。实战示例默认形态零配置购物车三步流程非线性跳转Stepper activeStep{step} onStepClick{setStep} Step step{0} labelCart / Step step{1} labelAddress / Step step{2} labelPayment / /Stepper关闭折叠摘要行的一半页面自有页脚 Back/Continue 时Stepper activeStep{step} onStepClick{setStep} hasSummaryControls{false} Step step{0} labelCart / Step step{1} labelAddress / Step step{2} labelPayment / /Stepper携带状态与描述的完整形态Stepper activeStep{1} Step step{0} labelAccount descriptionEnter your email statussuccess / Step step{1} labelPayment statuserror / Step step{2} labelReview isOptional / /Stepper无障碍设计折叠时发生了什么折叠态是无障碍设计中处理得最精细的部分值得单独成节语义列表始终完整折叠时每个li通过VisuallyHidden恢复标签文本和状态文本aria-currentstep原样保留——有序序列对辅助技术来说从不缺失。摘要行aria-hidden轨道上方的ol已经承载了每个步骤的名称与状态摘要行被设置为aria-hiddentrue避免屏幕阅读器把当前步骤名播报两遍见 Stepper.tsx。折叠导航控件是真实控件与 TabList 的装饰性滚动箭头不同折叠态的 上一页/下一页 是有名字、可聚焦、真实生效的按钮IconButtonchevronLeft/chevronRight图标RTL 下通过rtlStyles.mirror镜像。它们通过adjacentEnabledStep查找当前步骤邻近的启用步骤自动跳过被禁用的步骤渲染时与激活时都会重新解析目标见 Stepper.tsx。可点击步骤的可访问名点击型步骤按钮的可访问名为Go to step {n}: {label}, {status}形式状态completed/error/warning会合成进名称而指示器字形本身aria-hidden见 Stepper.test.tsx。从源码结构看摘要行的名称部分由活动Step通过createPortal渲染进summarySlot且仅在isCompact isActive summarySlot ! null时挂载见 Step.tsx。这意味着只要 Stepper 不提供摘要槽位名称就不会渲染——这正是hasSummaryLabel{false}方案的完整实现且因整行aria-hidden两个开关都是纯视觉的不会缩短屏幕阅读器听到的内容。反模式不要用 CSS 隐藏折叠摘要行以下是本文档明确禁止的做法/* 不要这样做 */ [data-astryx-stepper-summary] { display: none; }原因CSS 隐藏只解决看不见不解决可访问。折叠态的 上一页/下一页 控件仍留在 Tab 顺序中但页面没有任何可见对象与之对应——键盘用户会 Tab 到几个幽灵按钮上。正确做法是用hasSummaryControls/hasSummaryLabel或当前 API 的collapsedVariant在渲染层决定是否输出该行让控件要么存在且可见要么彻底不存在。同类原则贯穿组件折叠时每个步骤的点击目标随标签一起离开 DOM窄到放不下标签的步骤剩下的就只有一条 4px 的条点了也白点导航职责整体移交轨道下方的具名控件见 Step.tsx 注释。版本与适用范围说明本文涉及的折叠行为、阈值与无障碍细节以当前仓库packages/core/src/Stepper/实际实现为准hasSummaryControls/hasSummaryLabel为本文档arm C 方案记载的 API当前发货版本以horizontalOptions.collapsedVariant为准二者语义等价。相关参考实现与验证文件Stepper.tsx、Step.tsx、StepperContext.ts、Stepper.test.tsx、Stepper.public.test.ts、Stepper.spec.md、Stepper.doc.mjs命名决策过程见 stepper-collapse-naming-test/PLAN.md。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考