Back to Details

opentui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenTUI/React Quick Reference

OpenTUI/React 快速参考

OpenTUI is a React renderer for terminal UIs using Yoga layout (like React Native). NOT React DOM or Ink.
OpenTUI是一个基于Yoga布局（类似React Native）的终端UI React渲染器。注意：不是React DOM或Ink。

Version Info

版本信息

  • Current: 0.1.69 (updated), Latest: 0.1.69
  • Context repo: 
    .context/repos/opentui
    (run 
    bun run sync-context
    if missing)
  • 当前版本： 0.1.69（已更新），最新版本： 0.1.69
  • 上下文仓库： 
    .context/repos/opentui
    （若缺失可运行
    bun run sync-context
    ）

Core Imports

核心导入

typescript
import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
import type { ScrollBoxRenderable, KeyEvent } from "@opentui/core";
typescript
import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
import type { ScrollBoxRenderable, KeyEvent } from "@opentui/core";

JSX Elements (Lowercase!)

JSX元素（必须小写！）

tsx
// CORRECT - OpenTUI intrinsics
<box style={{ flexDirection: "column" }}>
  <text fg="#ffffff">Hello</text>
  <scrollbox ref={scrollRef} focused />
</box>

// WRONG - Not OpenTUI
<div>, <span>, <Box>, <Text>
ElementPurposeKey Props
<box>
Container/layout
style
, 
id
, 
onMouse
<text>
Text content (strings only!)
fg
, 
bg
, 
selectable
<scrollbox>
Scrollable container
ref
, 
focused
<a>
Hyperlink (OSC8)
href
, 
fg
<input>
Text input
focused
, 
onInput
, 
onSubmit
<textarea>
Multi-line input
ref
, 
focused
, 
placeholder
tsx
// 正确写法 - OpenTUI原生元素
<box style={{ flexDirection: "column" }}>
  <text fg="#ffffff">Hello</text>
  <scrollbox ref={scrollRef} focused />
</box>

// 错误写法 - 不属于OpenTUI
<div>, <span>, <Box>, <Text>
元素用途关键属性
<box>
容器/布局
style
, 
id
, 
onMouse
<text>
文本内容（仅支持字符串！）
fg
, 
bg
, 
selectable
<scrollbox>
可滚动容器
ref
, 
focused
<a>
超链接（OSC8标准）
href
, 
fg
<input>
文本输入框
focused
, 
onInput
, 
onSubmit
<textarea>
多行输入框
ref
, 
focused
, 
placeholder

Critical Rules

重要规则

1. Text Only Accepts Strings

1. 
<text>
仅接受字符串

tsx
// WRONG - Cannot nest elements in <text>
<text>Hello <text fg="red">world</text></text>

// CORRECT - Use row box for inline styling
<box style={{ flexDirection: "row" }}>
  <text>Hello </text>
  <text fg="red">world</text>
</box>
tsx
// 错误写法 - 不能在<text>中嵌套元素
<text>Hello <text fg="red">world</text></text>

// 正确写法 - 使用row布局的box实现内联样式
<box style={{ flexDirection: "row" }}>
  <text>Hello </text>
  <text fg="red">world</text>
</box>

2. Always Check 
focused
in Keyboard Handlers

2. 键盘事件处理中必须检查
focused
状态

tsx
useKeyboard((key) => {
  if (!focused) return;  // MUST check first!
  if (key.name === "j") moveDown();
});
tsx
useKeyboard((key) => {
  if (!focused) return;  // 必须先检查！
  if (key.name === "j") moveDown();
});

3. Save Scroll Position Synchronously

3. 同步保存滚动位置

tsx
// WRONG - useEffect runs after render, scroll already reset
useEffect(() => { if (!focused) savedScroll.current = scrollRef.current?.scrollTop; }, [focused]);

// CORRECT - Save before state change
const handleSelect = () => {
  savedScroll.current = scrollRef.current?.scrollTop;  // Save first!
  onSelect(item);
};
tsx
// 错误写法 - useEffect在渲染后执行，滚动位置已重置
useEffect(() => { if (!focused) savedScroll.current = scrollRef.current?.scrollTop; }, [focused]);

// 正确写法 - 在状态变更前保存
const handleSelect = () => {
  savedScroll.current = scrollRef.current?.scrollTop;  // 先保存！
  onSelect(item);
};

Hyperlinks (New in 0.1.64+)

超链接（0.1.64+版本新增）

tsx
<text>
  Visit <a href="https://example.com">example.com</a> for more
</text>
Renders clickable links in terminals supporting OSC8 (iTerm2, Kitty, etc.).
tsx
<text>
  访问 <a href="https://example.com">example.com</a> 了解更多
</text>
在支持OSC8标准的终端（如iTerm2、Kitty等）中会渲染为可点击的链接。

Key Names

按键名称对照表

Key
key.name
Key
key.name
Enter
"return"
Arrows
"up"
, 
"down"
, 
"left"
, 
"right"
Escape
"escape"
Letters
"a"
, 
"b"
, 
"j"
, 
"k"
Tab
"tab"
Shift+Letter
"A"
, 
"B"
, 
"G"
按键
key.name
值		按键
key.name
值
回车键
"return"
方向键
"up"
, 
"down"
, 
"left"
, 
"right"
ESC键
"escape"
字母键
"a"
, 
"b"
, 
"j"
, 
"k"
Tab键
"tab"
Shift+字母
"A"
, 
"B"
, 
"G"

Scrollbox API

滚动框API

typescript
const scrollbox = scrollRef.current;
scrollbox.scrollTop           // Current position
scrollbox.scrollHeight        // Total content height
scrollbox.viewport.height     // Visible area
scrollbox.scrollTo(pos)       // Absolute scroll
scrollbox.scrollBy(delta)     // Relative scroll
scrollbox.getChildren()       // Find elements by ID
typescript
const scrollbox = scrollRef.current;
scrollbox.scrollTop           // 当前滚动位置
scrollbox.scrollHeight        // 内容总高度
scrollbox.viewport.height     // 可见区域高度
scrollbox.scrollTo(pos)       // 绝对滚动到指定位置
scrollbox.scrollBy(delta)     // 相对滚动指定距离
scrollbox.getChildren()       // 通过ID查找元素

Common Layout Patterns

常见布局模式

tsx
// Full-height with fixed header/footer
<box style={{ flexDirection: "column", height: "100%" }}>
  <box style={{ flexShrink: 0 }}>{/* Header */}</box>
  <scrollbox style={{ flexGrow: 1 }}>{/* Content */}</scrollbox>
  <box style={{ flexShrink: 0 }}>{/* Footer */}</box>
</box>

// Prevent unwanted spacing (Yoga quirk)
<box style={{ justifyContent: "flex-start", marginBottom: 0, paddingBottom: 0 }}>
tsx
// 带固定头部/底部的全屏布局
<box style={{ flexDirection: "column", height: "100%" }}>
  <box style={{ flexShrink: 0 }}>{/* 头部 */}</box>
  <scrollbox style={{ flexGrow: 1 }}>{/* 内容区 */}</scrollbox>
  <box style={{ flexShrink: 0 }}>{/* 底部 */}</box>
</box>

// 避免不必要的间距（Yoga布局的小问题）
<box style={{ justifyContent: "flex-start", marginBottom: 0, paddingBottom: 0 }}>

React DevTools (Optional)

React DevTools（可选）

bash
bun add --dev react-devtools-core@7
npx react-devtools@7  # Start standalone devtools
DEV=true bun run start  # Run app with devtools enabled
bash
bun add --dev react-devtools-core@7
npx react-devtools@7  # 启动独立的开发者工具
DEV=true bun run start  # 启用开发者工具后运行应用

Detailed References

详细参考文档

  • COMPONENTS.md - JSX elements, styling, text nesting
  • KEYBOARD.md - Keyboard handling, key names, focus patterns
  • SCROLLBOX.md - Scrollbox API, scroll preservation, windowed lists
  • LAYOUT.md - Flex layout, Yoga engine, spacing issues
  • PATTERNS.md - Screen navigation, state preservation, library compatibility
  • COMPONENTS.md - JSX元素、样式、文本嵌套规则
  • KEYBOARD.md - 键盘处理、按键名称、焦点模式
  • SCROLLBOX.md - 滚动框API、滚动位置保存、窗口化列表
  • LAYOUT.md - Flex布局、Yoga引擎、间距问题
  • PATTERNS.md - 屏幕导航、状态保存、库兼容性

xfeed Reference Files

xfeed参考文件

  • src/app.tsx
    - Screen routing, navigation history
  • src/components/PostList.tsx
    - Scrollbox with preservation
  • src/components/PostCard.tsx
    - Component styling, mouse handling
  • src/modals/FolderPicker.tsx
    - Windowed list pattern
  • src/hooks/useListNavigation.ts
    - Vim-style navigation
  • src/app.tsx
    - 屏幕路由、导航历史
  • src/components/PostList.tsx
    - 带状态保存的滚动框
  • src/components/PostCard.tsx
    - 组件样式、鼠标事件处理
  • src/modals/FolderPicker.tsx
    - 窗口化列表模式
  • src/hooks/useListNavigation.ts
    - Vim风格导航