TUI 模块

TUI 模块为 XScript 提供基于 Bubble Tea 的终端用户界面(TUI)开发能力，让你可以使用 JavaScript 创建美观的、交互式的终端应用程序。

特性

🎨 现代化 TUI - 基于成熟的 Bubble Tea 框架

🔄 事件驱动 - Elm 架构风格的状态管理

⌨️ 键盘支持 - 完整的键盘事件处理

🖱️ 鼠标支持 - 可选的鼠标交互

📐 窗口响应 - 自动处理终端大小变化

🎭 全屏模式 - 支持替代屏幕缓冲区

引入模块

核心概念

TUI 模块采用 Elm 架构模式，包含三个核心函数：

init() - 初始化应用状态和命令

update(state, msg) - 根据消息更新状态

view(state) - 将状态渲染为字符串

快速开始

最简单的示例

API 参考

tui.NewProgram(config)

创建一个新的 TUI 程序。

参数：

返回： Program 对象

Program 方法

program.run()

运行程序（阻塞直到退出）。

返回： 最终状态

program.start()

非阻塞方式启动程序。

返回： boolean

program.send(msg)

向程序发送消息。

program.quit()

请求程序退出。

program.kill()

强制终止程序。

消息类型

键盘消息

常见按键名称：

字母：'a', 'b', ... 'z'

数字：'0', '1', ... '9'

方向键：'up', 'down', 'left', 'right'

特殊键：'enter', 'space', 'tab', 'esc', 'backspace'

组合键：'ctrl+c', 'ctrl+d', 'alt+enter'

鼠标消息

窗口大小消息

退出消息

辅助函数

tui.Quit()

创建一个退出命令。

tui.ClearScreen()

清除屏幕。

tui.HideCursor()

隐藏光标。

tui.ShowCursor()

显示光标。

完整示例

交互式菜单

实时计时器

表单输入

最佳实践

1. 状态管理

保持状态不可变，总是返回新的状态对象：

2. 退出处理

始终处理退出信号：

3. 窗口大小

处理窗口大小变化以适应不同终端：

4. 视图渲染

保持视图函数纯粹，不要有副作用：

5. 命令处理

命令应该返回消息，而不是直接修改状态：

常见问题

如何处理异步操作？

使用命令（Commands）处理异步操作：

如何使用全屏模式？

设置 altScreen 选项：

如何启用鼠标支持？

设置鼠标选项：

注意事项

编码 - 确保使用 UTF-8 编码

终端兼容性 - 某些旧终端可能不支持所有特性

性能 - 避免在 view 函数中进行复杂计算

状态大小 - 保持状态对象简洁

测试案例

TUI 模块提供了 8 个完整的测试案例，涵盖所有核心功能。这些测试位于 cmd/tui_tests/ 目录。

测试 1: 基础计数器 (01_counter.js)

简单的计数器应用，演示基本的状态管理和键盘输入。

功能特性:

状态管理

键盘输入响应

Quit 命令

操作说明:

↑/k - 增加计数

↓/j - 减少计数

r - 重置为 0

q - 退出

运行命令:

测试 2: 菜单导航 (02_menu.js)

交互式菜单系统，演示列表导航和选项选择。

功能特性:

列表导航

选项选择

分隔符处理

视觉反馈

操作说明:

↑/k - 向上导航

↓/j - 向下导航

Enter - 选择当前项

q - 退出

运行命令:

测试 3: 表单输入 (03_form.js)

多字段表单应用，演示文本输入和字段切换。

功能特性:

文本输入

多字段表单

Tab 键切换

密码字段隐藏

表单验证

操作说明:

输入文本填写字段

Tab - 切换到下一字段

Backspace - 删除字符

Enter - 提交表单

Ctrl+C - 退出

运行命令:

测试 4: TODO 应用 (04_todo.js)

完整的 TODO 管理应用，演示复杂状态管理。

功能特性:

添加任务

删除任务

切换完成状态

列表导航

进度统计

操作说明:

a - 添加新任务

d - 删除当前任务

Space - 切换完成/未完成

↑/k - 向上导航

↓/j - 向下导航

q - 退出

运行命令:

测试 5: 动画和定时器 (05_animation.js)

动态动画效果，演示 Init 命令和定时更新。

功能特性:

Init 命令

定时更新（Tick）

动态视图渲染

多种动画效果

暂停/继续控制

操作说明:

Space - 暂停/继续动画

q - 退出

运行命令:

测试 6: 窗口大小响应 (06_window_size.js)

响应式布局，演示窗口大小变化处理。

功能特性:

WindowSizeMsg 消息处理

响应式布局

窗口大小检测

动态调整界面

操作说明:

调整终端窗口大小观察效果

q - 退出

运行命令:

测试 7: 屏幕模式 (07_screen_modes.js)

屏幕控制功能，演示 Alt Screen 和光标控制。

功能特性:

Alt Screen 模式

光标隐藏/显示

屏幕清除

屏幕恢复

操作说明:

h - 隐藏光标

s - 显示光标

c - 清除屏幕

q - 退出

运行命令:

测试 8: 程序控制 (08_program_control.js)

程序控制命令，演示 Quit、Batch、Sequence 等命令。

功能特性:

Quit 命令

Batch 命令（批量操作）

Sequence 命令（顺序操作）

命令历史记录

操作说明:

↑ - 增加计数

b - Batch 命令测试

s - Sequence 命令测试

q - Quit 命令并退出

运行命令:

注意: 由于 JavaScript runtime 的线程安全限制，当前实现仅支持阻塞模式 program.run()，非阻塞模式 program.start() 暂不可用。

测试 9: 颜色和样式 (09_colors.js)

ANSI 颜色和样式演示，展示如何在 TUI 中使用彩色文本。

功能特性:

ANSI 颜色码

前景色（文字颜色）

背景色

文本样式（粗体、下划线等）

组合样式

操作说明:

←/h - 上一页

→/l - 下一页

q - 退出

运行命令:

颜色代码示例:

运行所有测试

查看所有测试的详细信息：

依次运行所有测试（PowerShell）：

for ($i=1; $i -le 8; $i++) {
    Write-Host "`n=== 运行测试 $i ==="
    go run . "tui_tests/0${i}_*.js"
    Start-Sleep -Seconds 1
}

依次运行所有测试（Bash）：

tui

TUI 模块#

特性#

引入模块#

核心概念#

快速开始#

最简单的示例#

API 参考#

tui.NewProgram(config)#

Program 方法#

program.run()#

program.start()#

program.send(msg)#

program.quit()#

program.kill()#

消息类型#

键盘消息#

鼠标消息#

窗口大小消息#

退出消息#

辅助函数#

tui.Quit()#

tui.ClearScreen()#

tui.HideCursor()#

tui.ShowCursor()#

完整示例#

交互式菜单#

实时计时器#

表单输入#

最佳实践#

1. 状态管理#

2. 退出处理#

3. 窗口大小#

4. 视图渲染#

5. 命令处理#

常见问题#

如何处理异步操作？#

如何使用全屏模式？#

如何启用鼠标支持？#

注意事项#

测试案例#

测试 1: 基础计数器 (01_counter.js)#

测试 2: 菜单导航 (02_menu.js)#

测试 3: 表单输入 (03_form.js)#

测试 4: TODO 应用 (04_todo.js)#

测试 5: 动画和定时器 (05_animation.js)#

测试 6: 窗口大小响应 (06_window_size.js)#

测试 7: 屏幕模式 (07_screen_modes.js)#

测试 8: 程序控制 (08_program_control.js)#

测试 9: 颜色和样式 (09_colors.js)#

运行所有测试#

相关资源#

相关模块#

TUI 模块

特性

引入模块

核心概念

快速开始

最简单的示例

API 参考

tui.NewProgram(config)

Program 方法

program.run()

program.start()

program.send(msg)

program.quit()

program.kill()

消息类型

键盘消息

鼠标消息

窗口大小消息

退出消息

辅助函数

tui.Quit()

tui.ClearScreen()

tui.HideCursor()

tui.ShowCursor()

完整示例

交互式菜单

实时计时器

表单输入

最佳实践

1. 状态管理

2. 退出处理

3. 窗口大小

4. 视图渲染

5. 命令处理

常见问题

如何处理异步操作？

如何使用全屏模式？

如何启用鼠标支持？

注意事项

测试案例

测试 1: 基础计数器 (01_counter.js)

测试 2: 菜单导航 (02_menu.js)

测试 3: 表单输入 (03_form.js)

测试 4: TODO 应用 (04_todo.js)

测试 5: 动画和定时器 (05_animation.js)

测试 6: 窗口大小响应 (06_window_size.js)

测试 7: 屏幕模式 (07_screen_modes.js)

测试 8: 程序控制 (08_program_control.js)

测试 9: 颜色和样式 (09_colors.js)

运行所有测试

相关资源

相关模块