# GitHub库 `github.com/schollz/progressbar/v3` 使用指南

`github.com/schollz/progressbar/v3` 是一个用于在终端显示进度条的Go语言库。它提供了丰富的功能和高度可定制的选项，适合各种需要展示进度的场景。

## 安装

在使用该库之前，请确保已安装 Go 环境（版本 >= 1.16）。然后通过以下命令安装：

go get github.com/schollz/progressbar/v3

## 基本用法

以下是一个简单的示例，展示如何创建并使用进度条：

package main

import (

"time"

"github.com/schollz/progressbar/v3"

)

func main() {

// 创建一个最大值为100的进度条
bar := progressbar.NewOptions(100,
    progressbar.OptionSetDescription("Processing"), // 设置描述信息
    progressbar.OptionSetWidth(50),               // 设置进度条宽度
    progressbar.OptionShowCount(),                // 显示计数
    progressbar.OptionThrottle(100*time.Millisecond), // 设置刷新频率
)

// 模拟任务进度
for i := 0; i <= 100; i++ {
    time.Sleep(50 * time.Millisecond) // 模拟工作延迟
    bar.Add(1)                      // 更新进度条
}

}

## 进度条创建方法

### 1. `New`
创建一个基本的进度条实例。

bar := progressbar.New(100)

- 参数：`maxValue int` - 进度条的最大值。

### 2. `NewOptions`
创建一个带有选项的进度条实例。

bar := progressbar.NewOptions(100, option1, option2, ...)

- 参数：
  - `maxValue int` - 进度条的最大值。
  - `options ...Option` - 自定义选项。

### 3. `NewOptions64`
创建一个支持 `int64` 类型最大值的进度条实例。

bar := progressbar.NewOptions64(100, option1, option2, ...)

- 参数：
  - `maxValue int64` - 进度条的最大值。
  - `options ...Option` - 自定义选项。

## 常用选项

以下是常用的 `Option` 配置项及其说明：

### 1. `OptionSetDescription(string)`
设置进度条的描述信息。

progressbar.OptionSetDescription("Downloading file...")

### 2. `OptionEnableColorCodes(bool)`
启用或禁用颜色编码。

progressbar.OptionEnableColorCodes(true)

### 3. `OptionShowBytes(bool)`
是否显示字节单位（如 KB、MB）。

progressbar.OptionShowBytes(true)

### 4. `OptionShowTotalBytes(bool)`
是否显示总字节数。

progressbar.OptionShowTotalBytes(true)

### 5. `OptionSetWidth(int)`
设置进度条的宽度（字符数）。

progressbar.OptionSetWidth(50)

### 6. `OptionShowCount()`
显示当前进度计数。

progressbar.OptionShowCount()

### 7. `OptionThrottle(time.Duration)`
设置进度条刷新频率。

progressbar.OptionThrottle(100 * time.Millisecond)

### 8. `OptionOnCompletion(func())`
设置进度条完成时的回调函数。

progressbar.OptionOnCompletion(func() {

fmt.Println("Task completed!")

})

### 9. `OptionSpinnerType(int)`
设置加载动画类型。

progressbar.OptionSpinnerType(progressbar.SpinnerCircleDotted)

### 10. `OptionShowPercent(bool)`
是否显示百分比。

progressbar.OptionShowPercent(true)

### 11. `OptionFullWidth(bool)`
是否让进度条占据终端的整个宽度。

progressbar.OptionFullWidth(true)

### 12. `OptionStartTime(time.Time)`
设置进度条的开始时间。

progressbar.OptionStartTime(time.Now())

### 13. `OptionTruncateText(bool)`
是否截断过长的文本。

progressbar.OptionTruncateText(true)

### 14. `OptionRemoveOnCompletion(bool)`
进度条完成后是否自动移除。

progressbar.OptionRemoveOnCompletion(true)

### 15. `OptionClearOnFinish(bool)`
进度条完成后是否清除终端内容。

progressbar.OptionClearOnFinish(true)

## 进度更新方法

### 1. `Add(int)`
增加进度条的当前值。

bar.Add(10)

### 2. `To(int)`
直接设置进度条的当前值。

bar.To(50)

### 3. `Increment()`
将进度条的当前值加1。

bar.Increment()

### 4. `Done()`
标记进度条为完成状态。

bar.Done()

## 示例代码

以下是一个完整的示例，展示如何结合多个选项使用进度条：

package main

import (

"fmt"
"time"

"github.com/schollz/progressbar/v3"

)

func main() {

// 创建进度条
bar := progressbar.NewOptions64(100,
    progressbar.OptionSetDescription("Processing..."),
    progressbar.OptionSetWidth(50),
    progressbar.OptionShowBytes(true),
    progressbar.OptionShowCount(),
    progressbar.OptionThrottle(100*time.Millisecond),
    progressbar.OptionOnCompletion(func() {
        fmt.Println("Task completed!")
    }),
    progressbar.OptionSpinnerType(progressbar.SpinnerCircleDotted),
    progressbar.OptionShowPercent(true),
    progressbar.OptionFullWidth(false),
    progressbar.OptionStartTime(time.Now()),
    progressbar.OptionTruncateText(false),
    progressbar.OptionRemoveOnCompletion(false),
    progressbar.OptionClearOnFinish(false),
)

// 模拟任务进度
for i := int64(0); i < 100; i++ {
    time.Sleep(50 * time.Millisecond)
    bar.Add(1)
}

}

## 总结

`github.com/schollz/progressbar/v3` 提供了灵活且强大的功能，能够满足各种进度展示需求。通过合理配置选项，可以轻松实现自定义的进度条效果。希望这份文档能帮助你快速上手并高效使用该库。