SuperAPI AI 工具集

slt

编程与开发

查看项目

更新于 10-28 20:17

技能介绍

SuperLightTUI(简称 SLT)v0.26.0 是一个用于构建 Rust 终端用户界面(TUI)的即时模式(immediate-mode)框架。本技能面向 AI 代理,用于在用户要求创建、修改或调试终端 UI 代码时,依据 SLT 的真实 API 生成或调整代码。使用前应先核对 src/ 中的实际接口,避免套用旧版本或训练数据中的过时写法。

一、用途与基本模型

SLT 采用单闭包模型:应用主体是一个每帧执行的闭包 slt::run(|ui: &mut Context| { ... })。没有 App trait、Model/View/Update 结构或保留式组件树,状态保存在闭包外的普通 Rust 变量中。框架负责 flexbox 布局、ANSI 差异输出和 stdout 刷新。较大应用可把界面拆成函数,例如 fn render_card(ui: &mut Context, data: &Card),并通过 ui.provide 与 ui.use_context 共享只读状态,而不必逐层传递引用。程序通常以 use slt::prelude::*; 作为单行导入;该 prelude 不含 crossterm 的重新导出。

二、运行时注意点

  1. 鼠标行为:自 v0.26 起,RunConfig::default() 的 mouse_mode 为 None,本地解析为 MouseMode::Drag,经 SSH/mosh 时解析为 MouseMode::Click。因此普通 slt::run(...) 就支持点击、右键、双击、滚动、滚动条与分栏拖拽以及内置文本选择。无按键的指针移动只在 MouseMode::Hover 下上报,依赖 hovered、group_hover_*、on_hover 或 ui.tooltip 的应用需用 slt::run_with(slt::RunConfig::default().mouse_mode(slt::MouseMode::Hover), ...) 启动。MouseMode::Off 或 .mouse(false) 关闭鼠标并保留终端原生选择;.mouse(true) 等价于 Hover。Headless TestBackend 测试不受该模式影响,可直接注入鼠标事件。

  2. 焦点与按键:当 text_input、textarea、表单字段或打开的命令面板拥有焦点时,ui.key、ui.key_code、ui.key_mod、ui.shortcut 会跳过其正在编辑的按键(无 Ctrl/Super/Meta 的可打印键、Backspace、Delete、方向键、Home、End;textarea 另含 Enter/Up/Down;code_editor 另含 Tab、Shift+Tab、PageUp/PageDown),且与调用顺序无关。组合键、Esc、Tab(code_editor 之外)和功能键仍可触发快捷键;ui.raw_key(c) 能看到每次按键。

  3. 布局时序:Response.rect 反映上一帧,因为布局在闭包返回后执行,第 1 帧返回零矩形。依赖测量结果的逻辑可用 if ui.tick() > 0 { ... } 保护。

三、API 规则(v0.20 起)

  • 可选配置用 builder:Context 上的方法在存在至少一个选项时返回 builder;builder 以 mut self -> Self 消费自身,在 Drop 时渲染,.show() 消费并返回 Response。
  • 浮点数统一为 f64,公共接口不接收或返回 f32。
  • 位置参数不超过 3 个,更多参数应使用 <Widget>Opts 结构或 builder。
  • 有状态控件接收 &mut <Widget>State,而不是 &mut String、&mut Vec<T> 或 &mut usize;仅有 slider(&mut f64)、checkbox(&mut bool)、toggle(&mut bool) 等简单值例外。
  • 单矩形控件返回 Response;复合控件返回 <Widget>Response,其 Deref 到 Response 并带 #[must_use],不返回元组。
  • Context 方法有三种返回形态:Text<'_> 用于单个文本元素的链式构建;&mut Self 用于 spacer、line_wrap、toast、form_field;Response 用于独立渲染的有状态交互控件。button、badge、stat、help、separator、progress、slider、line_chart 等在 v0.26 返回响应构建器,可链式设置选项。
  • 方法命名按类别:动词表示动作,名词表示无副作用取值,形容词为不超过两个音节的构建器修饰词,构造器使用 Type::default()、Type::new(args) 或 Type::with_X(arg)。允许 bg、fg、id、idx、len、min、max、pos、pct、w、h、x、y 等通用缩写。闭包参数统一命名为 ui。

四、分层结构

共五层:Layer 1 为 &mut Context(ui 参数);Layer 2 为 ContainerBuilder(由 ui.container()、ui.bordered(...) 返回);Layer 3 为 Widget trait 扩展点;Layer 4 为各控件状态结构体;Layer 5 为 Response 或带额外字段的 <Widget>Response。当同一能力既可用快捷方式又可用显式写法时,技能输出优先使用显式形式。

五、常见控件形态

有状态交互控件使用 &mut <Widget>State 并返回 Response,包括 list、tabs、table、tree、select、radio、multi_select、file_picker、calendar、text_input、textarea(需传 rows)、code_editor(builder,代码高亮需 syntax-* 特性)、rich_log、command_palette、toast、spinner。简单值控件包括 button、checkbox、toggle、slider。展示类控件通过选项方法设置样式,如 badge、stat、separator、progress、line_chart、help、code_block、grid_columns。builder 型控件在 Drop 时渲染,例如 gauge、line_gauge、breadcrumb。复合响应带额外字段,例如 GaugeResponse 的 ratio、BreadcrumbResponse 的 clicked_segment、SplitPaneResponse 的 ratio、GutterResponse 的 current_highlight、FormFieldResponse 的 response、input、layout_rect。

六、钩子与条件样式

钩子须每帧按相同顺序调用,除非使用 id 键控版本:use_state 按调用顺序、不可放在条件分支;use_state_keyed 与 use_state_keyed_default 以 &'static str 或 String 为键、可用于条件分支与列表逐行状态;use_memo 与 use_effect 按调用顺序加依赖。条件样式可用 with_if(cond, modifier) 与 with(modifier) 合并分支,Text 与 ContainerBuilder 均支持,但两者闭包语义不同。

七、自定义组件与交互

大多数场景优先写普通函数;只有当组件自带由调用方持有的状态结构并希望获得 ui.widget(&mut w) 式调用时才实现 Widget trait。鼠标命中检测在目标元素前调用 ui.interaction();键盘处理通过 ui.register_focusable() 获取焦点,再用 ui.key_presses_when(focused) 遍历按键并用 ui.consume_event(index) 标记已处理。

八、焦点、滚动与几何

可滚动容器跟随焦点,ui.scrollable(&mut scroll) 会把新获得焦点的子项滚入视野;ScrollState::follow_focus 默认 true,可关闭改为应用控制。表单可用 ui.form_field(&mut field)(保持链式)或 ui.form_field_response 获取响应。Response.rect 是裁剪后的命中矩形;ui.focused_layout_rect() 与 ui.measured_layout_rect("name") 返回上一帧完整布局框。Headless 测试中 TestBackend 每帧推进时钟,可用 tb.advance_time(Duration::ZERO) 固定时钟,has_pending_input() 报告 Tab 组后排队输入。有界画布可用 ui.try_canvas 或 ui.canvas_with。

九、适用场景与限制

适用于用 Rust 编写终端应用,如数据表格、仪表盘、表单、日志查看器等。限制与注意事项:需要按 v0.26 实际 API 编写,旧版本方法(如 gauge_w、line_gauge_with、breadcrumb_sep 等)已移除;鼠标默认开启而悬停需显式配置;文本输入聚焦时会拦截可编辑按键;首帧测量数据不可用。资料未提供该技能的安装命令、收费方式、价格及平台信息,相关内容暂未提供。