Steps 步骤条

17:06

说明

ux-steps 是容器：统一设置 mode、current、direction 与激活/未激活颜色，并通过 provide 把上下文下发给子步骤；它可以直接用默认插槽放 ux-step，也可以只传 list（{ name, desc }）自动渲染。ux-step 是单个步骤，负责显示 name / desc，并从父级读取模式与配色；索引不超过 current 的步骤（含当前步）显示为已完成态。

兼容性

平台	支持情况
App	✅ 支持（连接线用 top/bottom 双定位拉伸，规避 App 端不支持的 calc()）
H5	✅ 支持
微信小程序	✅ 支持

示例

点模式

默认 dot 模式，横向排列，current 设置当前步骤。

查看源码

<template>
    <ux-steps :current="1">
        <ux-step name="步骤一" />
        <ux-step name="步骤二" />
        <ux-step name="步骤三" />
    </ux-steps>
</template>

数字模式

mode=number 时显示数字序号，已完成步骤显示勾选图标。

查看源码

<template>
    <ux-steps mode="number" :current="2">
        <ux-step name="步骤一" />
        <ux-step name="步骤二" />
        <ux-step name="步骤三" />
        <ux-step name="步骤四" />
    </ux-steps>
</template>

竖向排列

direction=column 时竖向排列，可配合 desc 显示描述。

查看源码

<template>
    <ux-steps direction="column" :current="1">
        <ux-step name="步骤一" desc="已完成" />
        <ux-step name="步骤二" desc="进行中" />
        <ux-step name="步骤三" desc="待处理" />
    </ux-steps>
</template>

自定义颜色

通过 active-color 和 inactive-color 自定义激活与未激活颜色。

查看源码

<template>
    <ux-steps mode="number" :current="1" active-color="#fa3534" inactive-color="#909399">
        <ux-step name="步骤一" />
        <ux-step name="步骤二" />
        <ux-step name="步骤三" />
    </ux-steps>
</template>

可控步骤

结合按钮控制 current 值，实现步骤前进/后退。

查看源码

<template>
    <ux-steps mode="number" :current="current">
        <ux-step name="步骤一" />
        <ux-step name="步骤二" />
        <ux-step name="步骤三" />
    </ux-steps>
    <view class="btn-row">
        <ux-button size="small" @click="prev" :disabled="current === 0">上一步</ux-button>
        <ux-button size="small" type="primary" @click="next" :disabled="current === 2">下一步</ux-button>
    </view>
</template>

<script setup lang="uts">
const current = ref<number>(0);

function prev(): void {
    if (current.value > 0) {
        current.value--;
    }
}

function next(): void {
    if (current.value < 2) {
        current.value++;
    }
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    margin-top: 15px;
}
</style>

API

Props

ux-steps

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
mode	设置模式（dot|number，默认dot）	string	'dot'	-
list	数轴条数据	StepsListItem[]	-	-
type	主题类型（默认primary）	string	'primary'	-
current	设置当前处于第几步（默认0）	number | string	0	-
activeColor	已完成步骤的激活颜色，默认取主题色 primary	string	''	-
inactiveColor	未激活步骤的颜色，默认取 info	string	''	-
icon	自定义图标（默认check）	string	'checkmark'	-
direction	排列方向 row-横向 column-竖向（默认row）	string	'row'	-

ux-step

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
name	步骤名称	string	''	-
desc	步骤描述	string	''	-
icon	自定义图标	string	''	-
activeColor	激活颜色，覆盖 ux-steps 的同名配置	string	''	-
inactiveColor	未激活颜色，覆盖 ux-steps 的同名配置	string	''	-
mode	模式 dot|number，脱离 ux-steps 时的兜底值	String	'dot'	-

Events

本页组件均无事件。

Slots

ux-steps

插槽名	说明	版本
default	放置 ux-step 子组件；不传时按 list 自动渲染	-

注意事项

1. ux-step 依赖 ux-steps 提供的上下文（useParent），必须放在 ux-steps 内；脱离父级单独使用会回退到自身默认值，且不参与步骤计数、不显示连接线。
2. current 从 0 开始，索引不超过 current 的步骤都算已完成（含当前步）；示例中 current=1 表示前两步为已完成态。
3. 步骤切换不会自动发生：本页组件均不派发事件，需自行维护 current（如「可控步骤」示例用按钮前后翻页）。
4. mode / direction 由 ux-steps 统一决定，ux-step 上的 mode 仅在脱离父级时兜底生效。
5. 激活/未激活颜色默认取主题色 primary 与 info，ux-steps 与 ux-step 都可设置，ux-step 的值优先。
6. number 模式下已完成步骤显示图标，默认 checkmark，可用 icon 自定义（ux-step 优先于 ux-steps）。
7. ux-steps 的 type 目前仅声明、未参与渲染，配色请用 active-color / inactive-color。