spinner-utils

Node.js 命令行加载动画工具库。

特性

• 50+ 内置动画样式
• 支持自定义动画帧
• 可配置前缀、后缀、动画速度
• 支持进度百分比显示
• 链式 API
• 内置 succeed/fail/warn/info 彩色输出
• 零依赖

安装

npm install spinner-utils

快速开始

const Spinner = require('spinner-utils');

// 创建并启动
const spinner = new Spinner({
  frames: 'braille',
  prefix: 'Loading',
  interval: 100,
  autoStart: true
});

// 或者使用快捷方法
const spinner = Spinner.spin('dots', 'Please wait');

使用方法

基础用法

const Spinner = require('spinner-utils');

const spinner = new Spinner({
  frames: 'braille',    // 动画预设或自定义数组
  prefix: 'Loading',    // 前缀文字
  suffix: '',          // 后缀文字
  interval: 100,      // 动画间隔(毫秒)
  autoStart: true      // 自动开始动画
});

// 完成后调用
spinner.succeed('Done!');

可用预设

| 预设名 | 示例输出 | |--------|---------| | braille | Loading - / \ | ... | | moon | Loading - ... | | dots | Loading - ... | | line | Loading / | \ - | | arrow | Loading - ... | | plus | Loading + ++ +++ | | equal | Loading = == === | | box | Loading - ... | | pulse | Loading - ... | | triangle | Loading - ... | | loading | Loading L Lo Loa | | wait | Loading wait wait. | | dash | Loading - -- --- |

自定义动画帧

const spinner = new Spinner({
  frames: ['<', '<-', '<--', '<---', '----'],
  prefix: 'Uploading',
  autoStart: true
});

进度百分比

const spinner = new Spinner({
  frames: 'box',
  prefix: 'Downloading',
  autoStart: true
});

let percent = 0;
const timer = setInterval(() => {
  percent += 10;
  spinner.setProgress(percent);
  
  if (percent >= 100) {
    clearInterval(timer);
    spinner.succeed('Download complete!');
  }
}, 300);

快捷方法

const spinner = Spinner.spin('moon', 'Loading files...');
spinner.succeed('All files loaded!');

彩色输出方法

spinner.succeed('Operation completed!');  // 绿色勾选
spinner.fail('Operation failed!');         // 红色叉
spinner.warn('Warning: low disk space!');   // 黄色警告
spinner.info('Info: 3 files processed');   // 青色信息

链式 API

new Spinner()
  .setFrames('braille')
  .setPrefix('Processing')
  .setProgress(0)
  .start();

.setProgress(50)
// ...
.succeed('Complete!');

命令行用法

# 全局安装或使用 npx
npm install -g spinner-utils

# 基本用法
spinner "Processing..."

# 自定义动画
spinner -f moon "Loading..."

# 查看所有预设
spinner --list
spinner -l

# 自定义间隔
spinner -i 50 "Fast loading..."

API 参考

new Spinner(options)

创建 Spinner 实例。

参数:

• frames (string|string[]): 动画帧或预设名称。默认: 'braille'
• prefix (string): 前缀文字。默认: 'Loading'
• suffix (string): 后缀文字。默认: ''
• interval (number): 动画间隔(毫秒)。默认: 100
• stream (stream): 输出流。默认: process.stdout
• autoStart (boolean): 自动开始动画。默认: false

方法

| 方法 | 描述 | |------|------| | start() | 开始动画 | | stop() | 停止并清除动画 | | pause() | 暂停(保留最后帧) | | resume() | 恢复暂停的动画 | | setPrefix(text) | 设置前缀 | | setSuffix(text) | 设置后缀 | | setProgress(percent) | 设置进度百分比 | | setMessage(msg) | 设置消息 | | setFrames(frames) | 切换动画 | | succeed(msg) | 显示成功并停止 | | fail(msg) | 显示错误并停止 | | warn(msg) | 显示警告并停止 | | info(msg) | 显示信息并停止 |

静态方法

| 方法 | 描述 | |------|------| | Spinner.spin(frames, prefix, interval) | 快捷创建并启动 | | Spinner.presets | 获取所有预设名称 | | Spinner.preset(name) | 获取预设动画帧 |

添加新动画

编辑 frames.js 文件添加新预设:

// frames.js
module.exports = {
  // 现有预设...
  
  // 新增动画:
  mySpinner: ['A', 'B', 'C', 'D'],
};

使用:

const spinner = new Spinner({ frames: 'mySpinner', autoStart: true });

示例

异步操作

function fetchData() {
  return new Promise((resolve) => {
    const spinner = new Spinner({ prefix: 'Fetching data', autoStart: true });
    
    setTimeout(() => {
      spinner.succeed('Data fetched!');
      resolve({ data: [1, 2, 3] });
    }, 2000);
  });
}

文件处理

const Spinner = require('spinner-utils');
const files = ['a.txt', 'b.txt', 'c.txt'];

const spinner = new Spinner({
  frames: 'equal',
  prefix: 'Processing files',
  autoStart: true
});

let processed = 0;
files.forEach((file, i) => {
  setTimeout(() => {
    processed++;
    spinner.setSuffix(` (${processed}/${files.length})`);
    if (processed === files.length) {
      spinner.succeed(`Processed ${files.length} files!`);
    }
  }, (i + 1) * 500);
});

License

MIT