Vue Progress Header

🚀 一个高度可配置的 Vue 3 进度条头部组件，支持多种显示模式、自定义主题和响应式设计。

✨ 特性

• 🎨 完全可定制的主题 - 支持自定义颜色、字体、尺寸等
• 📱 响应式设计 - 完美适配移动端和桌面端
• 🔄 动态进度条 - 平滑的动画效果和百分比显示
• 👤 多种显示模式 - 支持关闭按钮模式和用户信息模式
• 🖼️ Logo 配置 - 灵活的 Logo 显示和点击事件
• ⚡ TypeScript 支持 - 完整的类型定义
• 🎯 丰富的事件 - 支持多种交互事件
• 🎛️ 灵活布局 - 支持 fixed、sticky、relative 定位

📦 安装

npm install vue-progress-header

🚀 快速开始

基本使用

<template>
  <ConfigurableProgressHeader
    title="创建新项目"
    mode="close-button"
    :progress="{
      totalSteps: 5,
      currentStep: 2,
    }"
    :logo="{
      src: '/logo.png',
      alt: 'Logo',
    }"
    @close="handleClose"
  />
</template>

<script setup>
import { ConfigurableProgressHeader } from "vue-progress-header";

const handleClose = () => {
  console.log("关闭");
};
</script>

用户信息模式

<template>
  <ConfigurableProgressHeader
    title="个人设置"
    mode="user-info"
    :progress="{
      totalSteps: 3,
      currentStep: 1,
    }"
    :userInfo="{
      email: '[email protected]',
      avatarUrl: '/avatar.jpg',
    }"
    @avatar-click="handleAvatarClick"
  />
</template>

📚 API 文档

Props

必需属性

| 属性 | 类型 | 描述 | | ---------- | ---------------- | ---------- | | title | string | 页面标题 | | progress | ProgressConfig | 进度条配置 |

可选属性

| 属性 | 类型 | 默认值 | 描述 | | ------------- | ------------------------------- | ---------------- | ---------------- | | mode | 'close-button' \| 'user-info' | 'close-button' | 显示模式 | | logo | LogoConfig | undefined | Logo 配置 | | userInfo | UserInfoConfig | undefined | 用户信息配置 | | closeButton | CloseButtonConfig | undefined | 关闭按钮配置 | | theme | Partial<ProgressHeaderTheme> | undefined | 主题配置 | | layout | LayoutConfig | undefined | 布局配置 | | className | string | undefined | 自定义类名 | | style | Record<string, any> | undefined | 自定义样式 | | closeRoute | string | undefined | 关闭时跳转的路由 |

类型定义

ProgressConfig

interface ProgressConfig {
  totalSteps: number; // 总步数
  currentStep?: number; // 当前步数，默认 1
  height?: string; // 进度条高度，默认 '4px'
  showPercentage?: boolean; // 是否显示百分比，默认 false
  animationDuration?: string; // 动画持续时间，默认 '0.3s'
}

LogoConfig

interface LogoConfig {
  src: string; // Logo 图片地址
  alt?: string; // 图片 alt 属性
  width?: string; // Logo 宽度
  height?: string; // Logo 高度
  objectFit?: "contain" | "cover" | "fill" | "scale-down" | "none";
}

UserInfoConfig

interface UserInfoConfig {
  email?: string; // 用户邮箱
  avatarUrl?: string; // 头像地址
  avatarAlt?: string; // 头像 alt 属性
  showEmail?: boolean; // 是否显示邮箱，默认 true
  maxEmailWidth?: string; // 邮箱最大宽度，默认 '200px'
}

CloseButtonConfig

interface CloseButtonConfig {
  size?: "small" | "medium" | "large"; // 按钮尺寸，默认 'medium'
  showBackground?: boolean; // 是否显示背景，默认 true
  customIcon?: string; // 自定义图标 SVG
}

ProgressHeaderTheme

interface ProgressHeaderTheme {
  primaryColor: string; // 主色调
  backgroundColor: string; // 背景色
  textColor: string; // 文字颜色
  secondaryTextColor: string; // 次要文字颜色
  dividerColor: string; // 分割线颜色
  progressColor: string; // 进度条颜色
  progressBackgroundColor: string; // 进度条背景色
  boxShadow: string; // 阴影
}

LayoutConfig

interface LayoutConfig {
  height?: string; // 头部高度，默认 '64px'
  padding?: string; // 桌面端内边距，默认 '16px 40px'
  mobilePadding?: string; // 移动端内边距，默认 '12px 16px'
  showDivider?: boolean; // 是否显示分割线，默认 true
  position?: "fixed" | "sticky" | "relative"; // 定位方式，默认 'fixed'
  zIndex?: number; // z-index 值，默认 1000
}

事件

| 事件名 | 描述 | 回调参数 | | -------------- | ------------------ | -------- | | close | 关闭按钮点击时触发 | () | | avatar-click | 头像点击时触发 | () | | logo-click | Logo 点击时触发 | () | | title-click | 标题点击时触发 | () |

🎨 主题定制

默认主题

const defaultTheme = {
  primaryColor: "#FB920C",
  backgroundColor: "#ffffff",
  textColor: "rgb(20, 23, 26)",
  secondaryTextColor: "rgb(107, 114, 126)",
  dividerColor: "rgb(232, 234, 237)",
  progressColor: "#FB920C",
  progressBackgroundColor: "rgb(245, 246, 247)",
  boxShadow: "0 2px 8px rgba(0, 0, 0, 0.1)",
};

自定义主题

<ConfigurableProgressHeader
  title="自定义主题"
  :progress="{ totalSteps: 5, currentStep: 3 }"
  :theme="{
    primaryColor: '#3B82F6',
    backgroundColor: '#1F2937',
    textColor: '#F9FAFB',
    progressColor: '#10B981',
  }"
/>

📖 更多示例

固定定位头部

<ConfigurableProgressHeader
  title="固定头部"
  :progress="{ totalSteps: 4, currentStep: 2 }"
  :layout="{
    position: 'fixed',
    zIndex: 9999,
  }"
/>

自定义进度条

<ConfigurableProgressHeader
  title="自定义进度条"
  :progress="{
    totalSteps: 10,
    currentStep: 7,
    height: '8px',
    showPercentage: true,
    animationDuration: '0.5s',
  }"
/>

大尺寸关闭按钮

<ConfigurableProgressHeader
  title="大按钮"
  :closeButton="{
    size: 'large',
    showBackground: true,
  }"
/>

🛠️ 开发

# 克隆项目
git clone https://github.com/skillharbor/vue-progress-header.git

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build:lib

# 类型检查
npm run type-check

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🔗 链接

• GitHub
• npm

Made with ❤️ by SkillHarbor