Steps 步骤条
把一个流程拆成几步显示,标出已完成、进行中和未开始的步骤。每一步用一个 NsStepItem。
引入
import { NsSteps, NsStepItem } from '@ns/ui'
基础用法
active 是当前步骤的序号,从 0 开始。序号小于 active 的步骤是已完成,等于的是进行中,大于的是等待。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSteps, NsStepItem, NsButton, NsSpace } from '@ns/ui'
const active = ref(0)
const prev = () => {
active.value = Math.max(active.value - 1, 0)
}
const next = () => {
active.value = active.value >= 3 ? 0 : active.value + 1
}
</script>
<template>
<NsSteps :active="active">
<NsStepItem title="填写信息" description="填写基本资料" />
<NsStepItem title="验证身份" description="上传证件照片" />
<NsStepItem title="完成注册" description="注册成功" />
</NsSteps>
<NsSpace style="margin-top: 16px">
<NsButton :disabled="active === 0" @click="prev">上一步</NsButton>
<NsButton type="primary" @click="next">下一步</NsButton>
<span>active = {{ active }}</span>
</NsSpace>
</template>
active 等于步骤总数时,所有步骤都是已完成。上面点到 active = 3 就能看到。
方向
direction 可选 horizontal(横向,默认)和 vertical(纵向)。纵向时步骤从上往下排,图标在左、文字在右,竖线把相邻的步骤连起来。
<template>
<NsSpace direction="vertical" fill size="large">
<div>
<p class="row-label">horizontal</p>
<NsSteps :active="1" direction="horizontal">
<NsStepItem title="提交申请" description="2026-11-01 10:00" />
<NsStepItem title="部门审批" description="等待部门经理审批" />
<NsStepItem title="归档" description="审批通过后自动归档" />
</NsSteps>
</div>
<div>
<p class="row-label">vertical</p>
<NsSteps :active="1" direction="vertical">
<NsStepItem title="提交申请" description="2026-11-01 10:00" />
<NsStepItem title="部门审批" description="等待部门经理审批" />
<NsStepItem title="归档" description="审批通过后自动归档" />
</NsSteps>
</div>
</NsSpace>
</template>
<style scoped>
.row-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
居中对齐
align-center 让图标、标题和描述在每一步里居中,连接线连在相邻两个图标之间。只对横向步骤条起作用。上面是默认的左对齐,下面是居中:
<template>
<NsSpace direction="vertical" fill size="large">
<NsSteps :active="1">
<NsStepItem title="填写信息" description="填写基本资料" />
<NsStepItem title="验证身份" description="上传证件照片" />
<NsStepItem title="完成注册" description="注册成功" />
</NsSteps>
<NsSteps :active="1" align-center>
<NsStepItem title="填写信息" description="填写基本资料" />
<NsStepItem title="验证身份" description="上传证件照片" />
<NsStepItem title="完成注册" description="注册成功" />
</NsSteps>
</NsSpace>
</template>
简洁风格
simple 给整个步骤条加上浅色背景,图标换成更小的 24px 实心圆:未开始是灰底,进行中是主色底,已完成是浅主色底加对勾,success 是成功色底,error 是危险色底。可以和居中对齐、纵向一起用。
<template>
<NsSpace direction="vertical" fill>
<NsSteps :active="1" simple>
<NsStepItem title="选择商品" />
<NsStepItem title="确认订单" />
<NsStepItem title="支付" />
</NsSteps>
<NsSteps :active="2" simple align-center finish-status="success">
<NsStepItem title="选择商品" />
<NsStepItem title="确认订单" />
<NsStepItem title="支付" />
</NsSteps>
<NsSteps :active="1" simple process-status="error">
<NsStepItem title="选择商品" />
<NsStepItem title="确认订单" description="库存不足" />
<NsStepItem title="支付" />
</NsSteps>
<NsSteps :active="1" simple direction="vertical">
<NsStepItem title="选择商品" description="已选 3 件" />
<NsStepItem title="确认订单" description="请核对收货地址" />
<NsStepItem title="支付" />
</NsSteps>
</NsSpace>
</template>
每一步的尺寸
space 是每一步占的尺寸:横向时是宽度,纵向时是高度。数字按 px 算,字符串原样使用(比如 '25%')。最后一步不受 space 影响,大小等于它的内容。不设 space 时,横向的步骤(最后一步除外)平分剩余宽度,纵向的步骤高度等于内容。
<template>
<NsSpace direction="vertical" fill size="large">
<NsSteps :active="1" :space="200">
<NsStepItem title="宽 200px" />
<NsStepItem title="宽 200px" />
<NsStepItem title="步骤三" />
</NsSteps>
<NsSteps :active="1" space="25%">
<NsStepItem title="宽 25%" />
<NsStepItem title="宽 25%" />
<NsStepItem title="步骤三" />
</NsSteps>
<NsSteps :active="1" direction="vertical" space="80px">
<NsStepItem title="高 80px" />
<NsStepItem title="高 80px" />
<NsStepItem title="步骤三" />
</NsSteps>
</NsSpace>
</template>
步骤状态
状态有 wait(等待)、process(进行中)、finish(已完成)、error(出错)、success(成功)五种。已完成(finish、success)的步骤图标显示对勾,error 显示叉号,其余显示序号。
NsStepItem 的 status 可以单独指定某一步的状态,写了以后不再按 active 计算。下面每一步是一种状态:
<template>
<NsSteps>
<NsStepItem title="已完成(finish)" status="finish" />
<NsStepItem title="成功(success)" status="success" />
<NsStepItem title="出错(error)" status="error" />
<NsStepItem title="进行中(process)" status="process" />
<NsStepItem title="等待(wait)" status="wait" />
</NsSteps>
</template>
finish-status 设置已完成步骤的状态,process-status 设置当前步骤的状态。比如当前步骤出错了,把 process-status 设成 error。
<template>
<NsSpace direction="vertical" fill size="large">
<NsSteps :active="1" process-status="error">
<NsStepItem title="提交" />
<NsStepItem title="审核" description="审核不通过" />
<NsStepItem title="完成" />
</NsSteps>
<NsSteps :active="2" finish-status="success">
<NsStepItem title="提交" />
<NsStepItem title="审核" />
<NsStepItem title="完成" />
</NsSteps>
<NsSteps :active="1">
<NsStepItem title="下单" />
<NsStepItem title="发货" status="error" description="仓库缺货,单独指定 status" />
<NsStepItem title="签收" />
</NsSteps>
</NsSpace>
</template>
两个属性都可以取五种状态中的任意一种,切换看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup, NsSpace, NsStepItem, NsSteps } from '@ns/ui'
import type { StepsStatus } from '@ns/ui'
const statuses: StepsStatus[] = ['wait', 'process', 'finish', 'error', 'success']
const finishStatus = ref<StepsStatus>('finish')
const processStatus = ref<StepsStatus>('process')
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap>
<span class="row-label">finish-status</span>
<NsRadioGroup v-model="finishStatus" type="button" size="small">
<NsRadio v-for="item in statuses" :key="item" :value="item">{{ item }}</NsRadio>
</NsRadioGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">process-status</span>
<NsRadioGroup v-model="processStatus" type="button" size="small">
<NsRadio v-for="item in statuses" :key="item" :value="item">{{ item }}</NsRadio>
</NsRadioGroup>
</NsSpace>
<NsSteps :active="2" :finish-status="finishStatus" :process-status="processStatus">
<NsStepItem title="第一步" description="已完成" />
<NsStepItem title="第二步" description="已完成" />
<NsStepItem title="第三步" description="当前步骤" />
<NsStepItem title="第四步" description="等待" />
</NsSteps>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 104px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
自定义图标
icon 传图标名(NsIcon 的 name)或者 VNode,图标会代替序号和状态图标。需要更多控制时用 icon 插槽。
<script setup lang="ts">
import { h } from 'vue'
import { NsSteps, NsStepItem, NsIcon } from '@ns/ui'
// icon 也可以传 VNode
const payIcon = h(NsIcon, { name: 'star' })
</script>
<template>
<NsSteps :active="1">
<NsStepItem title="登录" icon="user" />
<NsStepItem title="编辑" icon="edit" />
<NsStepItem title="上传">
<template #icon>
<NsIcon name="upload" />
</template>
</NsStepItem>
<NsStepItem title="评价" :icon="payIcon" />
</NsSteps>
</template>
自定义标题和描述
title 和 description 插槽可以放任意内容。没写 description 属性也没写 description 插槽时,不渲染描述区域。
<template>
<NsSteps :active="1">
<NsStepItem>
<template #title>
<strong>提交申请</strong>
</template>
<template #description>
<span style="color: var(--ns-color-success)">已于 11 月 1 日提交</span>
</template>
</NsStepItem>
<NsStepItem title="审批中" description="预计 3 个工作日" />
<NsStepItem title="完成" />
</NsSteps>
</template>
点击切换
clickable 为 true 时,点步骤触发 change,参数是被点步骤的序号。组件不会自己改 active,要在 change 里改。横向、纵向都可以点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSteps, NsStepItem, NsSpace } from '@ns/ui'
const active = ref(0)
const handleChange = (index: number) => {
active.value = index
}
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSteps :active="active" clickable @change="handleChange">
<NsStepItem title="基本信息" />
<NsStepItem title="联系方式" />
<NsStepItem title="确认提交" />
</NsSteps>
<NsSteps :active="active" direction="vertical" clickable @change="handleChange">
<NsStepItem title="基本信息" description="点我切换" />
<NsStepItem title="联系方式" description="点我切换" />
<NsStepItem title="确认提交" description="点我切换" />
</NsSteps>
</NsSpace>
<p style="margin-top: 12px">change 返回的序号:{{ active }}</p>
</template>
可点击时每一步都能用 Tab 键聚焦,聚焦后按回车或空格等同于点击。
动态增删步骤
步骤可以用 v-for、v-if 动态生成。增删或重新排序后,序号和状态按步骤在页面上的顺序重新计算。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSteps, NsStepItem, NsButton } from '@ns/ui'
const needReview = ref(true)
</script>
<template>
<NsSteps :active="1">
<NsStepItem title="提交" />
<NsStepItem v-if="needReview" title="复核" />
<NsStepItem title="审批" />
<NsStepItem title="完成" />
</NsSteps>
<NsButton style="margin-top: 16px" @click="needReview = !needReview">
{{ needReview ? '去掉复核' : '加上复核' }}
</NsButton>
</template>
读取步骤信息
NsSteps 通过 ref 暴露 steps(当前所有步骤,顺序和页面上一致)和 active。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsStepItem, NsSteps } from '@ns/ui'
const stepsRef = ref<InstanceType<typeof NsSteps>>()
const info = ref('')
const read = () => {
const steps = stepsRef.value?.steps ?? []
const titles = steps.map((step) => step.title).join('、')
info.value = `共 ${steps.length} 步:${titles};当前序号 ${stepsRef.value?.active}`
}
</script>
<template>
<NsSteps ref="stepsRef" :active="1">
<NsStepItem title="提交" />
<NsStepItem title="审批" />
<NsStepItem title="完成" />
</NsSteps>
<NsSpace style="margin-top: 16px">
<NsButton @click="read">读取步骤信息</NsButton>
<span>{{ info }}</span>
</NsSpace>
</template>
NsSteps Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| active | number | 0 | 当前步骤的序号,从 0 开始 |
| space | number | string | - | 每一步的尺寸,横向是宽度、纵向是高度。数字按 px,字符串原样使用。最后一步不受影响 |
| direction | 'horizontal' | 'vertical' | 'horizontal' | 排列方向 |
| alignCenter | boolean | false | 每一步的内容是否居中,只对横向起作用 |
| simple | boolean | false | 是否使用简洁风格 |
| finishStatus | 'wait' | 'process' | 'finish' | 'error' | 'success' | 'finish' | 已完成步骤的状态 |
| processStatus | 'wait' | 'process' | 'finish' | 'error' | 'success' | 'process' | 当前步骤的状态 |
| clickable | boolean | false | 步骤能不能点击。为 true 时点击触发 change,步骤可以用键盘聚焦 |
NsStepItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | string | '' | 标题。写了 title 插槽时不显示 |
| description | string | '' | 描述。写了 description 插槽时不显示 |
| icon | string | VNode | - | 图标,字符串是 NsIcon 的 name。设了以后代替序号和状态图标 |
| status | 'wait' | 'process' | 'finish' | 'error' | 'success' | - | 这一步的状态。设了以后不再按 active 计算 |
NsSteps Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| change | (index: number) | clickable 时用户点击步骤(或聚焦后按回车、空格)触发,参数是这一步的序号,从 0 开始 |
NsSteps Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsStepItem |
NsStepItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| title | - | 标题 |
| description | - | 描述 |
| icon | - | 图标,代替序号、状态图标和 icon 属性 |
NsStepItem 没有默认插槽,描述只能用 description 属性或 description 插槽。
NsSteps 暴露的属性
通过组件的 ref 读取,只用来读:
| 属性 | 类型 | 说明 |
|---|---|---|
| steps | StepItemInstance[] | 当前所有步骤的信息,顺序和页面上的顺序一致 |
| active | number | 当前步骤的序号,等于 active 属性 |
类型
import type {
StepsProps,
StepItemProps,
StepsDirection,
StepsStatus,
StepItemInstance
} from '@ns/ui'
import type { VNode } from 'vue'
type StepsDirection = 'horizontal' | 'vertical'
type StepsStatus = 'wait' | 'process' | 'finish' | 'error' | 'success'
interface StepsProps {
active?: number
space?: number | string
direction?: StepsDirection
alignCenter?: boolean
simple?: boolean
finishStatus?: StepsStatus
processStatus?: StepsStatus
clickable?: boolean
}
interface StepItemProps {
title?: string
description?: string
icon?: string | VNode
status?: StepsStatus
}
/** ref 上 steps 里的每一项 */
interface StepItemInstance {
uid: number
/** 步骤的根元素 */
getEl: () => HTMLElement | undefined
readonly title: string
readonly description: string
readonly icon: string | VNode | undefined
readonly status: StepsStatus | undefined
}
另外还导出了 StepsContext 和注入用的 STEPS_INJECTION_KEY,自己写和 NsSteps 配合的子组件时才用得到。
注意事项
NsStepItem要放在NsSteps里面,单独使用时控制台会有警告。中间可以隔着自己写的组件。- 序号按步骤在页面上的顺序计算,
v-for、v-if增删或重排后会跟着变。 clickable时点击当前步骤也会触发change,参数和active相同,需要的话在处理函数里自己判断。change只是通知,active要自己改。没有clickable时点击不触发事件,步骤也不能用 Tab 键聚焦。- 当前步骤带
aria-current="step";可点击时每一步是role="button"。 - 运行时修改
NsSteps的属性(direction、clickable、finishStatus等),步骤会跟着变。