rattles-terminal-spinners

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rattles Terminal Spinners

Rattles 终端加载动画库

Skill by ara.so — Daily 2026 Skills collection.

Rattles is a minimal, zero-dependency Rust library for terminal spinners. It has no runtime or lifecycle — spinners are constructed directly in render loops with negligible cost. Supports

no_std

environments.

来自ara.so的技能 — 2026每日技能合集。

Rattles 是一个轻量、零依赖的Rust终端加载动画库。它无需运行时或生命周期管理——加载动画直接在渲染循环中构建，开销极低。支持

no_std

环境。

Installation

安装

toml

undefined

toml

undefined

Cargo.toml

[dependencies] rattles = "0.1" # with std (default)

[dependencies] rattles = "0.1" # 带std（默认）

no_std

no_std版本

rattles = { version = "0.1", default-features = false }


Or via CLI:

```sh
cargo add rattles

rattles = { version = "0.1", default-features = false }


或通过CLI安装：

```sh
cargo add rattles

no_std variant

no_std变体

cargo add rattles --no-default-features

undefined

cargo add rattles --no-default-features

undefined

Core Concepts

核心概念

Rattler: a spinner definition (frames + interval). Stateless and cheap to construct.
TickedRattler: stateful wrapper for tick-based driving (required in
```
no_std
```
).
Presets: built-in spinners organized by category.
rattle!
macro: define custom spinners at compile time.

Rattler：加载动画定义（帧 + 间隔）。无状态且构建成本极低。
TickedRattler：基于节拍驱动的有状态包装器（
```
no_std
```
环境下必需）。
Presets：按类别划分的内置加载动画。
rattle!
宏：在编译时定义自定义加载动画。

Basic Usage (std)

基础用法（std环境）

rust

use std::{io::Write, time::Duration};
use rattles::presets::prelude as presets;

fn main() {
    let rattle = presets::dots();

    loop {
        print!("\r{}", rattle.current_frame());
        std::io::stdout().flush().unwrap();
        std::thread::sleep(Duration::from_millis(80));
    }
}

current_frame()

uses the system clock internally — no state needed.

rust

use std::{io::Write, time::Duration};
use rattles::presets::prelude as presets;

fn main() {
    let rattle = presets::dots();

    loop {
        print!("\r{}", rattle.current_frame());
        std::io::stdout().flush().unwrap();
        std::thread::sleep(Duration::from_millis(80));
    }
}

current_frame()

内部使用系统时钟——无需维护状态。

Preset Categories

预设类别

rust

use rattles::presets::{arrows, ascii, braille, emoji};
use rattles::presets::prelude as presets; // re-exports all presets

// Arrows
let s = arrows::arrow();
let s = arrows::arrow2();

// ASCII
let s = ascii::line();
let s = ascii::pipe();

// Braille
let s = braille::dots();
let s = braille::dots2();

// Emoji
let s = emoji::earth();
let s = emoji::clock();

// Prelude examples
let s = presets::waverows();
let s = presets::dots();

rust

use rattles::presets::{arrows, ascii, braille, emoji};
use rattles::presets::prelude as presets; // 导出所有预设

// 箭头类
let s = arrows::arrow();
let s = arrows::arrow2();

// ASCII类
let s = ascii::line();
let s = ascii::pipe();

// 盲文类
let s = braille::dots();
let s = braille::dots2();

// 表情符号类
let s = emoji::earth();
let s = emoji::clock();

// 预导出示例
let s = presets::waverows();
let s = presets::dots();

Rattler API

rust

use rattles::presets::prelude as presets;
use std::time::Duration;

let rattle = presets::dots();

// Get frame based on system clock (std only)
let frame: &str = rattle.current_frame();

// Get frame at specific elapsed duration (std + no_std)
let frame = rattle.frame_at(Duration::from_millis(500));

// Get frame by index
let frame = rattle.frame(3);

// Change animation interval
let rattle = presets::dots().set_interval(Duration::from_millis(50));

// Reverse direction
let rattle = presets::waverows().reverse();

// Convert to tick-based (stateful)
let mut ticked = presets::dots().into_ticked();

rust

use rattles::presets::prelude as presets;
use std::time::Duration;

let rattle = presets::dots();

// 根据系统时钟获取帧（仅std环境）
let frame: &str = rattle.current_frame();

// 根据特定已流逝时长获取帧（std + no_std环境）
let frame = rattle.frame_at(Duration::from_millis(500));

// 通过索引获取帧
let frame = rattle.frame(3);

// 修改动画间隔
let rattle = presets::dots().set_interval(Duration::from_millis(50));

// 反转方向
let rattle = presets::waverows().reverse();

// 转换为基于节拍的（有状态）
let mut ticked = presets::dots().into_ticked();

TickedRattler (Stateful / no_std-friendly)

TickedRattler（有状态 / 适配no_std）

rust

use rattles::presets::prelude as presets;

let mut rattle = presets::dots().into_ticked();

loop {
    rattle.tick();
    let frame = rattle.current_frame();
    // render frame...
}

TickedRattler

must be stored (it holds state). Suitable for

no_std

contexts where the global clock is unavailable.

rust

use rattles::presets::prelude as presets;

let mut rattle = presets::dots().into_ticked();

loop {
    rattle.tick();
    let frame = rattle.current_frame();
    // 渲染帧...
}

TickedRattler

必须被存储（它持有状态）。适用于无法使用全局时钟的

no_std

场景。

Index-Based Animation (no_std)

基于索引的动画（no_std环境）

rust

use rattles::presets::prelude as presets;

let rattle = presets::dots();
let mut i = 0usize;

loop {
    let frame = rattle.frame(i);
    i = i.wrapping_add(1);
    // render frame...
}

rust

use rattles::presets::prelude as presets;

let rattle = presets::dots();
let mut i = 0usize;

loop {
    let frame = rattle.frame(i);
    i = i.wrapping_add(1);
    // 渲染帧...
}

Time-Based Animation with External Clock (no_std)

基于外部时钟的时间驱动动画（no_std环境）

rust

use rattles::presets::prelude as presets;
use core::time::Duration;

let rattle = presets::dots();

// elapsed comes from your platform's timer
let elapsed: Duration = get_elapsed(); // your implementation
let frame = rattle.frame_at(elapsed);

rust

use rattles::presets::prelude as presets;
use core::time::Duration;

let rattle = presets::dots();

// elapsed来自平台计时器
let elapsed: Duration = get_elapsed(); // 你的实现代码
let frame = rattle.frame_at(elapsed);

Custom Spinners with

rattle!

Macro

使用

rattle!

宏定义自定义加载动画

rust

use rattles::rattle;

rattle!(
    MySpinner,   // generated struct name
    my_spinner,  // generated constructor function name
    1,           // row count (width of spinner)
    120,         // interval in milliseconds
    ["⣾", "⣷", "⣯", "⣟", "⣻", "⣽"]  // keyframes
);

// Use it like any preset
let s = my_spinner();
println!("{}", s.current_frame());

Multi-row custom spinner:

rust

rattle!(
    Wide,
    wide_spinner,
    3,   // 3 characters wide
    80,
    ["[   ]", "[=  ]", "[== ]", "[===]", "[ ==]", "[  =]"]
);

rust

use rattles::rattle;

rattle!(
    MySpinner,   // 生成的结构体名称
    my_spinner,  // 生成的构造函数名称
    1,           // 行数（加载动画宽度）
    120,         // 间隔（毫秒）
    ["⣾", "⣷", "⣯", "⣟", "⣻", "⣽"]  // 关键帧
);

// 像使用预设一样使用它
let s = my_spinner();
println!("{}", s.current_frame());

多行自定义加载动画：

rust

rattle!(
    Wide,
    wide_spinner,
    3,   // 宽度为3个字符
    80,
    ["[   ]", "[=  ]", "[== ]", "[===]", "[ ==]", "[  =]"]
);

Ratatui Integration

Ratatui集成

rust

// examples/ratatui.rs pattern
use rattles::presets::prelude as presets;
use ratatui::{
    backend::CrosstermBackend,
    widgets::Paragraph,
    Terminal,
};

fn ui(frame: &mut ratatui::Frame, rattle: &rattles::Rattler) {
    let spinner_text = rattle.current_frame();
    let paragraph = Paragraph::new(format!("{} Loading...", spinner_text));
    frame.render_widget(paragraph, frame.size());
}

fn main() -> std::io::Result<()> {
    let rattle = presets::dots();

    // standard ratatui event loop
    loop {
        terminal.draw(|f| ui(f, &rattle))?;
        std::thread::sleep(std::time::Duration::from_millis(16));

        // break on user input...
    }
    Ok(())
}

Since

Rattler

is stateless, pass it by reference anywhere — no

Arc<Mutex<>>

needed.

rust

// examples/ratatui.rs 示例代码
use rattles::presets::prelude as presets;
use ratatui::{
    backend::CrosstermBackend,
    widgets::Paragraph,
    Terminal,
};

fn ui(frame: &mut ratatui::Frame, rattle: &rattles::Rattler) {
    let spinner_text = rattle.current_frame();
    let paragraph = Paragraph::new(format!("{} Loading...", spinner_text));
    frame.render_widget(paragraph, frame.size());
}

fn main() -> std::io::Result<()> {
    let rattle = presets::dots();

    // 标准ratatui事件循环
    loop {
        terminal.draw(|f| ui(f, &rattle))?;
        std::thread::sleep(std::time::Duration::from_millis(16));

        // 用户输入时退出...
    }
    Ok(())
}

由于

Rattler

是无状态的，可通过引用传递到任何地方——无需使用

Arc<Mutex<>>

。

no_std Setup

no_std环境配置

toml

[dependencies]
rattles = { version = "0.1", default-features = false }

rust

#![no_std]
use rattles::presets::prelude as presets;

// Option 1: tick-based
let mut rattle = presets::dots().into_ticked();
rattle.tick();
let frame = rattle.current_frame();

// Option 2: index-based
let rattle = presets::dots();
let frame = rattle.frame(42);

// Option 3: duration-based (external clock)
let rattle = presets::dots();
let frame = rattle.frame_at(core::time::Duration::from_millis(840));

toml

[dependencies]
rattles = { version = "0.1", default-features = false }

rust

#![no_std]
use rattles::presets::prelude as presets;

// 选项1：基于节拍
let mut rattle = presets::dots().into_ticked();
rattle.tick();
let frame = rattle.current_frame();

// 选项2：基于索引
let rattle = presets::dots();
let frame = rattle.frame(42);

// 选项3：基于时长（外部时钟）
let rattle = presets::dots();
let frame = rattle.frame_at(core::time::Duration::from_millis(840));

Common Patterns

常见模式

Spinner with message

带消息的加载动画

rust

use rattles::presets::prelude as presets;
use std::{io::Write, time::Duration};

fn main() {
    let rattle = presets::dots();
    let message = "Fetching data...";

    loop {
        print!("\r{} {}", rattle.current_frame(), message);
        std::io::stdout().flush().unwrap();
        std::thread::sleep(Duration::from_millis(80));
    }
}

rust

use rattles::presets::prelude as presets;
use std::{io::Write, time::Duration};

fn main() {
    let rattle = presets::dots();
    let message = "Fetching data...";

    loop {
        print!("\r{} {}", rattle.current_frame(), message);
        std::io::stdout().flush().unwrap();
        std::thread::sleep(Duration::from_millis(80));
    }
}

Async-compatible (tokio)

异步兼容（tokio）

rust

use rattles::presets::prelude as presets;
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    let rattle = presets::dots();

    let spinner = tokio::spawn(async move {
        loop {
            print!("\r{}", rattle.current_frame());
            std::io::stdout().flush().unwrap();
            sleep(Duration::from_millis(80)).await;
        }
    });

    // do your async work
    do_work().await;
    spinner.abort();
    println!("\rDone!     ");
}

rust

use rattles::presets::prelude as presets;
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    let rattle = presets::dots();

    let spinner = tokio::spawn(async move {
        loop {
            print!("\r{}", rattle.current_frame());
            std::io::stdout().flush().unwrap();
            sleep(Duration::from_millis(80)).await;
        }
    });

    // 执行异步任务
    do_work().await;
    spinner.abort();
    println!("\rDone!     ");
}

Collecting all frames

收集所有帧

rust

let rattle = presets::dots();
let frames: Vec<&str> = (0..rattle.frame_count())
    .map(|i| rattle.frame(i))
    .collect();

rust

let rattle = presets::dots();
let frames: Vec<&str> = (0..rattle.frame_count())
    .map(|i| rattle.frame(i))
    .collect();

Troubleshooting

故障排除

Spinner not animating (stuck on first frame)

Ensure you're flushing stdout:
```
std::io::stdout().flush().unwrap()
```
Use
```
\r
```
to overwrite the line, not
```
\n
```
The sleep interval should match or be shorter than the spinner's interval

current_frame()
not available in no_std

Use

frame_at(duration)

frame(index)

, or

into_ticked()

instead

Disable default features:

rattles = { version = "...", default-features = false }

Custom spinner not compiling

Keyframes must be string literals in the
```
rattle!
```
macro array
Row count must match the visual width of each keyframe string

Spinner looks garbled in terminal

Some braille/emoji frames require a terminal with Unicode support
Test with ASCII presets (
```
ascii::line()
```
) to verify basic functionality first

加载动画不播放（停留在第一帧）

确保刷新标准输出：
```
std::io::stdout().flush().unwrap()
```
使用
```
\r
```
覆盖当前行，而非
```
\n
```
休眠间隔应等于或短于加载动画的间隔

current_frame()
在no_std环境中不可用

使用

frame_at(duration)

、

frame(index)

或

into_ticked()

替代

禁用默认特性：

rattles = { version = "...", default-features = false }

自定义加载动画编译失败

```
rattle!
```
宏数组中的关键帧必须是字符串字面量
行数必须与每个关键帧字符串的视觉宽度匹配

加载动画在终端中显示乱码

部分盲文/表情符号帧需要支持Unicode的终端
先使用ASCII预设（
```
ascii::line()
```
）验证基础功能是否正常

rattles-terminal-spinners

Original

Translation

Rattles Terminal Spinners

Rattles 终端加载动画库

Installation

安装

Cargo.toml

Cargo.toml

no_std

no_std版本

no_std variant

no_std变体

Core Concepts

核心概念

Basic Usage (std)

基础用法（std环境）

Preset Categories

预设类别

Rattler API

Rattler API

TickedRattler (Stateful / no_std-friendly)

TickedRattler（有状态 / 适配no_std）

Index-Based Animation (no_std)

基于索引的动画（no_std环境）

Time-Based Animation with External Clock (no_std)

基于外部时钟的时间驱动动画（no_std环境）

Custom Spinners with rattle! Macro

使用rattle!宏定义自定义加载动画

Ratatui Integration

Ratatui集成

no_std Setup

no_std环境配置

Common Patterns

常见模式

Spinner with message

带消息的加载动画

Async-compatible (tokio)

异步兼容（tokio）

Collecting all frames

收集所有帧

Troubleshooting

故障排除

Custom Spinners with
`rattle!`
Macro

使用
`rattle!`
宏定义自定义加载动画