awesome-progress-bars

v1.0.0

Published

a year ago

一个包含120种不同样式进度条的现代化npm库

Downloads

🎯 Awesome Progress Bars

一个包含120种不同样式进度条的现代化npm库，使用TypeScript构建，支持多种框架。

✨ 特性

🎨 120种精美样式 - 从基础到创意，应有尽有
📱 响应式设计 - 完美适配各种设备
🎭 主题系统 - 内置10+主题，支持自定义
⚡ 高性能 - 使用CSS3动画，流畅丝滑
🔧 易于使用 - 简单的API，丰富的配置选项
🌐 框架无关 - 支持React、Vue、Angular或原生JS
📦 零依赖 - 不依赖任何第三方库
♿ 无障碍支持 - 遵循WCAG指南
🎪 动画效果 - 多种缓动函数和动画选项

📦 安装

npm install awesome-progress-bars

或使用yarn：

yarn add awesome-progress-bars

🚀 快速开始

基础用法

import createProgressBar, { ProgressBarStyle } from 'awesome-progress-bars';

// 创建基础进度条
const progressBar = createProgressBar('#container', {
  value: 50,
  style: ProgressBarStyle.BASIC,
  theme: 'blue'
});

// 更新进度
progressBar.setValue(75);

// 动画到指定值
progressBar.animate(100, 2000);

HTML

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="node_modules/awesome-progress-bars/dist/styles.css">
</head>
<body>
  <div id="my-progress"></div>
  
  <script type="module">
    import createProgressBar from './node_modules/awesome-progress-bars/dist/index.esm.js';
    
    const progress = createProgressBar('#my-progress', {
      value: 60,
      style: 'gradient',
      showLabel: true
    });
  </script>
</body>
</html>

🎨 样式类型

线性进度条 (20种)

basic - 基础进度条
gradient - 渐变进度条
striped - 条纹进度条
segmented - 分段进度条
labeled - 带标签进度条
rainbow - 彩虹进度条
pulse - 脉冲效果
glow - 发光效果
3d - 3D效果
wave - 波浪效果
liquid - 液体效果
pixel - 像素风格
glassmorphism - 玻璃拟态
minimal - 极简风格
更多...

圆形进度条 (25种)

circular - 基础圆形
circular-neon - 霓虹圆形
circular-dashboard - 仪表盘样式
circular-pie - 饼图样式
circular-pulse - 脉冲圆形
dna-helix - DNA螺旋
gear - 齿轮效果
heartbeat - 心跳效果
更多...

创意进度条 (50种)

bouncing-ball - 弹跳球
loading-dots - 加载点
matrix - 矩阵效果
particle - 粒子效果
neural-network - 神经网络
aurora - 极光效果
constellation - 星座
wormhole - 虫洞
更多...

主题化进度条 (25种)

solar-system - 太阳系
steam-train - 蒸汽火车
rainbow-waterfall - 彩虹瀑布
electron-microscope - 电子显微镜
ancient-drum - 古代战鼓
laser-engraving - 激光雕刻
hummingbird-wings - 蜂鸟振翅
game-health - 游戏血条
game-mana - 游戏魔法条
music-equalizer - 音乐均衡器
更多...

🛠️ API 参考

ProgressBar类

class ProgressBar {
  constructor(container: HTMLElement | string, options: ProgressBarOptions)
  
  setValue(value: number): void
  getValue(): number
  setTheme(theme: string): void
  animate(targetValue: number, duration?: number): Promise<void>
  increment(amount?: number): void
  decrement(amount?: number): void
  reset(): void
  complete(): void
  updateOptions(options: Partial<ProgressBarOptions>): void
  destroy(): void
  getElement(): HTMLElement
  getInfo(): ProgressBarInfo
}

配置选项

interface ProgressBarOptions {
  value: number;                    // 进度值 (0-100)
  style: ProgressBarStyle;          // 样式类型
  theme?: string;                   // 主题名称
  size?: 'small' | 'medium' | 'large' | 'custom';
  customSize?: {
    width?: string;
    height?: string;
  };
  showLabel?: boolean;              // 显示标签
  labelPosition?: 'inside' | 'outside' | 'top' | 'bottom';
  animated?: boolean;               // 启用动画
  animationSpeed?: 'slow' | 'normal' | 'fast';
  striped?: boolean;                // 条纹效果
  className?: string;               // 自定义CSS类
  customColors?: {
    primary?: string;
    secondary?: string;
    background?: string;
    text?: string;
  };
  onComplete?: () => void;          // 完成回调
  onChange?: (value: number) => void; // 变化回调
}

🎭 主题系统

内置主题

import { getAvailableThemes, setTheme } from 'awesome-progress-bars';

// 获取所有可用主题
const themes = getAvailableThemes();
console.log(themes); // ['default', 'dark', 'blue', 'green', ...]

// 应用主题
progressBar.setTheme('dark');

自定义主题

import { registerTheme } from 'awesome-progress-bars';

// 注册自定义主题
registerTheme('myTheme', {
  name: 'My Custom Theme',
  colors: {
    primary: '#ff6b6b',
    secondary: '#ffeaa7',
    background: '#ddd',
    text: '#2d3436',
    accent: '#fd79a8'
  },
  animations: {
    duration: '400ms',
    easing: 'cubic-bezier(0.4, 0, 0.2, 1)'
  }
});

🎪 预设进度条

import { progressBarPresets } from 'awesome-progress-bars';

// 使用预设快速创建
const healthBar = progressBarPresets.gameHealth('#health', 85);
const loadingBar = progressBarPresets.gradient('#loading', 0);
const circularProgress = progressBarPresets.circular('#circle', 60);

📱 框架集成

React

import React, { useEffect, useRef } from 'react';
import createProgressBar from 'awesome-progress-bars';

function ProgressComponent({ value, style }) {
  const containerRef = useRef(null);
  const progressRef = useRef(null);

  useEffect(() => {
    if (containerRef.current && !progressRef.current) {
      progressRef.current = createProgressBar(containerRef.current, {
        value: 0,
        style,
        animated: true
      });
    }
  }, [style]);

  useEffect(() => {
    if (progressRef.current) {
      progressRef.current.animate(value, 500);
    }
  }, [value]);

  return <div ref={containerRef} />;
}

Vue

<template>
  <div ref="progressContainer"></div>
</template>

<script>
import createProgressBar from 'awesome-progress-bars';

export default {
  props: ['value', 'style'],
  mounted() {
    this.progressBar = createProgressBar(this.$refs.progressContainer, {
      value: this.value,
      style: this.style
    });
  },
  watch: {
    value(newValue) {
      this.progressBar.animate(newValue, 300);
    }
  },
  beforeDestroy() {
    if (this.progressBar) {
      this.progressBar.destroy();
    }
  }
}
</script>

Angular

import { Component, ElementRef, Input, OnInit, OnDestroy } from '@angular/core';
import createProgressBar, { ProgressBar } from 'awesome-progress-bars';

@Component({
  selector: 'app-progress-bar',
  template: '<div #container></div>'
})
export class ProgressBarComponent implements OnInit, OnDestroy {
  @Input() value: number = 0;
  @Input() style: string = 'basic';
  
  private progressBar: ProgressBar;

  constructor(private elementRef: ElementRef) {}

  ngOnInit() {
    this.progressBar = createProgressBar(this.elementRef.nativeElement, {
      value: this.value,
      style: this.style
    });
  }

  ngOnChanges() {
    if (this.progressBar) {
      this.progressBar.animate(this.value, 300);
    }
  }

  ngOnDestroy() {
    if (this.progressBar) {
      this.progressBar.destroy();
    }
  }
}

🎮 高级用法

进度条管理器

import { ProgressBarManager } from 'awesome-progress-bars';

const manager = new ProgressBarManager({
  defaultTheme: 'dark',
  globalAnimationSpeed: 'fast'
});

// 创建多个进度条
manager.create('loading', '#loading-container', { style: 'gradient' });
manager.create('upload', '#upload-container', { style: 'segmented' });

// 批量更新
manager.updateAll({ theme: 'blue' });
manager.setAllValues(50);

// 获取状态
const status = manager.getAllStatus();
console.log(status);

自定义动画

import { easingFunctions } from 'awesome-progress-bars';

// 使用内置缓动函数
progressBar.animate(80, 1000, easingFunctions.easeOutBounce);

// 自定义缓动
const customEasing = (t) => t * t * (3 - 2 * t); // smoothstep
progressBar.animate(90, 1500, customEasing);

事件处理

const progressBar = createProgressBar('#container', {
  value: 0,
  onComplete: () => {
    console.log('进度完成！');
    // 播放完成音效
    playSound('complete.mp3');
  },
  onChange: (value) => {
    console.log(`进度更新: ${value}%`);
    // 更新其他UI元素
    updateStatusText(`正在处理... ${value}%`);
  }
});

🎨 CSS 自定义

CSS 变量

:root {
  --progress-primary: #3b82f6;
  --progress-secondary: #e5e7eb;
  --progress-background: #f3f4f6;
  --progress-text: #1f2937;
  --progress-accent: #60a5fa;
  --progress-duration: 300ms;
  --progress-easing: ease-out;
}

自定义样式

.my-custom-progress {
  --progress-primary: linear-gradient(45deg, #ff6b6b, #feca57);
  --progress-height: 20px;
  --progress-radius: 10px;
}

.my-custom-progress .progress-fill {
  box-shadow: 0 0 20px rgba(255, 107, 107, 0.5);
  animation: customGlow 2s ease-in-out infinite;
}

@keyframes customGlow {
  0%, 100% { filter: brightness(1); }
  50% { filter: brightness(1.2); }
}

🌐 浏览器支持

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+
iOS Safari 12+
Android Chrome 60+

📊 性能

📦 Bundle大小: ~15KB (gzipped)
⚡ 首次渲染: <10ms
🔄 动画帧率: 60 FPS
💾 内存占用: <5MB
🚀 零阻塞: 使用CSS3动画

🤝 贡献

我们欢迎所有形式的贡献！请查看贡献指南了解详情。

开发设置

# 克隆仓库
git clone https://github.com/username/awesome-progress-bars.git
cd awesome-progress-bars

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 运行测试
npm test

# 构建项目
npm run build

📄 许可证

🙏 致谢

感谢所有贡献者的辛勤工作
灵感来源于各种优秀的UI库
特别感谢开源社区的支持

📞 支持

📧 邮箱: [email protected]
🐛 问题反馈: GitHub Issues
💬 讨论: GitHub Discussions
📖 文档: 完整文档

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🎯 Awesome Progress Bars

✨ 特性

📦 安装

🚀 快速开始

基础用法

HTML

🎨 样式类型

线性进度条 (20种)

圆形进度条 (25种)

创意进度条 (50种)

主题化进度条 (25种)

🛠️ API 参考

ProgressBar类

配置选项

🎭 主题系统

内置主题

自定义主题

🎪 预设进度条

📱 框架集成

React

Vue

Angular

🎮 高级用法

进度条管理器

自定义动画

事件处理

🎨 CSS 自定义

CSS 变量

自定义样式

🌐 浏览器支持

📊 性能

🤝 贡献

开发设置

📄 许可证

🙏 致谢

📞 支持