radix-vue StepperItem 组件指南状态管理、Props 与源码实现解析【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vueStepperItem 是 radix-vue即 Reka UIStepper 组件体系中的核心步骤单元用于渲染一个可感知自身active/completed/inactive状态、支持禁用与线性约束的步骤节点。本文以官方组件元数据文档 docs/content/meta/StepperItem.md 为主体结合仓库内 StepperItem 源码、StepperRoot 源码 与 Stepper 测试用例 逐项拆解其 Props、插槽与底层实现帮助你在多步骤表单、结算向导等场景中正确使用并深度定制该组件。StepperItem 在 Stepper 中的角色Stepper 是一组用于标识多步骤流程进度的步骤集合。官方组件文档 docs/content/docs/components/stepper.md 将其描述为A set of steps that are used to indicate progress through a multi-step process.完整的 Stepper 由以下部件组合而成详见 组件导出入口StepperRoot步骤容器承载modelValue、方向、线性模式等全局状态StepperItem单个步骤节点对应文档 API 参考中的Item小节StepperTrigger步骤的触发按钮StepperIndicator步骤指示器StepperTitle/StepperDescription可被读屏软件播报的标题与描述StepperSeparator步骤间的分隔线。其中StepperItem是步骤的骨架它负责计算当前步骤处于何种状态并通过 Context 把状态、禁用信息、无障碍 ID 提供给内部的StepperTrigger、StepperIndicator、StepperSeparator等子部件。官方推荐的骨架结构如下摘录自 stepper.mdscript setup import { StepperDescription, StepperIndicator, StepperItem, StepperRoot, StepperTitle, StepperTrigger } from reka-ui /script template StepperRoot StepperItem StepperTrigger / StepperIndicator / StepperTitle / StepperDescription / StepperSeparator / /StepperItem /StepperRoot /templateProps 详解StepperItem共暴露 5 个 Props其中仅step为必填。以下表格完整继承自元数据文档随后结合源码逐一展开。NameDescriptionTypeRequiredDefaultasThe element or component this component should render as. Can be overwritten by asChild.AsTag \| ComponentNodivasChildChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.booleanNo-completedShows whether the step is completed.booleanNofalsedisabledWhen true, prevents the user from interacting with the step.booleanNofalsestepA unique value that associates the stepper item with an indexnumberYes-step唯一索引值step是必填属性用于把步骤项与步进器中的某个索引关联起来。从源码接口定义看StepperItem.vueexport interface StepperItemProps extends PrimitiveProps { /** A unique value that associates the stepper item with an index */ step: number /** When true, prevents the user from interacting with the step. */ disabled?: boolean /** Shows whether the step is completed. */ completed?: boolean }step的取值约定是从 1 开始的连续正整数StepperRoot源码中isFirstStep modelValue 1、isLastStep modelValue totalSteps而goToStep会拒绝step 1或超出总步数的调用见 StepperRoot.vue。测试用例中也遵循这一约定例如steps数组使用step: 1到step: 5见 Stepper.test.ts。completed手动标记完成completed默认false表示该步骤是否已完成。需要特别注意的是它的优先级最高在 StepperItem.vue 的状态计算中一旦completed为真该步骤无条件进入completed状态const itemState computed(() { if (completed.value) return completed if (rootContext.modelValue.value step.value) return active if (rootContext.modelValue.value! step.value) return completed return inactive })也就是说即使step尚未被激活只要显式传入completedUI 也会把它渲染成已完成样式。这适用于默认已完成的历史步骤等场景。disabled禁止交互disabled默认false为true时阻止用户与步骤交互。它的作用体现在三个层面渲染层面渲染时会带上disabled属性与data-disabled数据属性见下文可聚焦层面isFocusable计算属性直接以disabled为前置条件禁用步骤tabindex为-1且不可被箭头键聚焦StepperItem.vue交互层面StepperTrigger的点击与键盘处理都会先检查itemContext.disabled.value并提前返回StepperTrigger.vue。as与asChild组合能力as默认渲染为div可改为任意 HTML 标签或 Vue 组件asChild则把默认渲染元素替换为传入的子元素并将属性与行为合并到子元素上具体机制可参考仓库中的 组合Composition指南。这是 radix-vue 全系列组件的通用能力StepperItemProps也通过extends PrimitiveProps继承而来StepperItem.vue。state插槽动态定制步骤外观StepperItem的默认插槽接收一个名为state的插槽属性类型为active | completed | inactive。元数据文档中的插槽表格如下NameDescriptionTypestateThe current state of the stepper itemactive \| completed \| inactive对应的类型定义StepperItem.vue为export type StepperState completed | active | inactive借助state你可以让指示器、图标、文字在不同状态间切换无需重复条件判断例如StepperItem v-foritem in steps :keyitem.step :stepitem.step StepperTrigger StepperIndicator / StepperTitle{{ item.title }}/StepperTitle StepperDescription{{ item.description }}/StepperDescription /StepperTrigger StepperSeparator v-ifitem.step ! steps.length / /StepperItem仓库 Story 示例_Stepper.vue正是以v-for驱动 5 个步骤Address → Shipping → Trade-in → Payment → Checkout的标准写法story/_Stepper.vue。渲染输出与数据属性StepperItem的模板StepperItem.vue基于Primitive渲染并自动派生出一组数据属性便于你编写状态样式Primitive :refforwardRef :asas :as-childasChild :aria-currentitemState active ? true : undefined :data-stateitemState :disableddisabled || !isFocusable ? : undefined :data-disableddisabled || !isFocusable ? : undefined :data-orientationrootContext.orientation.value slot :stateitemState / /Primitive官方组件文档为 Item 定义了以下数据属性见 stepper.md 的 Item 小节AttributeValues[data-state]active/inactive/completed[data-disabled]存在即表示禁用[data-orientation]vertical/horizontal此外当步骤处于active状态时还会输出aria-currenttrue该行为被测试用例直接验证expect(getByTestId(stepper-item-2)).toHaveAttribute(aria-current, true)Stepper.test.ts。需要注意disabled属性与data-disabled不仅受disabledprop 影响在线性模式下不可聚焦的步骤同样会被标记条件为disabled || !isFocusable。这与StepperTrigger上的渲染逻辑保持一致StepperTrigger.vue也意味着isNextDisabled等根级判断能通过读取 DOM 属性正常工作StepperRoot.vue。与 Root 的协作状态计算与线性约束StepperItem通过injectStepperRootContext()从StepperRoot读取modelValue、orientation、linear等全局状态StepperItem.vue其状态推导规则可归纳为completedprop 为真 →completedmodelValue step→activemodelValue step→completed已越过该步其余 →inactive。同时它还会计算isFocusable规则为StepperItem.vuedisabled时永远不可聚焦线性模式linear: trueRoot 默认值下只有step modelValue或step modelValue 1才可聚焦即只能访问当前步及下一步非线性模式下所有未禁用步骤都可聚焦。测试用例对此有完整覆盖线性模式下点击第三步无法聚焦linear: true而非线性模式下可以跳到第四步linear: false见 Stepper.test.ts。Root 的linear默认值为true、orientation默认horizontal、defaultValue默认1StepperRoot.vue。StepperItem还会通过provideStepperItemContext向子部件提供titleId、descriptionId、state、step、disabled、isFocusable等上下文StepperItem.vueStepperTrigger与StepperSeparator正是依赖这些上下文来渲染data-state、aria-labelledby、aria-describedby并决定交互行为StepperSeparator.vue。实战受控模式与额外控制按钮StepperItem本身通常配合 Root 使用。若需要上一步 / 下一步按钮等额外控制可以像官方示例stepper.md 的 With controls 小节那样用useTemplateRef拿到 Root 实例并调用其暴露的方法script setup langts const stepper useTemplateRef(stepper) /script template StepperRoot refstepper :default-value1 StepperItem StepperIndicator / StepperTitle / StepperDescription / /StepperItem StepperItem StepperIndicator / StepperTitle / StepperDescription / /StepperItem /StepperRoot div classflex gap-2 justify-between mt-4 button :disabled!stepper?.hasPrev() clickstepper?.prevStep() Prev /button button :disabled!stepper?.hasNext() clickstepper?.nextStep() Next /button /div /templateRoot 暴露的方法与状态完整列表StepperRoot.vue包括goToStep(step)、nextStep()、prevStep()、modelValue、totalSteps、isNextDisabled、isPrevDisabled、isFirstStep、isLastStep、hasNext()、hasPrev()。此外 Root 还会渲染一个视觉上隐藏绝对定位、透明度 0、pointer-events: none的aria-livepolite状态区实时播报 Step X of YStepperRoot.vue。可访问性与键盘交互StepperItem及其配套的StepperTrigger共同保证完整键盘可达性。官方文档stepper.md 的 Keyboard Interactions 小节定义的按键行为如下KeysDescriptionTab焦点移入步进器时聚焦第一个步骤ArrowDown根据orientation移动焦点到下一步ArrowRight根据orientation移动焦点到下一步ArrowUp根据orientation移动焦点到上一步ArrowLeft根据orientation移动焦点到上一步Enter/Space选中聚焦的步骤其底层实现位于StepperTrigger方向键通过useArrowNavigation结合orientation与dir在已注册的步骤元素间移动焦点Enter/Space则调用changeModelValue激活步骤StepperTrigger.vue步骤元素在onMounted/onUnmounted时动态注册进totalStepperItems集合以保持总步数同步StepperTrigger.vue。测试覆盖了水平/垂直方向键导航与 Enter/Space 选中并验证了步骤卸载重挂载后总数不漂移Stepper.test.ts同时该组件通过了 axe 无障碍测试toHaveNoViolations见 Stepper.test.ts。总结StepperItem通过 5 个精炼的 Props 和 1 个state插槽把步骤状态感知这一核心能力封装为声明式 APIstep定义索引、completed显式标记完成、disabled控制交互、as/asChild提供组合弹性state插槽则让 UI 定制完全跟随内部状态推导。理解其状态优先级completedactive 已越过 inactive与线性约束下的可聚焦规则能帮助你写出既符合无障碍规范又具备复杂交互逻辑的多步骤界面。更多组件级细节可继续查阅 StepperItem 元数据文档 与 Stepper 完整组件文档。【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 radix-vue StepperItem 组件指南：状态管理、Props 与源码实现解析
radix-vue StepperItem 组件指南状态管理、Props 与源码实现解析【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vueStepperItem 是 radix-vue即 Reka UIStepper 组件体系中的核心步骤单元用于渲染一个可感知自身active/completed/inactive状态、支持禁用与线性约束的步骤节点。本文以官方组件元数据文档 docs/content/meta/StepperItem.md 为主体结合仓库内 StepperItem 源码、StepperRoot 源码 与 Stepper 测试用例 逐项拆解其 Props、插槽与底层实现帮助你在多步骤表单、结算向导等场景中正确使用并深度定制该组件。StepperItem 在 Stepper 中的角色Stepper 是一组用于标识多步骤流程进度的步骤集合。官方组件文档 docs/content/docs/components/stepper.md 将其描述为A set of steps that are used to indicate progress through a multi-step process.完整的 Stepper 由以下部件组合而成详见 组件导出入口StepperRoot步骤容器承载modelValue、方向、线性模式等全局状态StepperItem单个步骤节点对应文档 API 参考中的Item小节StepperTrigger步骤的触发按钮StepperIndicator步骤指示器StepperTitle/StepperDescription可被读屏软件播报的标题与描述StepperSeparator步骤间的分隔线。其中StepperItem是步骤的骨架它负责计算当前步骤处于何种状态并通过 Context 把状态、禁用信息、无障碍 ID 提供给内部的StepperTrigger、StepperIndicator、StepperSeparator等子部件。官方推荐的骨架结构如下摘录自 stepper.mdscript setup import { StepperDescription, StepperIndicator, StepperItem, StepperRoot, StepperTitle, StepperTrigger } from reka-ui /script template StepperRoot StepperItem StepperTrigger / StepperIndicator / StepperTitle / StepperDescription / StepperSeparator / /StepperItem /StepperRoot /templateProps 详解StepperItem共暴露 5 个 Props其中仅step为必填。以下表格完整继承自元数据文档随后结合源码逐一展开。NameDescriptionTypeRequiredDefaultasThe element or component this component should render as. Can be overwritten by asChild.AsTag \| ComponentNodivasChildChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.booleanNo-completedShows whether the step is completed.booleanNofalsedisabledWhen true, prevents the user from interacting with the step.booleanNofalsestepA unique value that associates the stepper item with an indexnumberYes-step唯一索引值step是必填属性用于把步骤项与步进器中的某个索引关联起来。从源码接口定义看StepperItem.vueexport interface StepperItemProps extends PrimitiveProps { /** A unique value that associates the stepper item with an index */ step: number /** When true, prevents the user from interacting with the step. */ disabled?: boolean /** Shows whether the step is completed. */ completed?: boolean }step的取值约定是从 1 开始的连续正整数StepperRoot源码中isFirstStep modelValue 1、isLastStep modelValue totalSteps而goToStep会拒绝step 1或超出总步数的调用见 StepperRoot.vue。测试用例中也遵循这一约定例如steps数组使用step: 1到step: 5见 Stepper.test.ts。completed手动标记完成completed默认false表示该步骤是否已完成。需要特别注意的是它的优先级最高在 StepperItem.vue 的状态计算中一旦completed为真该步骤无条件进入completed状态const itemState computed(() { if (completed.value) return completed if (rootContext.modelValue.value step.value) return active if (rootContext.modelValue.value! step.value) return completed return inactive })也就是说即使step尚未被激活只要显式传入completedUI 也会把它渲染成已完成样式。这适用于默认已完成的历史步骤等场景。disabled禁止交互disabled默认false为true时阻止用户与步骤交互。它的作用体现在三个层面渲染层面渲染时会带上disabled属性与data-disabled数据属性见下文可聚焦层面isFocusable计算属性直接以disabled为前置条件禁用步骤tabindex为-1且不可被箭头键聚焦StepperItem.vue交互层面StepperTrigger的点击与键盘处理都会先检查itemContext.disabled.value并提前返回StepperTrigger.vue。as与asChild组合能力as默认渲染为div可改为任意 HTML 标签或 Vue 组件asChild则把默认渲染元素替换为传入的子元素并将属性与行为合并到子元素上具体机制可参考仓库中的 组合Composition指南。这是 radix-vue 全系列组件的通用能力StepperItemProps也通过extends PrimitiveProps继承而来StepperItem.vue。state插槽动态定制步骤外观StepperItem的默认插槽接收一个名为state的插槽属性类型为active | completed | inactive。元数据文档中的插槽表格如下NameDescriptionTypestateThe current state of the stepper itemactive \| completed \| inactive对应的类型定义StepperItem.vue为export type StepperState completed | active | inactive借助state你可以让指示器、图标、文字在不同状态间切换无需重复条件判断例如StepperItem v-foritem in steps :keyitem.step :stepitem.step StepperTrigger StepperIndicator / StepperTitle{{ item.title }}/StepperTitle StepperDescription{{ item.description }}/StepperDescription /StepperTrigger StepperSeparator v-ifitem.step ! steps.length / /StepperItem仓库 Story 示例_Stepper.vue正是以v-for驱动 5 个步骤Address → Shipping → Trade-in → Payment → Checkout的标准写法story/_Stepper.vue。渲染输出与数据属性StepperItem的模板StepperItem.vue基于Primitive渲染并自动派生出一组数据属性便于你编写状态样式Primitive :refforwardRef :asas :as-childasChild :aria-currentitemState active ? true : undefined :data-stateitemState :disableddisabled || !isFocusable ? : undefined :data-disableddisabled || !isFocusable ? : undefined :data-orientationrootContext.orientation.value slot :stateitemState / /Primitive官方组件文档为 Item 定义了以下数据属性见 stepper.md 的 Item 小节AttributeValues[data-state]active/inactive/completed[data-disabled]存在即表示禁用[data-orientation]vertical/horizontal此外当步骤处于active状态时还会输出aria-currenttrue该行为被测试用例直接验证expect(getByTestId(stepper-item-2)).toHaveAttribute(aria-current, true)Stepper.test.ts。需要注意disabled属性与data-disabled不仅受disabledprop 影响在线性模式下不可聚焦的步骤同样会被标记条件为disabled || !isFocusable。这与StepperTrigger上的渲染逻辑保持一致StepperTrigger.vue也意味着isNextDisabled等根级判断能通过读取 DOM 属性正常工作StepperRoot.vue。与 Root 的协作状态计算与线性约束StepperItem通过injectStepperRootContext()从StepperRoot读取modelValue、orientation、linear等全局状态StepperItem.vue其状态推导规则可归纳为completedprop 为真 →completedmodelValue step→activemodelValue step→completed已越过该步其余 →inactive。同时它还会计算isFocusable规则为StepperItem.vuedisabled时永远不可聚焦线性模式linear: trueRoot 默认值下只有step modelValue或step modelValue 1才可聚焦即只能访问当前步及下一步非线性模式下所有未禁用步骤都可聚焦。测试用例对此有完整覆盖线性模式下点击第三步无法聚焦linear: true而非线性模式下可以跳到第四步linear: false见 Stepper.test.ts。Root 的linear默认值为true、orientation默认horizontal、defaultValue默认1StepperRoot.vue。StepperItem还会通过provideStepperItemContext向子部件提供titleId、descriptionId、state、step、disabled、isFocusable等上下文StepperItem.vueStepperTrigger与StepperSeparator正是依赖这些上下文来渲染data-state、aria-labelledby、aria-describedby并决定交互行为StepperSeparator.vue。实战受控模式与额外控制按钮StepperItem本身通常配合 Root 使用。若需要上一步 / 下一步按钮等额外控制可以像官方示例stepper.md 的 With controls 小节那样用useTemplateRef拿到 Root 实例并调用其暴露的方法script setup langts const stepper useTemplateRef(stepper) /script template StepperRoot refstepper :default-value1 StepperItem StepperIndicator / StepperTitle / StepperDescription / /StepperItem StepperItem StepperIndicator / StepperTitle / StepperDescription / /StepperItem /StepperRoot div classflex gap-2 justify-between mt-4 button :disabled!stepper?.hasPrev() clickstepper?.prevStep() Prev /button button :disabled!stepper?.hasNext() clickstepper?.nextStep() Next /button /div /templateRoot 暴露的方法与状态完整列表StepperRoot.vue包括goToStep(step)、nextStep()、prevStep()、modelValue、totalSteps、isNextDisabled、isPrevDisabled、isFirstStep、isLastStep、hasNext()、hasPrev()。此外 Root 还会渲染一个视觉上隐藏绝对定位、透明度 0、pointer-events: none的aria-livepolite状态区实时播报 Step X of YStepperRoot.vue。可访问性与键盘交互StepperItem及其配套的StepperTrigger共同保证完整键盘可达性。官方文档stepper.md 的 Keyboard Interactions 小节定义的按键行为如下KeysDescriptionTab焦点移入步进器时聚焦第一个步骤ArrowDown根据orientation移动焦点到下一步ArrowRight根据orientation移动焦点到下一步ArrowUp根据orientation移动焦点到上一步ArrowLeft根据orientation移动焦点到上一步Enter/Space选中聚焦的步骤其底层实现位于StepperTrigger方向键通过useArrowNavigation结合orientation与dir在已注册的步骤元素间移动焦点Enter/Space则调用changeModelValue激活步骤StepperTrigger.vue步骤元素在onMounted/onUnmounted时动态注册进totalStepperItems集合以保持总步数同步StepperTrigger.vue。测试覆盖了水平/垂直方向键导航与 Enter/Space 选中并验证了步骤卸载重挂载后总数不漂移Stepper.test.ts同时该组件通过了 axe 无障碍测试toHaveNoViolations见 Stepper.test.ts。总结StepperItem通过 5 个精炼的 Props 和 1 个state插槽把步骤状态感知这一核心能力封装为声明式 APIstep定义索引、completed显式标记完成、disabled控制交互、as/asChild提供组合弹性state插槽则让 UI 定制完全跟随内部状态推导。理解其状态优先级completedactive 已越过 inactive与线性约束下的可聚焦规则能帮助你写出既符合无障碍规范又具备复杂交互逻辑的多步骤界面。更多组件级细节可继续查阅 StepperItem 元数据文档 与 Stepper 完整组件文档。【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考