Ink 技能指南

概述

Ink 使用 Yoga 布局引擎（CLI 版 Flexbox）将 React 组件直接渲染至终端。它负责差异计算（diffing）、重新渲染以及终端 I/O 操作。组件可使用完整的 React 状态、副作用和 Hook —— 其心智模型与 Web 端 React 完全一致。要求 Node.js 22+ 和 React 19.2+ 作为对等依赖（peer dependencies）。

适用场景

当用户希望使用 JSX/React 语法构建 CLI/TUI 应用、终端仪表盘、交互式提示、带颜色的终端输出、加载指示器（spinners）、进度条或表格时，Ink 是理想选择。

• 使用 React 构建 CLI 应用
• 创建交互式终端 UI
• 渲染带样式的终端输出
• 在终端中处理键盘输入
• 基于 Flexbox/Yoga 的终端布局

快速开始

mkdir my-cli && cd my-cli
pnpm init
pnpm add ink react @types/react
pnpm add -D tsx typescript @types/node

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "outDir": "build"
  }
}

// index.tsx
import { render, Box, Text } from 'ink';

const App = () => (
  
    Hello, CLI!
  
);

render();

运行命令：node --import=tsx index.tsx

架构

Ink 使用 react-reconciler 作为其渲染核心，并以 yoga-layout 为布局引擎。它将组件挂载到一个虚拟终端中，与当前输出进行 diff，并将变更写入 stdout。这意味着：

• 支持完整的 React 状态与生命周期（如 useState、useEffect 等）
• 通过 Yoga 实现 Flexbox 布局（非 CSS —— 使用基于字符/行的整数坐标定位）
• 终端输出被视为仅追加（append-only）缓冲区，每次重渲染都会整体替换

组件

— 布局容器

import { Box, Text } from 'ink';

// 行布局（默认 flexDirection）

  Left
  Right


// 列布局并添加边框

  Title
  subtitle

关键 Box 属性：width、height、padding/paddingX/paddingY、borderStyle（single/double/round/classic/bold）、borderDimColor、gap、flexGrow、flexShrink、flexDirection（row/column）、justifyContent、alignItems。

— 样式化文本

// 直接设置样式
Success

// 嵌套 Text 元素

  Regular bold and inverse red


// 按宽度自动换行或截断
Truncated long text...

颜色支持：black/red/green/yellow/blue/magenta/cyan/white/gray 及其 Bright 变体（如 redBright 等）、十六进制（#ff0000）、rgb(255,0,0)。
背景色：在颜色名前加 bg 前缀（如 bgGreen、bgCyanBright）。
文本样式：bold、dim、italic、underline、strikethrough、inverse。

、

       // 插入 2 行空行
                   // 弹性占位符（flex spacer）
        // 固定高度占位符

Hook

useInput — 键盘输入处理

import { useInput } from 'ink';

useInput((input, key) => {
  if (key.escape || input === 'q') exit();           // 按 Escape 或 'q' 退出
  if (key.upArrow) navigateUp();
  if (key.downArrow) navigateDown();
  if (key.return) selectItem();
});

key 对象包含以下属性：upArrow、downArrow、leftArrow、rightArrow、return、escape、tab、backspace、delete、ctrl、shift、meta、space、pageUp、pageDown、home、end、f1–f12。

useApp — 应用级控制

import { useApp } from 'ink';
const { exit } = useApp();
exit();  // 或 exit(error)

useFocus — 焦点管理

import { useFocus } from 'ink';
const { isFocused } = useFocus({ autoFocus: true });
// 聚焦时应用不同样式
{label}

useStdin / useStdout — 流访问

const { stdin, isRawModeSupported } = useStdin();
const { stdout } = useStdout();

render() 配置项

render(, {
  exitOnCtrlC: true,         // 默认为 true
  debug: false,              // 显示 Yoga 布局调试信息
  patchConsole: true,        // 屏蔽 console 输出
});

常见模式

选择器 / 菜单（Select/Menu）

const Menu = ({ items, onSelect }) => {
  const [idx, setIdx] = useState(0);
  useInput((_, key) => {
    if (key.upArrow) setIdx(i => Math.max(0, i - 1));
    if (key.downArrow) setIdx(i => Math.min(items.length - 1, i + 1));
    if (key.return) onSelect(items[idx]);
  });
  return (
    
      {items.map((item, i) => (
        
          {i === idx ? '❯ ' : '  '}{item}
        
      ))}
    
  );
};

加载指示器（Spinner，配合 useEffect + setInterval）

const Spinner = () => {
  const [frame, setFrame] = useState(0);
  const chars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
  useEffect(() => {
    const id = setInterval(() => setFrame(f => (f + 1) % chars.length), 80);
    return () => clearInterval(id);
  }, []);
  return {chars[frame]} Loading...;
};

进度条（Progress Bar）

const ProgressBar = ({ percent }) => {
  const filled = '█'.repeat(Math.round(percent / 5));
  const empty = '░'.repeat(20 - filled.length);
  return {filled}{empty} {percent}%;
};

输入框（Input Field，结合 useInput + useState）

const Input = ({ onSubmit }) => {
  const [value, setValue] = useState('');
  useInput((input, key) => {
    if (key.return) { onSubmit(value); setValue(''); }
    else if (key.backspace) setValue(v => v.slice(0, -1));
    else if (input.length === 1 && !key.ctrl) setValue(v => v + input);
  });
  return ❯ {value}█;
};

资源

本技能包含以下文档：

• components.md — 完整组件及属性参考
• hooks.md — Hook API 详解与自定义 Hook 模式
• examples.md — 完整可运行示例（计数器、表格、加载状态、CLI 参数解析等）

关键约束

• Node.js >= 22（仅支持 ESM）
• React >= 19.2 为对等依赖
• 仅适用于真实终端环境（不支持浏览器）
• 布局基于 Yoga Flexbox — 单位为字符/行，而非像素
• 不支持滚动 — 终端视口即为画布
• 颜色表现依赖终端支持（大多数现代终端支持 256 色）
• 交互模式需启用 raw stdin（Ink 自动启用）