opentui

OpenTUI 平台技能

用于使用 OpenTUI 构建终端用户界面的综合技能。使用下方的决策树找到合适的框架和组件，然后加载详细参考文档。

关键规则

在所有 OpenTUI 代码中遵循以下规则：

1. 新项目使用 create-tui。 请参阅框架 REFERENCE.md 中的快速入门。
2. create-tui 选项必须放在参数之前。 bunx create-tui -t react my-app 可用，bunx create-tui my-app -t react 则不可用。
3. 绝不要直接调用 process.exit()。 请使用 renderer.destroy()（参见 core/gotchas.md）。
4. 在 React/Solid 中，文本样式需要使用嵌套标签。 使用修饰元素，而不是属性（参见 components/text-display.md）。

如何使用此技能

参考文件结构

框架参考文档遵循 5 文件模式。跨领域概念使用单文件指南。

./references/<framework>/ 中的每个框架都包含：

文件	用途	阅读时机
REFERENCE.md	概览、适用场景、快速入门	始终首先阅读
api.md	运行时 API、组件、钩子	编写代码时
configuration.md	设置、tsconfig、打包	配置项目时
patterns.md	常见模式、最佳实践	获取实现指导时
gotchas.md	易踩问题、限制、调试	排查问题时

./references/<concept>/ 中的跨领域概念以 REFERENCE.md 作为入口文件。

阅读顺序

1. 从所选框架的 REFERENCE.md 开始
2. 然后阅读与任务相关的其他文件：
   • 构建组件 -> api.md + components/<category>.md
   • 设置项目 -> configuration.md
   • 布局/定位 -> layout/REFERENCE.md
   • 键盘/输入处理 -> keyboard/REFERENCE.md
   • 分层按键绑定/命令 -> keymap/REFERENCE.md
   • 动画 -> animation/REFERENCE.md
   • 故障排查 -> gotchas.md + testing/REFERENCE.md

示例路径

./references/react/REFERENCE.md           # Start here for React
./references/react/api.md              # React components and hooks
./references/solid/configuration.md    # Solid project setup
./references/components/inputs.md      # Input, Textarea, Select docs
./references/core/gotchas.md           # Core debugging tips

运行时说明

OpenTUI 运行于 Bun，并使用 Zig 进行原生构建。请阅读 ./references/core/gotchas.md，了解运行时要求和构建指南。

快速决策树

“我应该使用哪个框架？”

Which framework?
├─ I want full control, maximum performance, no framework overhead
│  └─ core/ (imperative API)
├─ I know React, want familiar component patterns
│  └─ react/ (React reconciler)
├─ I want fine-grained reactivity, optimal re-renders
│  └─ solid/ (Solid reconciler)
└─ I'm building a library/framework on top of OpenTUI
   └─ core/ (imperative API)

“我需要显示内容”

Display content?
├─ Plain or styled text -> components/text-display.md
├─ Container with borders/background -> components/containers.md
├─ Scrollable content area -> components/containers.md (scrollbox)
├─ Standalone scrollbar -> components/containers.md (scrollbar)
├─ ASCII art banner/title -> components/text-display.md (ascii-font)
├─ PNG/JPEG/WebP/GIF image -> components/text-display.md (image)
├─ First-draw diagnostic -> components/text-display.md (time-to-first-draw)
├─ QR code -> components/text-display.md (qr-code, @opentui/qrcode)
├─ Embedded child terminal/VT output -> components/containers.md (Core only)
├─ Data table with borders/wrapping -> components/code-diff.md (TextTable)
├─ Code with syntax highlighting -> components/code-diff.md
├─ Diff viewer (unified/split, hunk nav) -> components/code-diff.md
├─ Line numbers with diagnostics -> components/code-diff.md
└─ Markdown content (streaming) -> components/code-diff.md (markdown)

“我需要接收用户输入”

User input?
├─ Single-line text field -> components/inputs.md (input)
├─ Multi-line text editor -> components/inputs.md (textarea)
├─ Select from a list (vertical) -> components/inputs.md (select)
├─ Tab-based selection (horizontal) -> components/inputs.md (tab-select)
├─ Value slider -> components/inputs.md (slider)
├─ Declarative/layered keybindings -> keymap/REFERENCE.md (@opentui/keymap)
└─ Custom keyboard shortcuts -> keyboard/REFERENCE.md

“我需要布局/定位”

Layout?
├─ Flexbox-style layouts (row, column, wrap) -> layout/REFERENCE.md
├─ Absolute positioning -> layout/patterns.md
├─ Responsive to terminal size -> layout/patterns.md
├─ Centering content -> layout/patterns.md
└─ Complex nested layouts -> layout/patterns.md

“我需要动画”

Animations?
├─ Timeline-based animations -> animation/REFERENCE.md
├─ Easing functions -> animation/REFERENCE.md
├─ Property transitions -> animation/REFERENCE.md
└─ Looping animations -> animation/REFERENCE.md

“我需要处理输入”

Input handling?
├─ Keyboard events (keypress, release) -> keyboard/REFERENCE.md
├─ Layered bindings, commands, leader keys -> keymap/REFERENCE.md
├─ Focus management -> keyboard/REFERENCE.md
├─ Paste events -> keyboard/REFERENCE.md
├─ Mouse events -> components/containers.md
├─ Text selection & copy-on-select -> keyboard/REFERENCE.md (selection)
└─ Host/terminal clipboard service or OSC 52 -> keyboard/REFERENCE.md (clipboard)

“我需要测试我的 TUI”

Testing?
├─ Snapshot testing -> testing/REFERENCE.md
├─ Interaction testing -> testing/REFERENCE.md
├─ Test renderer setup -> testing/REFERENCE.md
└─ Debugging tests -> testing/REFERENCE.md

“我需要平台功能（音频、图像、剪贴板、通知、SSH）”

Platform capability?
├─ Play loaded sound or MP3/FLAC stream -> core/api.md (Audio)
├─ Capture microphone PCM / record WAV -> core/api.md (Audio)
├─ Decode, transform, or display images -> components/text-display.md (image)
├─ Read/write host or terminal clipboard -> keyboard/REFERENCE.md (clipboard)
├─ Desktop notifications (OSC 9/777/99) -> core/api.md (triggerNotification)
├─ Custom stdin/stdout (PTY, xterm.js) -> core/api.md (createCliRenderer)
└─ Serve a TUI over SSH -> core/REFERENCE.md (@opentui/ssh)

“我需要调试/排查问题”

Troubleshooting?
├─ Runtime errors, crashes -> <framework>/gotchas.md
├─ Layout issues -> layout/REFERENCE.md + layout/patterns.md
├─ Input/focus issues -> keyboard/REFERENCE.md
└─ Repro + regression tests -> testing/REFERENCE.md

故障排查索引

• 终端清理、崩溃 -> core/gotchas.md
• 文本样式未生效 -> components/text-display.md
• 输入焦点/快捷键 -> keyboard/REFERENCE.md
• 布局错位 -> layout/REFERENCE.md
• 快照不稳定 -> testing/REFERENCE.md

有关组件命名差异和文本修饰符，请参阅 components/REFERENCE.md。

产品索引

框架

框架	入口文件	描述
Core	./references/core/REFERENCE.md	命令式 API，所有基元
React	./references/react/REFERENCE.md	用于声明式 TUI 的 React 协调器
Solid	./references/solid/REFERENCE.md	用于声明式 TUI 的 SolidJS 协调器

跨领域概念

概念	入口文件	描述
布局	./references/layout/REFERENCE.md	Yoga/Flexbox 布局系统
组件	./references/components/REFERENCE.md	按类别划分的组件参考
键盘	./references/keyboard/REFERENCE.md	底层键盘输入处理
Keymap	./references/keymap/REFERENCE.md	声明式分层按键绑定（@opentui/keymap）
动画	./references/animation/REFERENCE.md	基于时间线的动画
测试	./references/testing/REFERENCE.md	测试渲染器和快照

组件类别

类别	入口文件	组件
文本与显示	./references/components/text-display.md	text、ascii-font、image、time-to-first-draw、styled text、qr-code
容器	./references/components/containers.md	box、scrollbox、scrollbar、embedded-terminal、borders
输入	./references/components/inputs.md	input、textarea、select、tab-select、slider
代码与差异	./references/components/code-diff.md	code、line-number、diff、markdown、text-table

附加包

包	描述	文档
@opentui/keymap	分层键绑定／命令引擎（支持 Bun 或 Node，无需 FFI）	./references/keymap/REFERENCE.md
@opentui/qrcode	二维码组件	./references/components/text-display.md
@opentui/ssh	通过 SSH 提供 TUI 服务	./references/core/REFERENCE.md
@opentui/three	Three.js WebGPU 渲染器（原为 core/src/3d）	上游 packages/three
@opentui/examples	可运行示例（原为 core/src/examples）	上游 packages/examples

Core 还提供加载中／流式／录制的 Audio、原生 images、主机和终端 clipboard 服务，以及 OSC 桌面 notifications。

资源

仓库：https://github.com/anomalyco/opentui Core 文档：https://github.com/anomalyco/opentui/tree/main/packages/core/docs 示例：https://github.com/anomalyco/opentui/tree/main/packages/examples/src Awesome 列表：https://github.com/msmps/awesome-opentui