opentui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenTUI Platform Skill

OpenTUI平台技能

Consolidated skill for building terminal user interfaces with OpenTUI. Use decision trees below to find the right framework and components, then load detailed references.

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

Critical Rules

重要规则

Follow these rules in all OpenTUI code:

Use
create-tui
for new projects. See framework
```
REFERENCE.md
```
quick starts.

create-tui
options must come before arguments.

bunx create-tui -t react my-app

works,

bunx create-tui my-app -t react

does NOT.

Never call
process.exit()
directly. Use

renderer.destroy()

(see

core/gotchas.md

Text styling requires nested tags in React/Solid. Use modifier elements, not props (see
```
components/text-display.md
```
).

所有OpenTUI代码都需遵循以下规则：

新项目使用
create-tui
。请查看框架的
```
REFERENCE.md
```
快速入门。

create-tui
的选项必须放在参数之前。

bunx create-tui -t react my-app

可以正常运行，

bunx create-tui my-app -t react

则不行。

切勿直接调用
process.exit()
。请使用

renderer.destroy()

（详见

core/gotchas.md

）。

在React/Solid中设置文本样式需要嵌套标签。请使用修饰元素而非props（详见
```
components/text-display.md
```
）。

How to Use This Skill

如何使用本技能

Reference File Structure

参考文件结构

Framework references follow a 5-file pattern. Cross-cutting concepts are single-file guides.

Each framework in

./references/<framework>/

contains:

File	Purpose	When to Read
`REFERENCE.md`	Overview, when to use, quick start	Always read first
`api.md`	Runtime API, components, hooks	Writing code
`configuration.md`	Setup, tsconfig, bundling	Configuring a project
`patterns.md`	Common patterns, best practices	Implementation guidance
`gotchas.md`	Pitfalls, limitations, debugging	Troubleshooting

Cross-cutting concepts in

./references/<concept>/

have

REFERENCE.md

as the entry point.

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

./references/<framework>/

下的每个框架包含：

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

./references/<concept>/

下的跨领域概念以

REFERENCE.md

为入口文件。

Reading Order

阅读顺序

Start with
```
REFERENCE.md
```
for your chosen framework
Then read additional files relevant to your task:
- Building components ->
```
api.md
```
  +
```
components/<category>.md
```
- Setting up project ->
```
configuration.md
```
- Layout/positioning ->
```
layout/REFERENCE.md
```
- Troubleshooting ->
```
gotchas.md
```
  +
```
testing/REFERENCE.md
```

从所选框架的
```
REFERENCE.md
```
开始
然后阅读与任务相关的其他文件：
- 构建组件 ->
```
api.md
```
  +
```
components/<category>.md
```
- 项目初始化 ->
```
configuration.md
```
- 布局/定位 ->
```
layout/REFERENCE.md
```
- 问题排查 ->
```
gotchas.md
```
  +
```
testing/REFERENCE.md
```

Example Paths

示例路径

./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

./references/react/REFERENCE.md           # React开发从这里开始
./references/react/api.md              # React组件和钩子
./references/solid/configuration.md    # Solid项目设置
./references/components/inputs.md      # Input、Textarea、Select文档
./references/core/gotchas.md           # 核心调试技巧

Runtime Notes

运行时说明

OpenTUI runs on Bun and uses Zig for native builds. Read

./references/core/gotchas.md

for runtime requirements and build guidance.

OpenTUI基于Bun运行，并使用Zig进行原生构建。请查阅

./references/core/gotchas.md

了解运行时要求和构建指南。

Quick Decision Trees

快速决策树

"Which framework should I use?"

"我应该使用哪个框架？"

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)

我应该使用哪个框架？
├─ 我想要完全控制、最高性能、无框架开销
│  └─ core/（命令式API）
├─ 我熟悉React，想要使用熟悉的组件模式
│  └─ react/（React reconciler）
├─ 我想要细粒度响应式、最优重渲染
│  └─ solid/（Solid reconciler）
└─ 我正在基于OpenTUI构建库/框架
   └─ core/（命令式API）

"I need to display content"

"我需要展示内容"

Display content?
├─ Plain or styled text -> components/text-display.md
├─ Container with borders/background -> components/containers.md
├─ Scrollable content area -> components/containers.md (scrollbox)
├─ ASCII art banner/title -> components/text-display.md (ascii-font)
├─ Code with syntax highlighting -> components/code-diff.md
├─ Diff viewer (unified/split) -> components/code-diff.md
└─ Line numbers with diagnostics -> components/code-diff.md

展示内容？
├─ 纯文本或带样式文本 -> components/text-display.md
├─ 带边框/背景的容器 -> components/containers.md
├─ 可滚动内容区域 -> components/containers.md（scrollbox）
├─ ASCII艺术横幅/标题 -> components/text-display.md（ascii-font）
├─ 带语法高亮的代码 -> components/code-diff.md
├─ 差异查看器（统一/拆分模式） -> components/code-diff.md
└─ 带诊断信息的行号 -> components/code-diff.md

"I need user input"

"我需要用户输入"

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)
└─ Custom keyboard shortcuts -> keyboard/REFERENCE.md

用户输入？
├─ 单行文本框 -> components/inputs.md（input）
├─ 多行文本编辑器 -> components/inputs.md（textarea）
├─ 列表选择（垂直） -> components/inputs.md（select）
├─ 标签页选择（水平） -> components/inputs.md（tab-select）
└─ 自定义键盘快捷键 -> keyboard/REFERENCE.md

"I need layout/positioning"

"我需要布局/定位"

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

布局？
├─ Flexbox风格布局（行、列、换行） -> layout/REFERENCE.md
├─ 绝对定位 -> layout/patterns.md
├─ 响应终端尺寸 -> layout/patterns.md
├─ 内容居中 -> layout/patterns.md
└─ 复杂嵌套布局 -> layout/patterns.md

"I need animations"

"我需要动画"

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

动画？
├─ 基于时间线的动画 -> animation/REFERENCE.md
├─ 缓动函数 -> animation/REFERENCE.md
├─ 属性过渡 -> animation/REFERENCE.md
└─ 循环动画 -> animation/REFERENCE.md

"I need to handle input"

"我需要处理输入"

Input handling?
├─ Keyboard events (keypress, release) -> keyboard/REFERENCE.md
├─ Focus management -> keyboard/REFERENCE.md
├─ Paste events -> keyboard/REFERENCE.md
├─ Mouse events -> components/containers.md
└─ Text selection -> components/text-display.md

输入处理？
├─ 键盘事件（按键按下、释放） -> keyboard/REFERENCE.md
├─ 焦点管理 -> keyboard/REFERENCE.md
├─ 粘贴事件 -> keyboard/REFERENCE.md
├─ 鼠标事件 -> components/containers.md
└─ 文本选择 -> components/text-display.md

"I need to test my TUI"

"我需要测试我的TUI"

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

测试？
├─ 快照测试 -> testing/REFERENCE.md
├─ 交互测试 -> testing/REFERENCE.md
├─ 测试渲染器设置 -> testing/REFERENCE.md
└─ 调试测试 -> testing/REFERENCE.md

"I need to debug/troubleshoot"

"我需要调试/排查问题"

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

问题排查？
├─ 运行时错误、崩溃 -> <framework>/gotchas.md
├─ 布局问题 -> layout/REFERENCE.md + layout/patterns.md
├─ 输入/焦点问题 -> keyboard/REFERENCE.md
└─ 复现与回归测试 -> testing/REFERENCE.md

Troubleshooting Index

问题排查索引

Terminal cleanup, crashes ->
```
core/gotchas.md
```
Text styling not applying ->
```
components/text-display.md
```
Input focus/shortcuts ->
```
keyboard/REFERENCE.md
```
Layout misalignment ->
```
layout/REFERENCE.md
```
Flaky snapshots ->
```
testing/REFERENCE.md
```

For component naming differences and text modifiers, see

components/REFERENCE.md

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

有关组件命名差异和文本修饰符，请查看

components/REFERENCE.md

。

Product Index

产品索引

Frameworks

框架

Framework	Entry File	Description
Core	`./references/core/REFERENCE.md`	Imperative API, all primitives
React	`./references/react/REFERENCE.md`	React reconciler for declarative TUI
Solid	`./references/solid/REFERENCE.md`	SolidJS reconciler for declarative TUI

框架	入口文件	描述
Core	`./references/core/REFERENCE.md`	命令式API，包含所有原语
React	`./references/react/REFERENCE.md`	用于声明式TUI的React reconciler
Solid	`./references/solid/REFERENCE.md`	用于声明式TUI的SolidJS reconciler

Cross-Cutting Concepts

跨领域概念

Concept	Entry File	Description
Layout	`./references/layout/REFERENCE.md`	Yoga/Flexbox layout system
Components	`./references/components/REFERENCE.md`	Component reference by category
Keyboard	`./references/keyboard/REFERENCE.md`	Keyboard input handling
Animation	`./references/animation/REFERENCE.md`	Timeline-based animations
Testing	`./references/testing/REFERENCE.md`	Test renderer and snapshots

概念	入口文件	描述
布局	`./references/layout/REFERENCE.md`	Yoga/Flexbox布局系统
组件	`./references/components/REFERENCE.md`	按分类整理的组件参考
键盘	`./references/keyboard/REFERENCE.md`	键盘输入处理
动画	`./references/animation/REFERENCE.md`	基于时间线的动画
测试	`./references/testing/REFERENCE.md`	测试渲染器和快照

Component Categories

组件分类

Category	Entry File	Components
Text & Display	`./references/components/text-display.md`	text, ascii-font, styled text
Containers	`./references/components/containers.md`	box, scrollbox, borders
Inputs	`./references/components/inputs.md`	input, textarea, select, tab-select
Code & Diff	`./references/components/code-diff.md`	code, line-number, diff

分类	入口文件	组件
文本与显示	`./references/components/text-display.md`	text、ascii-font、带样式文本
容器	`./references/components/containers.md`	box、scrollbox、边框
输入组件	`./references/components/inputs.md`	input、textarea、select、tab-select
代码与差异	`./references/components/code-diff.md`	code、line-number、diff

Resources

资源

Repository: https://github.com/anomalyco/opentui Core Docs: https://github.com/anomalyco/opentui/tree/main/packages/core/docs Examples: https://github.com/anomalyco/opentui/tree/main/packages/core/src/examples Awesome List: https://github.com/msmps/awesome-opentui

代码仓库: https://github.com/anomalyco/opentui 核心文档: https://github.com/anomalyco/opentui/tree/main/packages/core/docs 示例: https://github.com/anomalyco/opentui/tree/main/packages/core/src/examples 精选列表: https://github.com/msmps/awesome-opentui