Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
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等),步骤会跟着变。