步骤 - Semi Design Next

代码演示

如何引入

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';
</script>

Steps.Step 也可以按名导入：Step。Step 的 title、description、icon 是插槽（#title、#description、#icon）。Steps 只识别直接子节点中的 Steps.Step，其他子节点不渲染、不占序号，开发环境给出警告；Step 在 Steps 之外不渲染任何内容。

默认步骤条（旧版）

建议使用简易版 steps（新版），旧版后续会逐渐 deprecate

Finished

This is a description

In Progress

This is a description

Waiting

This is a description

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <Steps :current="1" @change="log">
        <Steps.Step>
            <template #title>Finished</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>In Progress</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>Waiting</template>
            <template #description>This is a description</template>
        </Steps.Step>
    </Steps>
</template>

简单步骤条（新版）

通过设置 type="basic" 显示为简洁风格步骤条

Finished

This is a description

In Progress

This is a description

Waiting

This is a description

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <Steps :current="1" type="basic" @change="log">
        <Steps.Step>
            <template #title>Finished</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>In Progress</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>Waiting</template>
            <template #description>This is a description</template>
        </Steps.Step>
    </Steps>
</template>

导航步骤条

通过设置 type="nav" 显示为导航风格步骤条。导航风格的步骤条有以下特点：

步骤条同样支持交互：Steps 监听步骤切换或 Step 绑定点击回调后，步骤可聚焦、可点击，行为与其他类型一致。
适用于步骤间互相关联较小，内容互不影响，且需要突出页面视觉元素时使用。
步骤条的宽度按照内容物撑开。
Steps.Step 只渲染标题，description、icon、status 不生效；其余属性与事件（aria-label、role、点击与键盘回调、类名与样式等）与其他类型相同。

注册账号

这个项目的文字比较多多多多

产品用途

期待尝试功能

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <div :style="{ display: 'flex', justifyContent: 'center' }">
        <Steps :current="1" :style="{ margin: 'auto' }" type="nav" @change="log">
            <Steps.Step>
                <template #title>注册账号</template>
            </Steps.Step>
            <Steps.Step>
                <template #title>这个项目的文字比较多多多多</template>
            </Steps.Step>
            <Steps.Step>
                <template #title>产品用途</template>
            </Steps.Step>
            <Steps.Step>
                <template #title>期待尝试功能</template>
            </Steps.Step>
        </Steps>
    </div>
</template>

迷你尺寸步骤条

通过设置 size="small" 显示迷你尺寸步骤条

Finished

This is a description

In Progress

This is a description

Waiting

This is a description

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <Steps :current="1" size="small" type="basic" @change="log">
        <Steps.Step>
            <template #title>Finished</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>In Progress</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>Waiting</template>
            <template #description>This is a description</template>
        </Steps.Step>
    </Steps>
</template>

注册账号

这个项目的文字比较多多多多

产品用途

期待尝试功能

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <div :style="{ display: 'flex', justifyContent: 'center' }">
        <Steps :current="1" size="small" :style="{ margin: 'auto' }" type="nav" @change="log">
            <Steps.Step>
                <template #title>注册账号</template>
            </Steps.Step>
            <Steps.Step>
                <template #title>这个项目的文字比较多多多多</template>
            </Steps.Step>
            <Steps.Step>
                <template #title>产品用途</template>
            </Steps.Step>
            <Steps.Step>
                <template #title>期待尝试功能</template>
            </Steps.Step>
        </Steps>
    </div>
</template>

处理进度

配合内容及按钮使用，表示一个流程的处理进度

First

Second

Last

First-content

代码

<script setup lang="ts">
    import { ref } from 'vue';
    import { Button, Steps } from '@fibrous/semi-ui-vue';

    const steps = [
        { title: 'First', content: 'First-content' },
        { title: 'Second', content: 'Second-content' },
        { title: 'Last', content: 'Last-content' },
    ];
    const current = ref(0);
    const log = (i: number) => console.log(i);
    const done = () => console.log('Processing complete!');
</script>

<template>
    <div>
        <Steps :current="current" type="basic" @change="log">
            <Steps.Step v-for="item in steps" :key="item.title">
                <template #title>{{ item.title }}</template>
            </Steps.Step>
        </Steps>
        <div class="steps-content" :style="{ marginTop: '4px', marginBottom: '4px' }">
            {{ steps[current].content }}
        </div>
        <div class="steps-action">
            <Button v-if="current < steps.length - 1" type="primary" @click="current += 1">Next</Button>
            <Button v-if="current === steps.length - 1" type="primary" @click="done">Done</Button>
            <Button v-if="current > 0" :style="{ marginLeft: '8px' }" @click="current -= 1">Previous</Button>
        </div>
    </div>
</template>

竖直方向的步骤条

通过设置 direction，使用竖直方向的步骤条

Finished

This is a description

In Progress

This is a description

Waiting

This is a description

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <Steps :current="1" direction="vertical" :style="{ width: '300px' }" @change="log">
        <Steps.Step>
            <template #title>Finished</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>In Progress</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>Waiting</template>
            <template #description>This is a description</template>
        </Steps.Step>
    </Steps>
</template>

Finished

This is a description

In Progress

This is a description

Waiting

This is a description

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <Steps :current="1" direction="vertical" type="basic" @change="log">
        <Steps.Step>
            <template #title>Finished</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>In Progress</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>Waiting</template>
            <template #description>This is a description</template>
        </Steps.Step>
    </Steps>
</template>

指定步骤状态

步骤运行错误，使用 Steps 的 status 属性来指定当前步骤的状态。

Finished

This is a description

In Process

This is a description

Waiting

This is a description

代码

<script setup lang="ts">
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <Steps :current="1" status="error" type="basic" @change="log">
        <Steps.Step>
            <template #title>Finished</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>In Process</template>
            <template #description>This is a description</template>
        </Steps.Step>
        <Steps.Step>
            <template #title>Waiting</template>
            <template #description>This is a description</template>
        </Steps.Step>
    </Steps>
</template>

自定义图标/状态

通过 Steps.Step 的 #icon 插槽，可以启用自定义图标；插槽存在但内容为空时不显示图标

通过设置 Steps.Step 的 status 属性，可以自定义每个 step 的状态

已完成

错误

警告

正在进行

等待

代码

<script setup lang="ts">
    import { IconHome, IconLock } from '@fibrous/semi-icons-vue';
    import { Steps } from '@fibrous/semi-ui-vue';

    const log = (i: number) => console.log(i);
</script>

<template>
    <Steps type="basic" @change="log">
        <Steps.Step status="finish">
            <template #title>已完成</template>
        </Steps.Step>
        <Steps.Step status="error">
            <template #title>错误</template>
        </Steps.Step>
        <Steps.Step status="warning">
            <template #title>警告</template>
        </Steps.Step>
        <Steps.Step status="process">
            <template #title>正在进行</template>
            <template #icon>
                <IconHome size="extra-large" />
            </template>
        </Steps.Step>
        <Steps.Step status="wait">
            <template #title>等待</template>
            <template #icon>
                <IconLock size="extra-large" />
            </template>
        </Steps.Step>
    </Steps>
</template>

onChange 回调

通过 @change 监听步骤切换（Steps 的 onChange 是函数 prop，监听与否决定步骤是否可点击），回调接收一个 number 类型的参数，等于 initial 加所选步骤的索引；点击当前步骤不会触发。current 也支持 v-model:current，绑定后所有步骤同样变为可点击。

First

Second

Last

代码

<script setup lang="ts">
    import { ref } from 'vue';
    import { Steps } from '@fibrous/semi-ui-vue';

    const steps = [{ title: 'First' }, { title: 'Second' }, { title: 'Last' }];
    const current = ref(1);
</script>

<template>
    <div>
        <Steps v-model:current="current" type="basic">
            <Steps.Step v-for="item in steps" :key="item.title">
                <template #title>{{ item.title }}</template>
            </Steps.Step>
        </Steps>
    </div>
</template>

Accessibility

ARIA

Steps、Step 组件支持传入 aria-label 或 aria-labelledby。Steps 根元素与不可点击的 Step 本身没有语义角色，传入名称时带 role="group"，名称因此能进入可访问名称；没有名称时不加 role。fill、basic、nav 三种类型一致
当前步骤带有 aria-current="step"，其余步骤不带该属性
Steps 监听步骤切换或 Step 绑定点击回调后，步骤可通过 Tab 聚焦，role 默认为 button（优先于 group，显式传入的 role 优先于二者）；焦点在步骤上时按 Enter 或空格与鼠标点击一致，同时触发 Step 的点击回调与 Steps 的切换回调；不可点击的步骤不可聚焦
点击来自步骤内其他可聚焦元素（input、button、链接等）时只触发 Step 的点击回调，不触发 Steps 的切换回调。可点击的步骤本身是 role="button"，title、description 中放可聚焦控件会形成嵌套交互元素，此时不要让步骤可点击

API 参考

Steps

整体步骤条。

Props

属性	说明	类型	默认值
type	步骤条类型，可选 fill、basic、nav。	`StepsType`	`semiDefault("Steps", "type", "fill")`
current	当前步骤，从 0 开始计数；子 Step 可用 status 覆盖状态。	`number`	`semiDefault("Steps", "current", 0)`
initial	起始序号，从 0 开始计数。	`number`	`semiDefault("Steps", "initial", 0)`
direction	步骤条方向，可选 horizontal、vertical。	`StepsDirection`	`semiDefault("Steps", "direction", "horizontal")`
status	当前步骤的状态，可选 wait、process、finish、error、warning。	`StepStatus`	`semiDefault("Steps", "status", "process")`
size	basic 与 nav 类型的尺寸，可选 default、small。	`StepsSize`	`semiDefault("Steps", "size", "default")`
hasLine	basic 类型是否显示连接线。	`boolean`	`semiDefault("Steps", "hasLine", true)`
prefixCls	根元素的类名前缀。	`string`	`semiDefault("Steps", "prefixCls", stepsClasses.PREFIX)`
onChange	点击或键盘选择步骤时调用，参数为该步骤序号（initial 加索引）；点击当前步骤不调用。是函数 prop，使用方照常写 @change；传入后所有 Step 变为可点击。	`Type`	`undefined`
onUpdate:current	v-model:current 绑定的更新函数，行为与 onChange 一致。	`Type`	`undefined`

Events

事件	说明	回调参数
无

Slots

插槽	说明	作用域参数
default	Steps.Step 子节点；每个元素或组件按顺序占一个步骤位置，空白和文本除外，包装 Step 的组件同样编号。	`any`

Exposes

名称	说明	类型
无

class、style 与原生属性经 attrs 传入，落在 Steps 根元素上。

Steps.Step

步骤条内的每一个步骤。

Props

属性	说明	类型	默认值
status	该步骤自己的状态；缺省时随 Steps 的 current 与 status 自动决定。	`StepStatus`	`undefined`

Events

事件	说明	回调参数
无

Slots

插槽	说明	作用域参数
title	标题。	`any`
description	详情描述；nav 类型不渲染。	`any`
icon	自定义图标，提供后替换状态图标，内容为空则不显示图标；nav 类型不渲染。	`any`

Exposes

名称	说明	类型
无

class、style、aria-*、role、tabindex 与 @click、@keydown 等原生属性和事件经 attrs 落在 Step 的根元素上。使用方的 @click 让该 Step 可点击；Steps 的 onChange 先于 Step 自身的 @click 执行。tabindex 可由使用方覆盖。

文案规范

步骤标题
- 标题应保持简洁，避免截断和换行；
- 使用句子大小写书写；
- 不要包含标点符号
描述
- 为标题补充上下文信息
- 不要以标点符号结尾

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$transition_duration-steps_item_title-text	var(--semi-transition_duration-none)	步骤条标题文字-背景色-动画持续时间
$transition_function-steps_item_title-text	var(--semi-transition_function-easeIn)	步骤条标题文字-背景色-过渡曲线
$transition_delay-steps_item_title-text	var(--semi-transition_delay-none)	步骤条标题文字-背景色-延迟时间
$transition_duration-steps_item_title-icon	var(--semi-transition_duration-none)	步骤条标题文字-背景色-动画持续时间
$transition_function-steps_item_title-icon	var(--semi-transition_function-easeIn)	步骤条标题文字-背景色-过渡曲线
$transition_delay-steps_item_title-icon	var(--semi-transition_delay-none)	步骤条标题文字-背景色-延迟时间
$transition_duration-steps_item_backgroundColor	var(--semi-transition_duration-none)	步骤条标题文字-背景色-动画持续时间
$transition_function-steps_item_backgroundColor	var(--semi-transition_function-easeIn)	步骤条标题文字-背景色-过渡曲线
$transition_delay-steps_item_backgroundColor	var(--semi-transition_delay-none)	步骤条标题文字-背景色-延迟时间
$transform_scale-step-item	var(--semi-transform_scale-small)	步骤条item-放大
$color-steps-bg-active	var(--semi-color-fill-1)	步骤条背景 - 按下态
$color-steps-bg-default	var(--semi-color-text-2)	未到达步骤条图标背景
$color-steps-bg-hover	var(--semi-color-fill-0)	步骤条背景 - 悬浮态
$color-steps-border-default	transparent	步骤条描边 - 默认
$color-steps-icon-default	var(--semi-color-text-2)	未到达步骤条图标背景
$color-steps-text-default	var(--semi-white)	步骤条图标默认文本颜色
$color-steps_danger-text-active	var(--semi-color-danger-active)	错误步骤条文本颜色 - 按下态
$color-steps_danger-text-default	var(--semi-color-danger)	错误步骤条文本颜色 - 默认态
$color-steps_danger-text-hover	var(--semi-color-danger-hover)	错误步骤条文本颜色 - 悬浮态
$color-steps_icon_after-bg	var(--semi-color-fill-2)
$color-steps_item_description-text-hover	var(--semi-color-focus-border)	步骤条辅助描述文本颜色 - 悬浮态
$color-steps_item_done_after-bg	var(--semi-color-primary)	完成步骤条尾部连接线颜色
$color-steps_item_done_icon_after-bg	var(--semi-color-primary)
$color-steps_item_error_left-icon	var(--semi-color-danger)	错误步骤条图标颜色
$color-steps_item_error_left_number-icon	var(--semi-color-primary)	错误步骤条数字序号文本颜色
$color-steps_item_finish-icon	var(--semi-color-primary)	已完成步骤条图标颜色
$color-steps_item_finish_number-icon	var(--semi-color-white)	已完成步骤条对勾图标颜色
$color-steps_item_left_number_icon-bg	var(--semi-color-primary)	步骤条图标背景颜色
$color-steps_item_left_number_icon-icon	var(--semi-color-white)	步骤条图标文字颜色
$color-steps_item_process_left-icon	var(--semi-color-primary)	进行中步骤条对勾图标颜色
$color-steps_item_process_left_number-icon	var(--semi-color-white)	进行中步骤条内部图标颜色
$color-steps_item_title-text-hover	var(--semi-color-focus-border)	步骤条标题文字悬停颜色
$color-steps_item_wait_left_icon-icon	var(--semi-color-text-2)	未到达步骤条图标颜色
$color-steps_item_wait_left_number_icon-bg-hover	var(--semi-color-secondary-light-default)	未到达步骤条图标背景颜色 - 悬浮态
$color-steps_item_wait_left_number_icon-bg	var(--semi-color-fill-0)	未到达步骤条图标背景颜色
$color-steps_item_wait_left_number_icon-icon-hover	var(--semi-color-focus-border)	未到达步骤条图标颜色 - 悬浮态
$color-steps_item_wait_left_number_icon-icon	var(--semi-color-text-2)	未到达步骤条内部图标颜色
$color-steps_item_wait_title-text	var(--semi-color-text-2)	未到达步骤条标题文字颜色
$color-steps_item_warning_left-icon	var(--semi-color-warning)	警告步骤条图标颜色
$color-steps_item_warning_left_number-icon	var(--semi-color-white)	警告步骤条数字序号文本颜色
$color-steps_main-text-default	var(--semi-color-text-0)	步骤条标题文本颜色
$color-steps_minor-text-default	var(--semi-color-text-2)	步骤条辅助描述文本颜色
$color-steps_nav_item_container-text	var(--semi-color-text-2)	步骤条容器内文本颜色
$color-steps_nav_item-icon	var(--semi-grey-3)
$color-steps_nav_item_title-text-active	var(--semi-color-text-0)	步骤条标题颜色 - 按下态
$color-steps_primary-bg-default	var(--semi-color-primary)	旧版进行中步骤条背景色 - 默认
$color-steps_primary-icon-default	var(--semi-color-primary)	旧版进行中步骤条图标色 - 默认
$color-steps_process-bg-default	var(--semi-color-primary-light-default)	旧版进行中步骤条背景色 - 默认
$color-steps_success-text-active	var(--semi-color-success-active)	旧版已完成步骤条文字颜色 - 按下态
$color-steps_success-text-default	var(--semi-color-success)	旧版已完成步骤条文字颜色 - 默认态
$color-steps_success-text-hover	var(--semi-color-success-hover)	旧版已完成步骤条文字颜色 - 悬浮态
$color-steps_title_after-bg	var(--semi-color-fill-2)	旧版步骤条连线颜色
$color-steps_warning-text-active	var(--semi-color-warning-active)	旧版警告步骤条文字颜色 - 按下态
$color-steps_warning-text-default	var(--semi-color-warning)	旧版警告步骤条文字颜色 - 默认态
$color-steps_warning-text-hover	var(--semi-color-warning-hover)	旧版警告步骤条文字颜色 - 悬浮态
$width-steps_basic_item_description	100%	步骤条辅助描述文本宽度
$width-steps_basic_item_description-maxWidth	268px	步骤条辅助描述文本最大宽度
$width-steps_basic_item_title-maxWidth	80%	步骤条标题宽度
$height-steps_basic_vertical_icon_content-minHeight	42px	垂直步骤条图标+内容最小高度
$width-steps_basic_vertical_item_title-maxWidth	100%	垂直步骤条标题最大宽度
$width-steps_basic_vertical_item_description	100%	垂直步骤条辅助描述文本最大宽度
$height-steps_basic_vertical_small_item_content-minHeight	40px	小尺寸垂直步骤条内容最小高度
$height-steps_basic_item_left-icon	24px	步骤条左侧图标高度
$width-steps_basic_item_left_number-icon	24px	步骤条左侧图标宽度
$height-steps_basic_item_left_number-icon	24px	步骤条左侧图标高度
$height-steps_basic_small_item_left-icon	20px	小尺寸步骤条左侧图标高度
$width-steps_basic_small_item_left_number-icon	20px	小尺寸步骤条左侧数字图标高度
$height-steps_item	72px	旧版步骤条高度
$width-steps_item-border	1px	旧版步骤条高度
$width-steps_item_title	100%	步骤条标题宽度
$width-steps_item_description	100%	步骤条辅助描述文本宽度
$width-steps_item_left	24px	步骤条左侧图标容器宽度
$height-steps_item_left	24px	步骤条左侧图标容器高度
$width-steps_title_after	9999px	步骤条连接线长度
$height-steps_title_after	1px	步骤条连接线高度
$width-steps_vertical_icon_after	1px
$height-steps_vertical_icon_after	9999px	垂直步骤条连接线长度
$width-steps_nav_item_icon-minWidth	60px	导航型步骤条图标最小宽度
$width-steps_nav_item_title-maxWidth	17em	导航型步骤条标题最大宽度
$spacing-steps_basic_item-paddingLeft	16px	简版步骤条左侧内边距
$spacing-steps_basic_vertical_item-paddingTop	9px	简版垂直步骤条顶部内边距
$spacing-steps_basic_vertical_item_content-paddingBottom	22px	简版垂直步骤条内容区底部内边距
$spacing-steps_basic_vertical_item_icon-paddingBottom	9px	简版垂直步骤条图标底部内边距
$spacing-steps_basic_item_left-marginRight	8px	简版步骤条图标右侧外边距
$spacing-steps_basic_item_title-paddingRight	16px	简版步骤条标题右侧内边距
$spacing-steps_basic_item_title-paddingBottom	4px	简版步骤条标题底部内边距
$spacing-steps_item-marginRight	16px	旧版步骤条右侧外边距
$spacing-steps_item-paddingY	$spacing-base-tight	旧版步骤条垂直方向内边距
$spacing-steps_item-paddingX	$spacing-base	旧版步骤条水平方向内边距
$spacing-steps_item_content-marginLeft	$spacing-base	旧版步骤条水平内容区左侧外边距
$radius-steps_basic_item_left_number_icon	var(--semi-border-radius-circle)	步骤条左侧图标圆角
$radius-steps_item	var(--semi-border-radius-medium)	步骤条整体圆角
$radius-steps_item_left	32px	步骤条左侧距离
$font-steps_basic_item_left_number_icon-fontWeight	600	步骤条数字图标文本字重
$font-steps_basic_item_title-fontWeight	600	步骤条标题文本字重
$font-steps_basic_item_title-lineHeight	24px	步骤条标题文本行高
$font-steps_item_left-lineHeight	32px	步骤条标题左侧图标内部文本行高
$font-steps_nav_item_title-fontWeight	$font-weight-regular	导航型步骤条标题文本字重 - 默认态
$font-steps_nav_item_title_active-fontWeight	600	导航型步骤条标题文本字重 - 激活态