Back to Details

opentui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenTUI Core Development

OpenTUI 核心开发

Expert assistance for building terminal user interfaces with OpenTUI's imperative API.
为使用OpenTUI命令式API构建终端用户界面提供专业支持。

Quick Start

快速开始

bash
undefined
bash
undefined

Install dependencies

安装依赖

bun install @opentui/core
bun install @opentui/core

Zig is required for native modules

原生模块需要Zig支持

Install from: https://ziglang.org/download/

从以下地址安装：https://ziglang.org/download/

undefined
undefined

Core Components

核心组件

ComponentPurposeImport
TextRenderable
Text display with styling
import { TextRenderable } from "@opentui/core"
BoxRenderable
Container with borders/backgrounds
import { BoxRenderable } from "@opentui/core"
GroupRenderable
Layout containers
import { GroupRenderable } from "@opentui/core"
InputRenderable
Single-line text input
import { InputRenderable } from "@opentui/core"
SelectRenderable
Dropdown selection
import { SelectRenderable } from "@opentui/core"
ScrollBoxRenderable
Scrollable content areas
import { ScrollBoxRenderable } from "@opentui/core"
CodeRenderable
Syntax-highlighted code
import { CodeRenderable } from "@opentui/core"
组件用途导入方式
TextRenderable
带样式的文本显示
import { TextRenderable } from "@opentui/core"
BoxRenderable
带边框/背景的容器
import { BoxRenderable } from "@opentui/core"
GroupRenderable
布局容器
import { GroupRenderable } from "@opentui/core"
InputRenderable
单行文本输入
import { InputRenderable } from "@opentui/core"
SelectRenderable
下拉选择器
import { SelectRenderable } from "@opentui/core"
ScrollBoxRenderable
可滚动内容区域
import { ScrollBoxRenderable } from "@opentui/core"
CodeRenderable
语法高亮代码显示
import { CodeRenderable } from "@opentui/core"

Basic Pattern

基础模式

typescript
import { createCliRenderer } from "@opentui/core"
import { BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const box = new BoxRenderable()
  const text = new TextRenderable("Hello, OpenTUI!")
  box.add(text)

  renderer.getRoot().add(box)
  renderer.start()

  // Handle Ctrl+C to exit
  renderer.on("key", (key) => {
    if (key.name === "c" && key.ctrl) {
      renderer.destroy()
      process.exit(0)
    }
  })
}

main()
typescript
import { createCliRenderer } from "@opentui/core"
import { BoxRenderable, TextRenderable } from "@opentui/core"

async function main() {
  const renderer = await createCliRenderer()

  const box = new BoxRenderable()
  const text = new TextRenderable("Hello, OpenTUI!")
  box.add(text)

  renderer.getRoot().add(box)
  renderer.start()

  // 处理Ctrl+C退出
  renderer.on("key", (key) => {
    if (key.name === "c" && key.ctrl) {
      renderer.destroy()
      process.exit(0)
    }
  })
}

main()

Layout with Yoga (CSS Flexbox)

使用Yoga（CSS Flexbox）进行布局

typescript
import { Yoga } from "@opentui/core"

const group = new GroupRenderable()
group.setStyle({
  flexDirection: "column",
  justifyContent: "center",
  alignItems: "center",
  width: 80,
  height: 24,
})
See LAYOUT.md for all Yoga properties.
typescript
import { Yoga } from "@opentui/core"

const group = new GroupRenderable()
group.setStyle({
  flexDirection: "column",
  justifyContent: "center",
  alignItems: "center",
  width: 80,
  height: 24,
})
查看 LAYOUT.md 获取所有Yoga属性。

Input Handling

输入处理

Keyboard Events

键盘事件

typescript
renderer.on("key", (key: KeyEvent) => {
  if (key.name === "escape") process.exit(0)
  if (key.name === "c" && key.ctrl) process.exit(0)
})
typescript
renderer.on("key", (key: KeyEvent) => {
  if (key.name === "escape") process.exit(0)
  if (key.name === "c" && key.ctrl) process.exit(0)
})

Component Input Events

组件输入事件

typescript
const input = new InputRenderable()
input.on("submit", (value: string) => {
  console.log("Submitted:", value)
})
input.on("change", (value: string) => {
  console.log("Changed:", value)
})
See INPUT.md for complete event handling patterns.
typescript
const input = new InputRenderable()
input.on("submit", (value: string) => {
  console.log("Submitted:", value)
})
input.on("change", (value: string) => {
  console.log("Changed:", value)
})
查看 INPUT.md 获取完整的事件处理模式。

Styling & Colors

样式与颜色

typescript
import { Color, parseColor } from "@opentui/core"

// Create colors
const red = new Color(255, 0, 0)        // RGB integers
const blue = Color.fromInts(0, 0, 255) // Static method
const green = parseColor("#00FF00")     // Parse hex

// Apply styles
box.setStyle({
  backgroundColor: red,
  foregroundColor: blue,
  borderStyle: "double",
  paddingLeft: 2,
  paddingRight: 2,
})
See STYLING.md for color system and style properties.
typescript
import { Color, parseColor } from "@opentui/core"

// 创建颜色
const red = new Color(255, 0, 0)        // RGB整数
const blue = Color.fromInts(0, 0, 255) // 静态方法
const green = parseColor("#00FF00")     // 解析十六进制颜色

// 应用样式
box.setStyle({
  backgroundColor: red,
  foregroundColor: blue,
  borderStyle: "double",
  paddingLeft: 2,
  paddingRight: 2,
})
查看 STYLING.md 获取颜色系统和样式属性详情。

Animations

动画

typescript
import { Timeline } from "@opentui/core"

const box = new BoxRenderable()
const timeline = new Timeline({
  duration: 1000,
  easing: (t) => t * (2 - t), // easeOutQuad
})

timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
}, {
  onUpdate: () => renderer.render()
})

timeline.play()
See ANIMATION.md for animation patterns.
typescript
import { Timeline } from "@opentui/core"

const box = new BoxRenderable()
const timeline = new Timeline({
  duration: 1000,
  easing: (t) => t * (2 - t), // easeOutQuad
})

timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
}, {
  onUpdate: () => renderer.render()
})

timeline.play()
查看 ANIMATION.md 获取动画实现模式。

Debugging

调试

typescript
// Enable console overlay
import { consoleOverlay } from "@opentui/core"
renderer.attach(consoleOverlay())

// Now console.log() appears in terminal overlay
console.log("Debug: initialized")
typescript
// 启用控制台覆盖层
import { consoleOverlay } from "@opentui/core"
renderer.attach(consoleOverlay())

// 现在console.log()会显示在终端覆盖层中
console.log("Debug: initialized")

When to Use This Skill

何时使用该技能

Use 
/opentui
for:
  • Building TUIs with vanilla TypeScript/JavaScript
  • Creating custom OpenTUI components
  • Understanding core OpenTUI architecture
  • Performance optimization
  • Low-level debugging
For React-specific development, use 
/opentui-react
For SolidJS-specific development, use 
/opentui-solid
For project scaffolding and examples, use 
/opentui-projects
使用
/opentui
来：
  • 基于原生TypeScript/JavaScript构建TUI
  • 创建自定义OpenTUI组件
  • 理解OpenTUI核心架构
  • 性能优化
  • 底层调试
针对React相关开发，请使用
/opentui-react
针对SolidJS相关开发，请使用
/opentui-solid
针对项目脚手架和示例，请使用
/opentui-projects

Common Tasks

常见任务

  • Create a form: Use BoxRenderable + InputRenderable components with Yoga layout
  • Handle keyboard shortcuts: Listen to renderer "key" events
  • Make scrollable lists: Use ScrollBoxRenderable with dynamic content
  • Display code: Use CodeRenderable for syntax highlighting
  • Add borders: Use BoxRenderable with borderStyle property
  • 创建表单：结合BoxRenderable + InputRenderable组件与Yoga布局
  • 处理键盘快捷键：监听renderer的"key"事件
  • 制作可滚动列表：使用ScrollBoxRenderable加载动态内容
  • 显示代码：使用CodeRenderable实现语法高亮
  • 添加边框：为BoxRenderable设置borderStyle属性

Resources

资源

  • Component API - Complete component reference
  • Layout Guide - Yoga flexbox properties
  • Event Handling - Keyboard, mouse, clipboard
  • Styling - Colors, borders, spacing
  • Animations - Timeline and easing
  • Testing - Testing utilities
  • 组件API - 完整组件参考文档
  • 布局指南 - Yoga弹性盒属性
  • 事件处理 - 键盘、鼠标、剪贴板
  • 样式设计 - 颜色、边框、间距
  • 动画制作 - 时间线与缓动效果
  • 测试 - 测试工具

Key Knowledge Sources

核心知识来源

  • OpenTUI GitHub: https://github.com/sst/opentui
  • Context7: 
    /sst/opentui
    （168个代码片段，高可信度）
  • 研究资料: 
    .search-data/research/opentui/