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