探秘Whirly：终端彩色动态加载指示器

在如今的命令行开发中，一个生动有趣的加载指示器能够极大地提升用户体验。Whirly就是这样一款专为Ruby设计的简单、多彩且可定制的终端加载指示器库，它内置了24种自定义动画和来自cli-spinners项目的更多样式。

动态演示

查看以下精彩演示：

或者在asciinema上直接体验全部预设的Whirly样式。

此外，还可以查看由cli-spinners提供的额外样式：

在这个asciinema中也能找到他们的实际运行效果。

快速上手

在你的Gemfile里添加如下代码：

gem 'whirly'
gem 'paint' # 让Whirly支持颜色（推荐）

之后，就可以愉快地使用Whirly啦！

基本用法

将下面的代码块放在你需要显示加载指示器的地方：

Whirly.start do
  # 在这里执行耗时操作
  sleep 5
end

可以随时更新指示器的文字信息：

Whirly.start do
  Whirly.status = "设置一些文本与加载符号一起显示"
  sleep 3
  Whirly.status = "更新它"
  sleep 2
end

如果你不喜欢使用代码块的形式，也可以手动控制开始和停止：

Whirly.start
sleep 5
Whirly.stop

start方法接受很多选项以定制你的指示器，如指定动画样式、初始状态等。详细信息见下文。

例如，这样设置一个使用"Pong"动画且无色的状态：

Whirly.start spinner: "pong", color: false, status: "游戏乒乓" do
  sleep 10
end

查看示例目录获取更多的应用场景。

配置Whirly

通过调用.configure方法，你可以设置一个持久化的配置，这将在所有的.start调用中应用：

Whirly.configure spinner: "dots"

Whirly.start do
  sleep 3 # 将使用dots动画
end

Whirly.start do
  sleep 3 # 再次使用dots动画
end

调用.reset会恢复到未配置的状态：

Whirly.configure spinner: "dots"

Whirly.reset

Whirly.start do
  sleep 3 # 将使用默认动画
end

动画样式

内置样式

详情可查阅以下文件：

• data/whirly-static-spinners.json -lib/whirly/spinners/whirly.rb
• cli-spinners项目。要观看所有内置样式的演示，请运行脚本examples/all_spinners.rb。

Whirly.start 和 Whirly.configure 的配置选项

主要选项

spinner:

默认: "whirly"

你可以通过以下方式设定使用的动画：

• 使用内置动画名
• 提供一个动画帧数组
• 定义一个动态生成动画帧的Proc对象
• 直接提供一个完整的动画哈希对象（参阅下方“完整动画哈希格式”）

status:

默认: 无

用于直接设置初始状态文本，以显示在加载符号旁。

interval:

默认: 100

每帧动画之间的时间间隔，单位是毫秒。

进阶选项

ambiguous_characters_width:

默认: 1

如果设置为2，则异形Unicode字符会被视为宽度为2列。

ansi_escape_mode:

默认: "restore"

可选择为"line"来尝试另一种ANSI转义序列的生成方式（实验性功能）。

append_newline:

默认: true

当Whirly块结束（或调用了.stop）时，将会打印一个换行符。若不想换行，请将其设为false。

color:

默认: 如果已定义Paint常量，则启用

该选项控制是否以随机颜色显示加载符号。若不希望有色彩，设为false。另外还有color_change_rate选项。

color_change_rate:

默认: 30

颜色变化的速率值。

hide_cursor:

默认: true

默认情况下，加载期间会隐藏终端光标，退出程序时会自动恢复。如不想隐藏光标，将此选项设为false。

mode:

默认: "linear"

指示如何播放帧。可能的值有："linear"，"reverse"，"swing"和"random"。参阅"模式"部分了解详情。

non_tty:

默认: false

Whirly仅在真正的终端环境下工作。如果你想在非终端环境中激活它，将此选项设为true。

position:

默认: "normal"

设为"below"可以让Whirly出现在正常位置的下一行。

remove_after_stop:

默认: false

停止后移除最后一个帧。

stop:

默认: 无

你可以指定一个自定义帧作为动画结束的标志，例如：

Whirly.start spinner: "clock", interval: 1000, stop: "⏰" do
  sleep 12
end

spinner_packs:

默认: [:whirly, :cli]

Whirly包含了来自不同源的动画。此选项指定要考虑的源及其顺序（值对应Whirly::Spinners的大写字母常量）。

stream:

默认: $stdout

你可以传入一个兼容IO的对象，让Whirly在其他流上显示。

完整动画哈希格式

完整的动画是一个哈希，它可以有以下几个键值对。请注意，为了保持格式更通用，所有键都是字符串，而不是Ruby符号。除了"frames"和"proc"外，所有其他选项在启动或配置Whirly时都可覆盖。参考内置动画以获取样例定义。

"frames"

一个字符串的数组或枚举，它们会作为动画图标。

"proc"

替代"frames"：一个每次调用都会生成下一帧的Proc。

"interval"

帧间切换的毫秒数。

"mode"

播放帧的顺序。可以是以下之一：

• "linear"：按正常顺序循环
• "reverse"：反向循环
• "swing"：先正向循环，再反向循环，但每个回合只播放第一帧和最后一帧一次
• "random"：随机播放帧

请注意："linear"模式下，即使帧仅为枚举对象也可工作，而其他帧模式要求能表示为数组。

"stop"

用来结束动画的帧。

注意事项、问题解决与限制

• 间隔时间是毫秒，但不要依赖精确计时
• 如果流不是真实的终端（或者传递了non_tty: true），Whirly将不会有任何动作
• 颜色无法显示？确保在你的Gemfile中引入了paint库
• 不要设置太短的间隔（可能会显著影响性能）

许可证

• Whirly由Jan Lelis（https://janlelis.com）于2016年发布，并遵循MIT许可证。
• 包含来自cli-spinners的数据：MIT许可，Sindre Sorhus（[e-mail]）拥有版权（sindresorhus.com）。