用途:这是 Warp 无头 TUI 前端的 UI 编写规范,是 GUI 界面规范的 TUI 对应版本,面向所有 TUI UI 任务,建议在任务开始前阅读并贯穿实现过程。
主要能力与范围:TUI 与 GUI 桌面应用是不同前端,不能沿用像素布局、鼠标像素命中测试、GPU/WGSL 渲染、.app 包等 GUI 假设。前端视图/屏幕位于 crates/warp_tui,含按渠道的 console 二进制(如 crates/warp_tui/src/bin);元素库位于 crates/warpui_core/src/elements/tui,由 tui cargo feature 控制,是与 GUI Element/View 库并行的单元格网格元素词汇。可与 GUI 共用的部分:warp_core/warpui 的 Entity/model 核心(App/Entity/AppContext/ViewContext)、actions 系统、Appearance/主题、FeatureFlag 运行时检查、遥测与日志。不可在 TUI 使用:GUI Element/View 类型、像素几何、GPU/WGSL 渲染或像素绘制的按钮主题。TUI 仍有悬停/点击,TuiHoverable 与 tui_collapsible 复用共享的 MouseStateHandle,该句柄应像 GUI 一样在 render 之外持有;仅像素命中测试属 GUI 专属。
TuiElement trait(定义于 crates/warpui_core/src/elements/tui/mod.rs):layout 按约束测量并返回尺寸;render 向 buffer 的 area 绘制;cursor_position 返回光标位置;present 参与子视图递归;dispatch_event 分发事件并返回是否处理。元素须以 .finish() 结束,不要手动 Box::new 包裹。
组合词汇:TuiFlex(row/column、child、flex_child、with_cross_axis_alignment)、TuiContainer、TuiConstrainedBox(如 with_max_cols);TuiText(with_style、truncate、from_spans);TuiChildView、TuiEventHandler(如 on_key);TuiParentElement 提供 with_child/with_children/add_child/add_children;几何类型 TuiSize、TuiRect、TuiConstraint(loose/tight/clamp)、TuiPoint。
样式:TuiStyle 由 Color 与 Modifier(如 BOLD、DIM)组成,绘制进 Cell 的 TuiBuffer,终端单元格无透明度。应优先使用 TuiUiBuilder(crates/warp_tui/src/tui_builder.rs)的语义样式,如 primary_text_style、muted_text_style、error_text_style、accent_border_style 等,通过 TuiUiBuilder::from_app(app) 每次渲染时构造;不要直接使用原始 ANSI 色位(如 Color::White)。
事件与快捷键:Crossterm 输入在 crate::runtime 转为 TuiEvent 并沿元素树分发;快捷键遵循 GUI 约定,视图模块暴露 init(app) 注册绑定,汇总于 crates/warp_tui/src/keybindings.rs 并在 TUI 启动时调用一次。固定绑定(如 ctrl-c)标记为 TUI_BINDING_GROUP,可编辑绑定使用 tui: 前缀;GUI 绑定不会在 TUI 触发,校验器会强制 TUI 上下文绑定的归属。
验证:用 ./script/run-tui 运行并观察输出;TUI 变更需构建运行验证,相关流程见 tui-verify-change,测试见 tui-testing。应核对元素库与 TuiUiBuilder 的真实 API 名称,不要臆造方法;现有 crates/warp_tui 视图代码多为早期原型,不应视为规范范例。
限制:资料未提供安装命令、收费或价格、支持平台等信息。