ratatui-tui

ratatui-tui 是一套围绕 Rust 终端用户界面框架 ratatui 的开发指南、模板与参考资料，目标版本为 ratatui 0.30.x，MSRV 为 1.88，使用 edition 2024。

用途

用于在 Rust 中构建终端 UI（TUI）应用。文档列出的使用场景包括：(1) 创建新的 TUI 应用；(2) 添加控件或布局；(3) 处理键盘事件等。

快速开始

可将模板复制到项目：

cp -r ~/.agents/skills/ratatui-tui/assets/templates/<template>/* .

或从官方模板仓库生成：

cargo install --locked cargo-generate
cargo generate ratatui/templates

运行：

cargo run

模板选择

按复杂度分为四类：

最小（hello-world）：学习与快速演示。
简单（simple-app）：单屏应用与工具。
异步（async-app）：后台任务、网络请求。
完整（component-app）：多视图、配置、日志。

决策树：需要异步/网络 → async-app；多个屏幕/组件 → component-app；简单工具 → simple-app；学习 ratatui → hello-world。

版本说明（0.30.x）

模块化工作区：应用继续依赖 ratatui；控件库建议依赖 ratatui-core，以获得 API 稳定性并减少依赖。
ratatui::run(|terminal| ...)：初始化终端、安装可恢复终端的 panic hook、运行闭包并在退出时恢复。
Block::shadow(...)（0.30.1 新增）：为区块/弹窗添加阴影。
自 0.29 起的破坏性变更：移除 block::Title，layout::Alignment 更名为 HorizontalAlignment，Flex::SpaceAround 现与 flexbox 语义一致（旧行为请用 Flex::SpaceEvenly），Marker 变为非穷尽枚举。
性能：禁用 default-features 会同时禁用 layout-cache；需显式重新启用，否则布局性能会显著下降。

项目设置

最小 Cargo.toml：

[package]
name = "my-tui"
version = "0.1.0"
edition = "2024"

[dependencies]
ratatui = "0.30"
crossterm = "0.29"
color-eyre = "0.6"

component-app 的完整依赖包括 ratatui、crossterm（event-stream）、color-eyre、tokio、futures、clap、tracing、tracing-subscriber、serde、config、dirs，以及可选的 ratatui-image 11 和 tui-shimmer 0.1。

发布配置：

[profile.release]
lto = true
codegen-units = 1
panic = "abort"
strip = true

核心循环：TEA（The Elm Architecture）

架构为 Model → Message → Update → View，循环回 Model。文档给出 App 结构体、Message 枚举以及 update/view 方法的示例代码。

样式规则

推荐使用 Stylize trait 的辅助方法，如 .bold()、.dim()、.cyan()、.on_dark_gray()，避免硬编码白色/黑色或冗长的 Modifier 写法。配色建议：主色用 cyan/green，错误用 red，警告用 yellow（少量），弱化用 dim/dark_gray，强调用 magenta。文本换行可使用 textwrap 与 Line。

控件模式

StatefulWidget：实现 StatefulWidget 时定义 type State，通过 render_stateful_widget 使用状态。
布局：使用 Layout::vertical / Layout::horizontal 与 Constraint 组合。
内置状态类型：ListState、TableState、ScrollbarState。

异步事件处理

使用 crossterm 的 EventStream、futures 的 StreamExt 与 tokio 的 select!，在循环中先渲染再处理事件（键盘、后台任务、定时器等）。

图片集成

针对 ratatui-image 11.x。建议在启动时用 Picker::from_query_stdio() 查询协议与字体大小，并在 draw 之外完成编码（大图可放工作线程）：

let picker = Picker::from_query_stdio()?;
let dyn_img = image::open("photo.png")?;
let protocol: Protocol = picker.new_protocol(dyn_img, Size::new(40, 20), Resize::Fit(None))?;
frame.render_widget(Image::new(&protocol), area);

要点：可移植二进制使用 chafa-static 并设 default-features = false；协议只需查询一次；Image 无状态且固定尺寸，编码发生在 new_protocol；StatefulImage 会在渲染时按区域重新适配并编码，会阻塞，需通过 ratatui_image::thread::ThreadProtocol 驱动。

闪烁/加载动画

tui-shimmer 可在文本上扫过高亮，产生 “Loading…”/“Thinking…” 效果。提供时间和阶段驱动两种用法；动画需要重绘（约 80–120ms 的 tick），建议使用 _at_phase 变体并把 phase 存入 Model 以保持渲染纯净、便于测试。支持真彩色并对受限终端自动回退；该 API 在 1.0 前为实验性，需锁定版本并审查小版本升级。

错误处理

ratatui::run() / ratatui::init() 会安装可在 panic 前恢复终端的 hook，不应手写。应先安装 color-eyre，使终端在报告打印前恢复：

fn main() -> Result<()> {
    color_eyre::install()?;
    let result = ratatui::run(|terminal| App::default().run(terminal));
    Ok(result?)
}

错误传播使用 ? 处理可恢复错误，用 color_eyre 的 wrap_err 添加上下文。

发布构建

cargo build --release，产物位于 target/release/<name>。若更在意体积而非速度，可在发布配置中加入 opt-level = "z"。

模板概览

hello-world 约 25 行，使用 ratatui::run() 的最小演示；simple-app 约 80 行，同步事件循环、App 结构体与基础渲染；async-app 约 120 行，Tokio 运行时、EventStream、select! 模式；component-app 约 300 行，包含 main.rs、app.rs、event.rs、ui.rs、action.rs、tui.rs、config.rs、logging.rs 的完整模块化结构。

常见模式

居中弹窗：提供 centered_rect 函数示例；0.30.1+ 可用 Block::bordered().title("Confirm").shadow(Shadow::dark_shade().offset(Offset::new(2, 1))) 添加阴影。
键位显示与状态栏：使用 Line 组合带样式的文本片段。

多智能体 TUI 审查工作流

workflows/tui-review.js 是用于 Claude Code 的 Workflow 工具的 dynamic-workflow 模板。它按 TUI 维度分派审查者——TEA 架构、终端安全、样式、事件处理、渲染性能——并对每条发现进行对抗性验证，只保留确认的问题。在无 Workflow 工具的智能体（如 Codex）中，可把这五个维度作为人工审查清单。使用时需按代码库调整目标路径、维度与严重性阈值：

Workflow({
  scriptPath: "~/.agents/skills/ratatui-tui/workflows/tui-review.js",
  args: { path: "src/" },
})

发布前检查清单

cargo fmt
cargo clippy --all-features 无警告
测试之外不使用 unwrap()
所有退出路径都能恢复终端（使用 ratatui::run() 或 init/restore）
cargo build --release 成功
在目标终端上测试

限制

资料未提供该技能的安装命令、许可协议、维护状态或与特定平台的兼容性说明；ratatui-image 与 tui-shimmer 的 API 可能随版本变化，使用前应查阅对应 crate 文档。