百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
T

tty-progressbar

> 编程语言
开源

在终端中显示单个或多个进度条。

435 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

在终端中显示单个或多个进度条。

TTY::ProgressBar

A flexible and extensible progress bar for terminal applications.

TTY::ProgressBar provides independent progress bar component for TTY toolkit.

Features

  • Customisable. Choose from many configuration options to get the behaviour you want.
  • Flexible. Describe bar format and pick from many predefined tokens and bar styles.
  • Extensible. Define custom tokens to fit your needs.
  • Powerful. Display multi progress bars in parallel.
  • Show an unbounded operation with indeterminate progress.
  • Pause and resume progress at any time.
  • Include Unicode characters in progress bar.
  • Works on all ECMA-48 compatible terminals.

Installation

Add this line to your application's Gemfile:

ruby
gem "tty-progressbar"

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-progressbar

Contents

  • 1. Usage
  • 2. TTY::ProgressBar::API
    • 2.1 advance
    • 2.2 iterate
    • 2.3 current=
    • 2.4 ratio=
    • 2.5 width=
    • 2.6 start
    • 2.7 update
    • 2.8 finish
    • 2.9 stop
    • 2.10 pause
    • 2.11 reset
    • 2.12 resume
    • 2.13 complete?
    • 2.14 paused?
    • 2.15 stopped?
    • 2.16 indeterminate?
    • 2.17 resize
    • 2.18 on
  • 3. Configuration
    • 3.1 :total
    • 3.1 :width
    • 3.3 :complete
    • 3.4 :incomplete
    • 3.5 :head
    • 3.6 :unknown
    • 3.7 :bar_format
    • 3.8 :output
    • 3.9 :frequency
    • 3.10 :interval
    • 3.11 :hide_cursor
    • 3.12 :clear
    • 3.13 :clear_head
  • 4. Formatting
    • 4.1 Tokens
    • 4.2 Custom Formatters
    • 4.3 Custom Tokens
    • 4.4 Unicode
  • 5. Logging
  • 6. TTY::ProgressBar::Multi API
    • 6.1 new
    • 6.2 register
    • 6.3 advance
    • 6.4 start
    • 6.5 finish
    • 6.6 stop
    • 6.7 pause
    • 6.8 resume
    • 6.9 complete?
    • 6.10 paused?
    • 6.11 stopped?
    • 6.12 on
    • 6.13 :style
  • 7. Examples
    • 7.1 Colors
    • 7.2 Speed

1. Usage

TTY::ProgressBar requires only a format string with :bar token and total number of steps to completion:

ruby
bar = TTY::ProgressBar.new("downloading [:bar]", total: 30)

Once initialized, use advance method to indicated progress:

ruby
30.times do
  sleep(0.1)
  bar.advance  # by default increases by 1
end

This would produce the following animation in your terminal:

ruby
# downloading [=======================       ]

You can further change a progress bar behaviour and display by changing configuration options and using many predefined tokens and bar formats.

When you don't know the total yet, you can set it to nil to switch to indeterminate progress:

ruby
# downloading [                           ]

Use TTY::ProgressBar::Multi to display multiple parallel progress bars.

Declare a top level bar and then register child bars:

ruby
bars = TTY::ProgressBar::Multi.new("main [:bar] :percent")

bar1 = bars.register("one [:bar] :percent", total: 15)
bar2 = bars.register("two [:bar] :percent", total: 15)

Then progress the child bars in parallel:

ruby
bars.start  # starts all registered bars timers

th1 = Thread.new { 15.times { sleep(0.1); bar1.advance } }
th2 = Thread.new { 15.times { sleep(0.1); bar2.advance } }

[th1, th2].each { |t| t.join }

A possible terminal output may look like this:

ruby
# ┌ main [===============               ] 50%
# ├── one [=====          ] 34%
# └── two [==========     ] 67%

2. TTY::ProgressBar API

2.1 advance

Once you have TTY::ProgressBar instance, you can progress the display by calling advance method. By default, it will increase by 1 but you can pass any number of steps, for instance, a number of bytes for a downloaded file:

ruby
bar.advance(1024)

You can also pass negative steps if you wish to backtrack the progress:

ruby
bar.advance(-1)

Note: If a progress bar has already finished then any negative steps will not set it back to desired value.

2.2 iterate

To simplify progressing over an enumerable you can use iterate which as a first argument accepts an Enumerable and as a second the amount to progress the bar with.

First, create a progress bar without a total which will be automatically updated for you once iteration starts:

ruby
bar = TTY::ProgressBar.new("[:bar]")

Then, either directly iterate over a collection by yielding values to a block:

ruby
bar.iterate(30.times) { |v| ... }

Or return an Enumerator:

ruby
progress = bar.iterate(30.times)
# => #

By default, progress bar is advanced by 1 but you can change it by passing second argument:

ruby
bar.iterate(30.times, 5)

One particularly useful application of iterate are Ruby infamous lazy enumerators, or slowly advancing enumerations, representing complex processes.

For example, an Enumerator that downloads content from a remote server chunk at a time:

ruby
downloader = Enumerator.new do |y|
  start = 0
  loop do
    yield(download_from_server(start, CHUNK_SIZE))
    raise StopIteration if download_finished?
    start += CHUNK_SIZE
  end
end

Would be used with progress bar with the total size matching the content size like so:

ruby
bar = TTY::ProgressBar.new("[:bar]", total: content_size)
# you need to provide the total for the iterate to avoid calling enumerator.count
response = bar.iterate(downloader, CHUNK_SIZE).to_a.join

This would result in progress bar advancing after each chunk up until all content has been downloaded, returning the result of the download in response variable.

Please run slow_process example to see this in action.

2.3 current=

A progress doesn't have to start from zero. You can set it to a given value using current= method:

ruby
bar.current = 50

Note: If a progress bar has already finished then setting current value will not have any effect.

2.4 ratio=

In order to update overall completion of a progress bar as an exact percentage use the ratio= method. The method accepts values between 0 and 1 inclusive. For example, a ratio of 0.5 will attempt to set the progress bar halfway:

ruby
bar.ratio = 0.5

2.5 width=

You can set how many terminal columns will the :bar actually span excluding any other tokens and/or text.

For example, if you need the bar to be always 20 columns wide do:

ruby
bar.width = 20

Or with configuration options:

ruby
bar = TTY::ProgressBar.new("[:bar]", width: 20)

2.6 start

By default the timer for internal time estimation is started automatically when the advance method is called. However, if you require control on when the progression timer is started use start call:

ruby
bar.start  # => sets timer and draws initial progress bar

2.7 update

Once a progress bar has been started, you can change its configuration option(s) by calling update:

ruby
bar.update(complete: "+", frequency: 10)

2.8 finish

In order to immediately stop and finish progress of a bar call finish. This will finish drawing the progress by advancing it to 100% and returning to a new line.

ruby
bar.finish

2.9 stop

In order to immediately stop a bar in the current position and thus prevent any further progress use stop:

ruby
bar.stop

2.10 pause

A running progress bar can be paused at the current position using pause method:

ruby
bar.pause

A paused progress bar will stop accumulating any time measurements like elapsed time. It also won't return to a new line, so a progress animation can be smoothly resumed.

2.11 reset

In order to reset currently running or finished progress bar to its original configuration and initial position use reset like so:

ruby
bar.reset

After resetting a progress bar, if you wish to draw and start a bar and its timers use start call.

2.12 resume

When a bar is stopped or paused, you can continue its progression using the resume method.

ruby
bar.resume

A resumed progression will continue accumulating the total elapsed time without including time intervals for pausing or stopping.

2.13 complete?

During progression you can check whether a bar is finished or not by calling complete?. The bar will only return true if the progression finished successfully, otherwise false will be returned.

ruby
bar.complete? # => false

2.14 paused?

To check whether a progress bar is paused or not use paused?:

ruby
bar.paused? # => true

2.15 stopped?

To check whether a progress bar is stopped or not use stopped?:

ruby
bar.stopped? # => true

2.16 indeterminate?

You can make a progress bar indeterminate by setting :total to nil. In this state, a progress bar animation is displayed to show unbounded task. You can check whether the progress bar is indeterminate with the indeterminate? method:

ruby
bar.indeterminate? # => false

2.17 resize

If you want to change a progress bar's current width, use resize and pass in a new desired length. However, if you don't provide any width the resize will use terminal current width as its base for scaling.

ruby
bar.resize      # determine terminal width and scale accordingly
bar.resize(50)  # will resize bar proportionately from this point onwards

To handle automatic resizing you can trap :WINCH signal:

ruby
trap(:WINCH) { bar.resize }

2.18 on

A progress bar fires events when it is progressing, paused, stopped or finished. You can register to listen for these events using the on message.

Every time an advance is called the :progress event gets fired which you can listen for inside a block. A first yielded argument is the actual amount of progress:

ruby
bar.on(:progress) { |amount| ... }

When a progress bar finishes and completes then the :done event is fired. You can listen for this event:

ruby
bar.on(:done) { ... }

Alternatively, when a progress bar gets stopped the :stopped event is fired. You can listen for this event:

ruby
bar.on(:stopped) { ... }

Anytime a progress bar is paused the :paused event will be fired. To listen for this event do:

ruby
bar.on(:paused) { ... }

3. Configuration

There are number of configuration options that can be provided:

  • :total - the total number of steps to

Issues· 5 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rubyconsole-toolfrequencyintervalprogressbar

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言