旋转器 (Spinner)

超过 80 种内置旋转器模式
创建自定义旋转器模式
自定义旋转器的格式
方便的内置完成函数 (成功, 错误, 警告, 信息)
记录旋转器的时间并显示其持续时间
使用 rainbow 应用颜色
使用自定义 SpinnerStream 进行输出

安装

通过 Swift Package Manager 安装，在你的项目 Package.swift 中将 Spinner 声明为依赖项

.package(url: "https://github.com/dominicegginton/Spinner", from: "1.0.0")

入门

import Foundation
import Spinner

let spinner = Spinner(.dots, "foo bar baz")
spinner.start()
sleep(2) // do work
spinner.stop()

文档

创建旋转器

通过初始化 Spinner 类的实例来创建 spinner。

let spinner = Spinner(.dots, "foo bar baz")

Spinner() 类接受可选参数，用于自定义旋转器。

/**
Initialize spinner
- Parameter pattern: spinner pattern
- Parameter message: message to render
- Parameter color: spinner pattern color
- Parameter speed: speed of spinner animation
- Parameter format: spinner format
- Parameter stream: output steam for spinner
- Parameter signal: signal trap implementation for spinner
*/
public init(_ pattern: SpinnerPattern, _ message: String = "", color: Color = .default, speed: Double? = nil, format: String = "{S} {T}", stream: SpinnerStream? = nil, signal: SpinnerSignal? = nil)

启动旋转器

调用 Spinner.start() 函数启动旋转器动画。这也将调用 SpinnerStream.hideCursor() 函数来隐藏光标。

let spinner = Spinner(.dots, "foo bar baz")
spinner.start()

停止旋转器

调用 Spinner.stop() 函数停止旋转器动画。这也将调用 SpinnerStream.showCursor() 函数来显示光标。

let spinner = Spinner(.dots, "foo bar baz")
spinner.stop()

Spinner.stop() 函数接受可选参数，用于自定义其行为。

/**
Stop the spinner
- Parameter frame: final frame to render before stopping
- Parameter message: final message to render before stopping
- Parameter color: final frame color
- Parameter terminator: the string to print after all items have been printed
*/
public func stop(frame: String? = nil, message: String? = nil, color: Color? = nil, terminator: String = "\n")

清除旋转器

Spinner.clear() 函数是一个帮助函数，用于停止并清除旋转器。它的实现底层使用了 Spinner.stop()。

let spinner = Spinner(.dots, "foo bar baz")
spinner.clear()

辅助函数

为常见任务提供了底层实现 Spinner.stop() 的辅助函数。

/**
Stop and clear the spinner
*/
public func clear()

/**
Stop and render a green tick for the final pattern frame
- Parameter message: spinner message to render
*/
public func success(_ message: String? = nil)

/**
Stop and render a red cross for the final pattern frame
- Parameter message: spinner message to render
*/
public func error(_ message: String? = nil)

/**
Stop and render a yellow warning symbol for the final pattern frame
- Parameter message: spinner message to render
*/
public func warning(_ message: String? = nil)

/**
Stop and render a blue information sign  for the final pattern frame
- Parameter message: spinner message to render
*/
public func info(_ message: String? = nil)

在动画期间更新旋转器

提供了在动画期间更新旋转器的函数。

/**
Update spinner pattern
- Parameter pattern: spinner pattern
*/
public func pattern(_ pattern: SpinnerPattern)

/**
Update spinner message
- Parameter message: message to render
*/
public func message(_ message: String)

/**
Update spinner animation speed
- Parameter speed: speed of spinner animation
*/
public func speed(_ speed: Double)

/**
Update spinner pattern color
- Parameter color: spinner pattern color
*/
public func color(_ color: Color)

/**
Update spinner format
- Parameter format: spinner format
*/
public func format(_ format: String)

旋转器模式

自定义旋转器渲染格式

对于旋转器，Spinner.format 字符串被作为基础，其中的键会被替换以生成渲染的旋转器。

{S} 渲染动画模式
{T} 渲染消息
{D} 渲染自旋转器启动以来的持续时间

let spinner = Spinner(.dots, "foo bar baz", format : "{T} - {S}") // foo bar baz - ⠧

记录旋转器的持续时间

使用包含 {D} 的自定义 Spinner.format 字符串，以便渲染自旋转器动画启动以来的时间长度

let spinner = Spinner(.dots, "foo bar baz", format: "{D} {T} - {S}") // 8s ⠧ foo bar baz

创建自定义模式

使用 SpinnerPattern() 枚举初始化器来创建带有字符串数组的 spinner 模式。

let pattern = SpinnerPattern(frames: ["1","2","3","4","5"])
let spinner = Spinner(pattern, "foo bar baz", speed: 0.3) // 1 foo bar baz

自定义流

Spinner 将输出逻辑包装在 SpinnerStream 协议中。该库提供了 StdOutSpinnerStream 类，该类实现了写入 STDOUT。

struct SwiftCLISpinnerStream: SpinnerStream {
    private let _stdout: WritableStream

    init(stdout: WritableStream) {
        _stdout = stdout
    }

    func write(string: String, terminator: String) {
        _stdout.write(string, terminator: terminator)
    }

    func hideCursor() {
        _stdout.write("\u{001B}[?25l", terminator: "")
    }

    func showCursor() {
        _stdout.write("\u{001B}[?25h", terminator: "")
    }
}

let spinner = Spinner(.dots, "foo bar baz", stream: SwiftCLISpinnerStream(stdout: stdout))

注意事项

为了处理进程中断（例如，通过 ctrl+c 发送的 SIGINT），使用信号处理程序在退出前显示用户的光标。此库提供了一个 SpinnerSignal 协议和一个 DefaultSpinnerSignal 结构，默认情况下处理此功能。如果这与其他正在使用的信号冲突，则可以提供 SpinnerSignal 的自定义实现。有关处理信号的干净且安全的方法，请参阅 IBM-Swift/BlueSignals。您的项目的适当信号处理程序可能如下所示：

struct CustomSpinnerSignal: SpinnerSignal {
    func trap() {
        Signals.trap(signal: .int) { _ in
            // print("\u{001B}[?25h", terminator: "")
            // exit(0)
        }
    }
}

let spinner = Spinner(.dots, "foo bar baz", signal: CustomSpinnerSignal())