Reka UI 标志Reka
backdrop
示例
组件

步进器

一组用于指示多步骤流程进度的步骤。

地址

配送

结账

第 2 步，共 0 步

功能特性

  • 可受控或不受控。
  • 支持水平/垂直方向。
  • 支持线性/非线性激活。
  • 全键盘导航。

安装

从命令行安装此组件。

sh
$ npm add reka-ui

结构

导入所有部分并将其组合。

vue
<script setup>
import { StepperDescription, StepperIndicator, StepperItem, StepperRoot, StepperTitle, StepperTrigger } from 'reka-ui'
</script>

<template>
  <StepperRoot>
    <StepperItem>
      <StepperTrigger />
      <StepperIndicator />

      <StepperTitle />
      <StepperDescription />

      <StepperSeparator />
    </StepperItem>
  </StepperRoot>
</template>

API 参考

根

包含所有步进器组件部分。

属性默认类型
as
'div'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

defaultValue
1
数字

初始渲染时应激活的步骤值。当您不需要控制步骤的状态时使用。

dir
'ltr' | 'rtl'

适用时，组合框的阅读方向。
如果省略，则全局继承自 ConfigProvider 或假定为 LTR（从左到右）阅读模式。

linear
true
布尔值

步骤是否必须按顺序完成。

modelValue
数字

要激活的受控步骤值。可以绑定为 v-model。

orientation
'horizontal'
'vertical' | 'horizontal'

步骤的排列方向。主要是为了箭头导航能相应地进行（左右 vs. 上下）。

事件触发载荷
update:modelValue
[payload: number]

值改变时调用的事件处理程序

插槽（默认）载荷
modelValue
number | undefined

当前步骤

totalSteps
数字

总步数

isNextDisabled
布尔值

下一步是否被禁用

isPrevDisabled
布尔值

上一步是否被禁用

isFirstStep
布尔值

第一步是否激活

isLastStep
布尔值

最后一步是否激活

goToStep
(step: number): void

跳转到指定步骤

nextStep
(): void

跳转到下一步

prevStep
(): void

跳转到上一步

hasNext
(): boolean

是否有下一步

hasPrev
(): boolean

是否有上一步

方法类型
goToStep
(step: number) => void
nextStep
() => void
prevStep
() => void
hasNext
() => boolean
hasPrev
() => boolean
数据属性值
[data-orientation]"垂直" | "水平"
[data-linear]线性时存在

项

步进器项组件。

属性默认类型
as
'div'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

completed
false
布尔值

显示步骤是否已完成。

disabled
false
布尔值

当 true 时，阻止用户与该步骤交互。

step*
数字

将步进器项与索引关联的唯一值

插槽（默认）载荷
state
'active' | 'completed' | 'inactive'

步进器项的当前状态

数据属性值
[data-state]"active" | "inactive" | "completed"
[data-disabled]禁用时存在
[data-orientation]"垂直" | "水平"

触发器

切换步骤的触发器。

属性默认类型
as
'button'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

数据属性值
[data-state]"active" | "inactive" | "completed"
[data-disabled]禁用时存在
[data-orientation]"垂直" | "水平"

指示器

步骤的指示器。

属性默认类型
as
'div'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

插槽（默认）载荷
step
数字

当前步骤

标题

当步进器触发器获得焦点时，会播报的可访问标题。

如果您想隐藏标题，请将其包裹在我们的 Visually Hidden 工具（如 <VisuallyHidden asChild>）中。

属性默认类型
as
'h4'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

描述

当步进器触发器获得焦点时，会播报的可选可访问描述。

如果您想隐藏描述，请将其包裹在我们的 Visually Hidden 工具（如 <VisuallyHidden asChild>）中。如果您想完全移除描述，请移除此部分并向 StepperTrigger 传递 aria-describedby="undefined"。

属性默认类型
as
'div'
AsTag | Component

此组件应渲染为的元素或组件。可通过 asChild 覆盖。

asChild
布尔值

更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。

阅读我们的 组合指南了解更多详情。

completed
false
布尔值

显示步骤是否已完成。

disabled
false
布尔值

当 true 时，阻止用户与该步骤交互。

step*
数字

将步进器项与索引关联的唯一值

插槽（默认）载荷
state
'active' | 'completed' | 'inactive'

步进器项的当前状态

示例

垂直

您可以使用 orientation 属性创建垂直步进器。

vue
<script setup>
import { StepperDescription, StepperIndicator, StepperItem, StepperRoot, StepperTitle } from 'reka-ui'
</script>

<template>
  <StepperRoot
    :default-value="1"
    orientation="vertical"
  >
    <StepperItem>
      <StepperIndicator />
      <StepperTitle />
      <StepperDescription />
    </StepperItem>
    <StepperItem>
      <StepperIndicator />
      <StepperTitle />
      <StepperDescription />
    </StepperItem>
  </StepperRoot>
</template>

带控件

您可以使用按钮为步进器添加额外控件，并使用 useTemplateRef 访问类型化的组件实例。

vue
<script setup lang="ts">
const stepper = useTemplateRef('stepper')
</script>

<template>
  <StepperRoot
    ref="stepper"
    :default-value="1"
  >
    <StepperItem>
      <StepperIndicator />
      <StepperTitle />
      <StepperDescription />
    </StepperItem>
    <StepperItem>
      <StepperIndicator />
      <StepperTitle />
      <StepperDescription />
    </StepperItem>
  </StepperRoot>

  <div class="flex gap-2 justify-between mt-4">
    <button
      :disabled="!stepper?.hasPrev()"
      @click="stepper?.prevStep()"
    >
      Prev
    </button>

    <button
      :disabled="!stepper?.hasNext()"
      @click="stepper?.nextStep()"
    >
      Next
    </button>
  </div>
</template>

可访问性

键盘交互

键描述
Tab
当焦点移至步骤时，聚焦第一个步骤。
向下箭头键
根据 orientation 移动焦点到下一步。
向右箭头
根据 orientation 移动焦点到下一步。
向上箭头键
根据 orientation 移动焦点到上一步。
向左箭头
根据 orientation 移动焦点到上一步。
EnterSpace
选择当前聚焦的步骤。