Loongship UI

Appearance

Stepper 步骤器 ​

展示流程进度并切换步骤。

命令行安装 ​

bash
npx @loongship-kit/ui add stepper

组件结构 ​

角色组件职责使用条件
根组件Stepper管理当前步骤和导航规则必需
步骤容器StepperItem声明单个步骤及其状态必需
交互与标记StepperTrigger、StepperIndicator切换步骤并展示步骤标记触发器必需
连接组件StepperSeparator展示相邻步骤之间的连接线按需
语义内容StepperTitle、StepperDescription提供步骤标题和辅助说明标题建议，描述按需

基础用法 ​

Step 1 of 0
查看代码
vue
<template>
  <Stepper :default-value="1">
    <StepperItem :step="1">
      <StepperTrigger>
        <StepperIndicator />
        <StepperTitle>创建任务</StepperTitle>
        <StepperDescription>填写基础信息</StepperDescription>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
    <StepperItem :step="2">
      <StepperTrigger>
        <StepperIndicator />
        <StepperTitle>配置规则</StepperTitle>
        <StepperDescription>设置执行条件</StepperDescription>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
    <StepperItem :step="3">
      <StepperTrigger>
        <StepperIndicator />
        <StepperTitle>完成</StepperTitle>
        <StepperDescription>确认并提交</StepperDescription>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
  </Stepper>
</template>

自定义步骤图标 ​

StepperIndicator 的默认插槽可替换步骤数字。使用 Loongship Icon 时同时安装 stepper 和 icon。

Step 3 of 0
查看代码
vue
<script setup lang="ts">
import { Icon } from '@/components/loongship/icon'
import {
  Stepper,
  StepperIndicator,
  StepperItem,
  StepperSeparator,
  StepperTitle,
  StepperTrigger
} from '@/components/loongship/stepper'
</script>

<template>
  <Stepper :default-value="3">
    <StepperItem :step="1">
      <StepperTrigger>
        <StepperIndicator><Icon name="document" size="md" /></StepperIndicator>
        <StepperTitle>提交资料</StepperTitle>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
    <StepperItem :step="2">
      <StepperTrigger>
        <StepperIndicator><Icon name="shipping-truck" size="md" /></StepperIndicator>
        <StepperTitle>运输中</StepperTitle>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
    <StepperItem :step="3">
      <StepperTrigger>
        <StepperIndicator><Icon name="file-done" size="md" /></StepperIndicator>
        <StepperTitle>已完成</StepperTitle>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
  </Stepper>
</template>

受控状态 ​

Step 2 of 0
当前步骤：2
查看代码
vue
<script setup lang="ts">
import { ref } from 'vue'

const currentStep = ref(2)
</script>

<template>
  <div class="vp-demo-showcase-column">
    <Stepper v-model="currentStep">
      <StepperItem v-for="step in 3" :key="step" :step="step">
        <StepperTrigger>
          <StepperIndicator />
          <StepperTitle>步骤 {{ step }}</StepperTitle>
        </StepperTrigger>
        <StepperSeparator />
      </StepperItem>
    </Stepper>
    <span>当前步骤：{{ currentStep }}</span>
  </div>
</template>

纵向与非线性流程 ​

Step 1 of 0
查看代码
vue
<template>
  <Stepper v-model="verticalStep" orientation="vertical" :linear="false">
    <StepperItem :step="1">
      <StepperTrigger>
        <StepperIndicator />
        <StepperTitle>申请已提交</StepperTitle>
        <StepperDescription>可以自由返回此步骤</StepperDescription>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
    <StepperItem :step="2">
      <StepperTrigger>
        <StepperIndicator />
        <StepperTitle>资料审核</StepperTitle>
        <StepperDescription>非线性模式允许直接跳转</StepperDescription>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
    <StepperItem :step="3" disabled>
      <StepperTrigger>
        <StepperIndicator />
        <StepperTitle>人工复核</StepperTitle>
        <StepperDescription>此步骤当前不可用</StepperDescription>
      </StepperTrigger>
      <StepperSeparator />
    </StepperItem>
  </Stepper>
</template>

线性模式与键盘操作

线性模式是默认行为，只允许返回已完成步骤或进入紧邻的下一步。设置 :linear="false" 后可以直接访问任意未禁用步骤。横向模式使用左右方向键，纵向模式使用上下方向键；Enter 或 Space 激活聚焦步骤。

内容由业务层渲染

步骤器只管理步骤状态。根据 v-model 在业务层渲染对应的表单或内容面板。

API ​

Stepper（主组件） ​

属性 ​

属性类型默认值说明
v-modelnumber-当前步骤编号
defaultValuenumber1非受控模式的初始步骤
orientation'horizontal' | 'vertical''horizontal'排列方向和方向键导航方式
linearbooleantrue是否要求按顺序完成步骤
dir'ltr' | 'rtl''ltr'阅读方向
asstring | Component'div'渲染元素
asChildbooleanfalse合并到唯一子元素
classClassValue-自定义类名

事件 ​

事件参数说明
update:modelValuevalue: number | undefined当前步骤改变时触发

插槽 ​

插槽参数说明
default{ modelValue, totalSteps, goToStep, nextStep, prevStep, hasNext, hasPrev, isNextDisabled, isPrevDisabled, isFirstStep, isLastStep }步骤列表和流程控制内容

子组件 ​

StepperItem — 单个步骤容器

属性 ​

属性类型默认值说明
stepnumber-步骤编号，必填
disabledbooleanfalse是否禁止访问
completedbooleanfalse是否显式标记为已完成
asstring | Component'div'渲染元素
asChildbooleanfalse合并到唯一子元素
classClassValue-自定义类名

插槽 ​

插槽参数说明
default{ state: 'inactive' | 'active' | 'completed' }当前步骤状态内容
StepperTrigger — 步骤交互入口

属性 ​

属性类型默认值说明
asstring | Component'button'渲染元素
asChildbooleanfalse合并到唯一子元素
classClassValue-自定义类名

插槽 ​

插槽参数说明
default—步骤标记、标题和说明
StepperIndicator — 步骤编号或状态图标

属性 ​

属性类型默认值说明
asstring | Component'div'渲染元素
asChildbooleanfalse合并到唯一子元素
classClassValue-自定义类名

插槽 ​

插槽参数说明
default{ step: number }替换步骤数字或渲染完成图标
StepperSeparator — 步骤连接线

属性 ​

属性类型默认值说明
asstring | Component'div'渲染元素
asChildbooleanfalse合并到唯一子元素
classClassValue-自定义类名

插槽 ​

插槽参数说明
default—自定义连接线内容
StepperTitle / StepperDescription — 步骤标题与说明

属性 ​

组件属性类型默认值说明
StepperTitleasstring | Component'h4'渲染元素
StepperTitleasChildbooleanfalse合并到唯一子元素
StepperTitleclassClassValue-自定义类名
StepperDescriptionasstring | Component'p'渲染元素
StepperDescriptionasChildbooleanfalse合并到唯一子元素
StepperDescriptionclassClassValue-自定义类名

插槽 ​

组件插槽参数说明
StepperTitledefault—步骤标题
StepperDescriptiondefault—步骤辅助说明