Stepper 步骤条
可视化的多步流程引导组件，完成步骤带勾选图标，激活步骤高亮放大，粗边框圆形节点与连接线尽显新粗野主义质感。
预览
水平
账户信息
填写基本资料
安全设置
设置密码与验证
偏好配置
个性化设置
完成
注册成功
垂直
账户信息
填写基本资料
安全设置
设置密码与验证
偏好配置
个性化设置
完成
注册成功
变体 (accent)
账户信息
填写基本资料
安全设置
设置密码与验证
偏好配置
个性化设置
完成
注册成功
尺寸 (lg)
账户信息
填写基本资料
安全设置
设置密码与验证
偏好配置
个性化设置
完成
注册成功
不可点击
账户信息
填写基本资料
安全设置
设置密码与验证
偏好配置
个性化设置
完成
注册成功
安装
pnpm dlx brutx-vue@latest add stepper用法
<script setup>
import { Stepper } from 'brutx-ui-vue'
import type { StepperStep } from 'brutx-ui-vue'
import { ref } from 'vue'
const steps: StepperStep[] = [
{ id: 1, title: '基本信息', description: '填写账户资料' },
{ id: 2, title: '安全设置', description: '设置密码' },
{ id: 3, title: '完成', description: '注册成功' },
]
const current = ref(0)
</script>
<template>
<!-- 水平步骤条 -->
<Stepper v-model="current" :steps="steps" orientation="horizontal" />
<!-- 垂直步骤条（支持内容插槽） -->
<Stepper v-model="current" :steps="steps" orientation="vertical">
<template #step-1>
<p class="text-sm">在此填写第一步的内容...</p>
</template>
<template #step-2>
<p class="text-sm">在此填写第二步的内容...</p>
</template>
</Stepper>
<!-- 导航按钮 -->
<button :disabled="current === 0" @click="current--">上一步</button>
<button :disabled="current === steps.length - 1" @click="current++">下一步</button>
</template>不可点击
设置 clickable 为 false 可禁用步骤点的点击跳转，仅作展示用。
<Stepper v-model="current" :steps="steps" :clickable="false" />变体
通过 variant 属性控制激活步骤的颜色。
| 变体 | 说明 |
|---|---|
default | 默认背景色（bg-brutal-bg） |
primary | 主色（珊瑚红）背景 |
accent | 强调色（黄色）背景 |
<Stepper v-model="current" :steps="steps" variant="accent" />尺寸
通过 size 属性控制步骤点尺寸。
| 尺寸 | 说明 |
|---|---|
sm | 小尺寸节点 |
default | 默认尺寸节点 |
lg | 大尺寸节点 |
<Stepper v-model="current" :steps="steps" size="lg" />数据类型
interface StepperStep {
id: string | number // 唯一标识（垂直插槽名为 step-{id}）
title: string // 步骤标题
description?: string // 可选副标题
}导出类型
import type { StepperStep } from 'brutx-ui-vue'API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
steps必填 | StepperStep[] | — | 按显示顺序提供步骤数据，每项包含唯一 id、标题和可选描述。 |
详情声明类型StepperStep[] 关联类型 StepperStep 类型定义 — StepperStepexport interface StepperStep {
id: string | number;
title: string;
description?: string;
}默认值详情
来源packages/ui/src/components/stepper/Stepper.vue | |||
modelValue必填 | number | — | 当前步骤的从 0 开始索引；通过 v-model 受控同步，索引越界时展示状态会钳制到有效范围。 |
详情 | |||
orientation | "vertical" | "horizontal" | undefined | "horizontal" | 设置步骤条布局方向；默认横向，vertical 模式可为当前步骤提供 step-{id} 内容插槽。 |
详情声明类型"vertical" | "horizontal" | undefined 字面量
默认值详情
来源packages/ui/src/components/stepper/Stepper.vue | |||
size | "default" | "lg" | "sm" | undefined | "default" | 设置步骤节点及对应连接线的尺寸级别。 |
详情声明类型NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/stepper/Stepper.vue | |||
variant | "accent" | "default" | "primary" | undefined | "default" | 设置当前激活步骤节点使用的颜色变体。 |
详情声明类型NonNullable<"default" | "primary" | "accent" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/stepper/Stepper.vue | |||
clickable | boolean | undefined | true | 允许通过点击步骤节点跳转到对应步骤。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/stepper/Stepper.vue | |||
class | string | undefined | undefined | 追加到步骤条根容器的 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/stepper/Stepper.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@update:modelValue | [step: number] | 当前步骤有效索引变化时发出新索引，用于同步 v-model。 |
详情声明类型[step: number] 来源packages/ui/src/components/stepper/Stepper.vue | ||
@step-click | [index: number] | 用户点击步骤节点时携带该节点的从 0 开始索引发出。 |
详情声明类型[index: number] 来源packages/ui/src/components/stepper/Stepper.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
currentStep | number | 只读的当前步骤索引；无步骤时为 -1，其他情况下会限制在有效步骤范围内。 |
详情声明类型number 来源packages/ui/src/components/stepper/Stepper.vue | ||
totalSteps | number | 只读的步骤总数，等于 steps 数组长度。 |
详情声明类型number 来源packages/ui/src/components/stepper/Stepper.vue | ||
goToStep | (index: number) => void | 请求跳转到指定索引；只有索引位于现有步骤范围内时才发出更新。 |
详情声明类型(index: number) => void 来源packages/ui/src/components/stepper/Stepper.vue | ||
nextStep | () => void | 请求前进一个步骤；空列表或已到最后一步时不发出更新。 |
详情声明类型() => void 来源packages/ui/src/components/stepper/Stepper.vue | ||
previousStep | () => void | 请求后退一个步骤；空列表或已到第一步时不发出更新。 |
详情声明类型() => void 来源packages/ui/src/components/stepper/Stepper.vue | ||
isFirstStep | boolean | 只读布尔值，表示当前步骤是否为第一步；空列表时为 false。 |
详情声明类型boolean 字面量
来源packages/ui/src/components/stepper/Stepper.vue | ||
isLastStep | boolean | 只读布尔值，表示当前步骤是否为最后一步；空列表时为 false。 |
详情声明类型boolean 字面量
来源packages/ui/src/components/stepper/Stepper.vue | ||
插槽
垂直模式下，每个步骤在激活时可通过 #step-{id} 插槽注入内容区域：
<Stepper v-model="current" :steps="steps" orientation="vertical">
<template #step-1>
<!-- 第一步激活时展示的内容 -->
</template>
</Stepper>可访问性
- 键盘操作：步骤按钮支持方向键导航（
←/→水平模式，↑/↓垂直模式），Home/End跳转首尾步骤，Enter/Space点击当前聚焦步骤 - 焦点管理：通过 Tab 键可聚焦到步骤按钮
节点状态说明
| 状态 | 样式 | 条件 |
|---|---|---|
completed | 绿色背景 + ✓ 图标 | 索引 < 当前步骤 |
active | 变体背景色 + 大阴影 | 索引 = 当前步骤 |
upcoming | 默认背景色 + 半透明 | 索引 > 当前步骤 |
方法（defineExpose）
实例方法和只读状态见上方 API 参考。通过 ref 调用实例方法：
<script setup>
import { ref } from 'vue'
import { Stepper } from 'brutx-ui-vue'
const stepperRef = ref(null)
const current = ref(0)
const steps = [...]
function handleNext() {
stepperRef.value?.nextStep()
}
function handleBack() {
stepperRef.value?.previousStep()
}
</script>
<template>
<Stepper ref="stepperRef" v-model="current" :steps="steps" />
<button @click="handleBack" :disabled="stepperRef?.isFirstStep">上一步</button>
<button @click="handleNext" :disabled="stepperRef?.isLastStep">下一步</button>
</template>