ChuFix UI v0.11.0
开发预览 更新于 2026-05-10

Stepper 步骤指示

多步流程进度条，支持横竖两种方向、3 种 variant、可点击切换。

基础用法

items 数组每项至少有 title，current 是当前步骤的索引（从 0 起）。索引小于 current 的自动标 done，等于的标 current，大于的标 pending。

背景 视口
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfStepper, CfButton, type StepItem } from '@chufix-design/vue';

const current = ref(1);
const items: StepItem[] = [
  { title: '填写信息', description: '账号 / 邮箱 / 密码' },
  { title: '验证邮箱', description: '收到的邮件中点击链接' },
  { title: '完成', description: '即可开始使用' },
];
</script>
<template>
  <div style="display:flex; flex-direction:column; gap: 16px;">
    <CfStepper :items="items" :current="current" />
    <div style="display:inline-flex; gap: 8px;">
      <CfButton
        size="sm"
        variant="tertiary"
        :disabled="current === 0"
        @click="current = Math.max(0, current - 1)"
      >上一步</CfButton>
      <CfButton
        size="sm"
        variant="primary"
        :disabled="current === items.length - 1"
        @click="current = Math.min(items.length - 1, current + 1)"
      >下一步</CfButton>
    </div>
  </div>
</template>
<script setup>
import { ref } from 'vue';
import { CfStepper, CfButton } from '@chufix-design/vue';

const current = ref(1);
const items= [
  { title: '填写信息', description: '账号 / 邮箱 / 密码' },
  { title: '验证邮箱', description: '收到的邮件中点击链接' },
  { title: '完成', description: '即可开始使用' },
];
</script>
<template>
  <div style="display:flex; flex-direction:column; gap: 16px;">
    <CfStepper :items="items" :current="current" />
    <div style="display:inline-flex; gap: 8px;">
      <CfButton
        size="sm"
        variant="tertiary"
        :disabled="current === 0"
        @click="current = Math.max(0, current - 1)"
      >上一步</CfButton>
      <CfButton
        size="sm"
        variant="primary"
        :disabled="current === items.length - 1"
        @click="current = Math.min(items.length - 1, current + 1)"
      >下一步</CfButton>
    </div>
  </div>
</template>
import { useState } from 'react';
import { CfStepper, type StepItem } from '@chufix-design/react';

const items: StepItem[] = [
{ title: '填写信息', description: '账号 / 邮箱 / 密码' },
{ title: '验证邮箱', description: '收到的邮件中点击链接' },
{ title: '完成', description: '即可开始使用' },
];

export default function Demo() {
const [current, setCurrent] = useState(1);
return <CfStepper items={items} current={current} />;
}
import { useState } from 'react';
import { CfStepper } from '@chufix-design/react';

const items= [
{ title: '填写信息', description: '账号 / 邮箱 / 密码' },
{ title: '验证邮箱', description: '收到的邮件中点击链接' },
{ title: '完成', description: '即可开始使用' },
];

export default function Demo() {
const [current, setCurrent] = useState(1);
return <CfStepper items={items} current={current} />;
}

三种 variant

numbered（默认）显示步骤号；dots 极简圆点；minimal 透明描边。

背景 视口
src/App.vue 
<script setup lang="ts">
import { CfStepper, type StepItem } from '@chufix-design/vue';

const items: StepItem[] = [
  { title: '设计' },
  { title: '开发' },
  { title: '测试' },
  { title: '上线' },
];
</script>
<template>
  <div style="display:flex; flex-direction:column; gap: 24px;">
    <CfStepper :items="items" :current="2" variant="numbered" />
    <CfStepper :items="items" :current="2" variant="dots" />
    <CfStepper :items="items" :current="2" variant="minimal" />
  </div>
</template>
<script setup>
import { CfStepper } from '@chufix-design/vue';

const items= [
  { title: '设计' },
  { title: '开发' },
  { title: '测试' },
  { title: '上线' },
];
</script>
<template>
  <div style="display:flex; flex-direction:column; gap: 24px;">
    <CfStepper :items="items" :current="2" variant="numbered" />
    <CfStepper :items="items" :current="2" variant="dots" />
    <CfStepper :items="items" :current="2" variant="minimal" />
  </div>
</template>
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  const items: StepItem[] = [
    { title: '设计' },
    { title: '开发' },
    { title: '测试' },
    { title: '上线' },
  ];
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
          <CfStepper items={items} current={2} variant="numbered" />
          <CfStepper items={items} current={2} variant="dots" />
          <CfStepper items={items} current={2} variant="minimal" />
        </div>
    </>
  );
}
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  const items= [
    { title: '设计' },
    { title: '开发' },
    { title: '测试' },
    { title: '上线' },
  ];
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
          <CfStepper items={items} current={2} variant="numbered" />
          <CfStepper items={items} current={2} variant="dots" />
          <CfStepper items={items} current={2} variant="minimal" />
        </div>
    </>
  );
}

竖向 + 显式状态

orientation="vertical" 把步骤竖排展开。每一项可以单独指定 status: 'done' | 'current' | 'pending' | 'error'，会覆盖 current 自动推断的结果。

背景 视口
src/App.vue 
<script setup lang="ts">
import { CfStepper, type StepItem } from '@chufix-design/vue';

const items: StepItem[] = [
  { title: '提交申请', description: '已于 2026-05-01 提交', status: 'done' },
  { title: '审核中', description: '客户经理预计 2 天内回复', status: 'current' },
  { title: '签订合同', description: '电子签或邮寄都可' },
  { title: '账户激活', status: 'error' },
];
</script>
<template>
  <CfStepper :items="items" orientation="vertical" />
</template>
<script setup>
import { CfStepper } from '@chufix-design/vue';

const items= [
  { title: '提交申请', description: '已于 2026-05-01 提交', status: 'done' },
  { title: '审核中', description: '客户经理预计 2 天内回复', status: 'current' },
  { title: '签订合同', description: '电子签或邮寄都可' },
  { title: '账户激活', status: 'error' },
];
</script>
<template>
  <CfStepper :items="items" orientation="vertical" />
</template>
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  return (
    <>
      <CfStepper
      orientation="vertical"
      items={[
        { title: '提交申请', description: '已于 2026-05-01 提交', status: 'done' },
        { title: '审核中', description: '客户经理预计 2 天内回复', status: 'current' },
        { title: '签订合同' },
        { title: '账户激活', status: 'error' },
      ]}
      />
    </>
  );
}
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  return (
    <>
      <CfStepper
      orientation="vertical"
      items={[
        { title: '提交申请', description: '已于 2026-05-01 提交', status: 'done' },
        { title: '审核中', description: '客户经理预计 2 天内回复', status: 'current' },
        { title: '签订合同' },
        { title: '账户激活', status: 'error' },
      ]}
      />
    </>
  );
}

三档尺寸

size 控制节点直径、字号与间距。sm 紧凑（适合多步流程的顶部进度条）/ md 默认 / lg 适合需要强调的关键流程。

背景 视口
sm
md (默认)
lg
src/App.vue 
<script setup lang="ts">
import { CfStepper, type StepItem } from '@chufix-design/vue';

const items: StepItem[] = [
  { title: '提交' },
  { title: '审核' },
  { title: '完成' },
];
</script>
<template>
  <div class="demo-stack">
    <div>
      <span class="adm-tag">sm</span>
      <CfStepper :items="items" :current="1" size="sm" />
    </div>
    <div>
      <span class="adm-tag">md (默认)</span>
      <CfStepper :items="items" :current="1" size="md" />
    </div>
    <div>
      <span class="adm-tag">lg</span>
      <CfStepper :items="items" :current="1" size="lg" />
    </div>
  </div>
</template>
<style scoped>
.demo-stack { display: flex; flex-direction: column; gap: 20px; }
.adm-tag {
  display: inline-block;
  font-family: var(--font-mono);
  font-size: var(--t-12);
  color: var(--fg-3);
  margin-bottom: 6px;
}
</style>
<script setup>
import { CfStepper } from '@chufix-design/vue';

const items= [
  { title: '提交' },
  { title: '审核' },
  { title: '完成' },
];
</script>
<template>
  <div class="demo-stack">
    <div>
      <span class="adm-tag">sm</span>
      <CfStepper :items="items" :current="1" size="sm" />
    </div>
    <div>
      <span class="adm-tag">md (默认)</span>
      <CfStepper :items="items" :current="1" size="md" />
    </div>
    <div>
      <span class="adm-tag">lg</span>
      <CfStepper :items="items" :current="1" size="lg" />
    </div>
  </div>
</template>
<style scoped>
.demo-stack { display: flex; flex-direction: column; gap: 20px; }
.adm-tag {
  display: inline-block;
  font-family: var(--font-mono);
  font-size: var(--t-12);
  color: var(--fg-3);
  margin-bottom: 6px;
}
</style>
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  const items: StepItem[] = [
    { title: '提交' },
    { title: '审核' },
    { title: '完成' },
  ];
  return (
    <>
      <div className="demo-stack">
          <div>
            <span className="adm-tag">sm</span>
            <CfStepper items={items} current={1} size="sm" />
          </div>
          <div>
            <span className="adm-tag">md (默认)</span>
            <CfStepper items={items} current={1} size="md" />
          </div>
          <div>
            <span className="adm-tag">lg</span>
            <CfStepper items={items} current={1} size="lg" />
          </div>
        </div>
    </>
  );
}
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  const items= [
    { title: '提交' },
    { title: '审核' },
    { title: '完成' },
  ];
  return (
    <>
      <div className="demo-stack">
          <div>
            <span className="adm-tag">sm</span>
            <CfStepper items={items} current={1} size="sm" />
          </div>
          <div>
            <span className="adm-tag">md (默认)</span>
            <CfStepper items={items} current={1} size="md" />
          </div>
          <div>
            <span className="adm-tag">lg</span>
            <CfStepper items={items} current={1} size="lg" />
          </div>
        </div>
    </>
  );
}

可点击切换

clickable 让每一步都变成可点击按钮，配合 @change (Vue) / onChange (React) 接收点击的索引和原始 item，自行更新 current。被禁用（item.disabled）的项依然无法点击。

背景 视口

当前 current = 1 —— 直接点击任意步骤切换
src/App.vue 
<script setup lang="ts">
import { ref } from 'vue';
import { CfStepper, type StepItem } from '@chufix-design/vue';

const current = ref<number>(1);
const items: StepItem[] = [
  { title: '填写信息', description: '账号 / 邮箱' },
  { title: '验证邮箱', description: '收到的链接' },
  { title: '完成', description: '开始使用' },
];

function handleChange(index: number, item: StepItem) {
  current.value = index;
  console.log('change →', index, item.title);
}
</script>
<template>
  <CfStepper
    :items="items"
    :current="current"
    clickable
    @change="handleChange"
  />
  <p class="adm-hint">当前 current = {{ current }} —— 直接点击任意步骤切换</p>
</template>
<style scoped>
.adm-hint { color: var(--fg-3); font-size: var(--t-12); margin-top: 8px; }
</style>
<script setup>
import { ref } from 'vue';
import { CfStepper } from '@chufix-design/vue';

const current = ref<number>(1);
const items= [
  { title: '填写信息', description: '账号 / 邮箱' },
  { title: '验证邮箱', description: '收到的链接' },
  { title: '完成', description: '开始使用' },
];

function handleChange(index, item) {
  current.value = index;
  console.log('change →', index, item.title);
}
</script>
<template>
  <CfStepper
    :items="items"
    :current="current"
    clickable
    @change="handleChange"
  />
  <p class="adm-hint">当前 current = {{ current }} —— 直接点击任意步骤切换</p>
</template>
<style scoped>
.adm-hint { color: var(--fg-3); font-size: var(--t-12); margin-top: 8px; }
</style>
import { useState } from 'react';
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  const [current, setCurrent] = useState<number>(1);
  const items: StepItem[] = [
    { title: '填写信息', description: '账号 / 邮箱' },
    { title: '验证邮箱', description: '收到的链接' },
    { title: '完成', description: '开始使用' },
  ];

  function handleChange(index: number, item: StepItem) {
    setCurrent(index);
    console.log('change →', index, item.title);
  }
  return (
    <>
      <CfStepper items={items} current={current} clickable onChange={handleChange} />
        <p className="adm-hint">当前 current = {current} —— 直接点击任意步骤切换</p>
    </>
  );
}
import { useState } from 'react';
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  const [current, setCurrent] = useState<number>(1);
  const items= [
    { title: '填写信息', description: '账号 / 邮箱' },
    { title: '验证邮箱', description: '收到的链接' },
    { title: '完成', description: '开始使用' },
  ];

  function handleChange(index, item) {
    setCurrent(index);
    console.log('change →', index, item.title);
  }
  return (
    <>
      <CfStepper items={items} current={current} clickable onChange={handleChange} />
        <p className="adm-hint">当前 current = {current} —— 直接点击任意步骤切换</p>
    </>
  );
}

error 状态

某步骤显式置 status: 'error' —— 节点会渲染 × 图标并应用红色 tone，后续步骤保持 pending。常用于校验失败或异步任务报错的可视化。

背景 视口

某一步出错时设 status: 'error'，节点显示 × 图标且强调红色， 后续步骤保持 pending（不会自动推进）。

src/App.vue 
<script setup lang="ts">
import { CfStepper, type StepItem } from '@chufix-design/vue';

const items: StepItem[] = [
  { title: '上传文件', description: '已完成', status: 'done' },
  { title: '解析', description: '识别失败 —— 文件格式错误', status: 'error' },
  { title: '导入', description: '等待中' },
];
</script>
<template>
  <CfStepper :items="items" />
  <p class="adm-hint">
    某一步出错时设 <code>status: 'error'</code>，节点显示 × 图标且强调红色，
    后续步骤保持 pending（不会自动推进）。
  </p>
</template>
<style scoped>
.adm-hint { color: var(--fg-3); font-size: var(--t-12); margin-top: 12px; line-height: 1.6; }
code { font-family: var(--font-mono); color: var(--fg-2); }
</style>
<script setup>
import { CfStepper } from '@chufix-design/vue';

const items= [
  { title: '上传文件', description: '已完成', status: 'done' },
  { title: '解析', description: '识别失败 —— 文件格式错误', status: 'error' },
  { title: '导入', description: '等待中' },
];
</script>
<template>
  <CfStepper :items="items" />
  <p class="adm-hint">
    某一步出错时设 <code>status: 'error'</code>，节点显示 × 图标且强调红色，
    后续步骤保持 pending（不会自动推进）。
  </p>
</template>
<style scoped>
.adm-hint { color: var(--fg-3); font-size: var(--t-12); margin-top: 12px; line-height: 1.6; }
code { font-family: var(--font-mono); color: var(--fg-2); }
</style>
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  return (
    <>
      <CfStepper items={[
      { title: '上传文件', description: '已完成', status: 'done' },
      { title: '解析',     description: '识别失败',  status: 'error' },
      { title: '导入',     description: '等待中' },
      ]} />
    </>
  );
}
import { CfStepper } from '@chufix-design/react';

export default function Demo() {
  return (
    <>
      <CfStepper items={[
      { title: '上传文件', description: '已完成', status: 'done' },
      { title: '解析',     description: '识别失败',  status: 'error' },
      { title: '导入',     description: '等待中' },
      ]} />
    </>
  );
}

API

属性类型默认值说明
itemsStepItem[][]步骤数组
currentnumber0当前步骤索引（0 起）
variant'numbered' | 'dots' | 'minimal''numbered'视觉模式
orientation'horizontal' | 'vertical''horizontal'排列方向
size'sm' | 'md' | 'lg''md'尺寸
clickablebooleanfalse步骤是否可点击切换；与 change 事件配合使用

StepItem：{ key?, title, description?, status?, disabled? }。 事件：change(index, item)（React 端：onChange）。

反馈与讨论

Stepper 步骤指示 的讨论

0
0 / 600
正在加载评论...