# TUI 转换层 - 强大的 WebUI 到终端界面转换引擎 ## 架构设计 TUI 转换层是 NebulaShell 的核心组件之一,提供完整的 HTML/CSS/JS 到终端界面的转换能力。 ### 核心理念 1. **只访问 WebUI 开放的 /tui 接口** - TUI 不直接渲染内容,而是通过 `/tui/*` 接口获取带有特殊标记的 HTML 2. **强大的转换层** - 自动解析 HTML 结构、CSS 样式、JS 交互配置,转换为终端元素 3. **参考 opencode 风格** - 提供现代化的终端用户体验 ### 接口规范 #### `/tui/index.html` - TUI 入口 返回特殊标记的 HTML,不含用户可见内容,包含: - `data-tui-*` 属性标记 - ` ``` ### 支持的组件 | 组件 | HTML 标签 | 描述 | |------|----------|------| | 面板 | `` | 带边框的面板/卡片 | | 按钮 | `` | 可点击按钮,支持快捷键 | | 列表 | `/` | 有序/无序列表 | | 进度条 | `` | 进度条组件 | | 加载动画 | `` | 旋转加载器 | | 导航 | `` | 导航菜单 | | 分隔线 | `` | 水平分隔线 | ### 使用示例 ```python from oss.tui.converter import TUIManager, HTMLToTUIConverter # 创建转换器 converter = HTMLToTUIConverter(width=80, height=24) # 解析 HTML html = """ 欢迎 退出 [q] """ layout = converter.parse(html) output = layout.render() print(output) # 使用 TUI 管理器 manager = TUIManager.get_instance() manager.load_page("/welcome", html) manager.render_current() manager.run_event_loop() ``` ### 开发指南 1. **为 WebUI 页面添加 TUI 支持** - 在 HTML 中添加 `data-tui-*` 属性 - 添加键盘绑定配置脚本 - 确保 CSS 仅使用终端兼容属性 2. **创建新的 TUI 组件** - 继承 `TUIElement` 基类 - 实现 `render()` 方法 - 在 `HTMLToTUIConverter._create_tui_element()` 中注册 3. **扩展交互功能** - 在 `TUIInputHandler` 中添加新的事件处理器 - 在 `/tui/interact` 接口中处理新的事件类型 ## License MIT License - NebulaShell Project