SuperAPI AI 工具集

react-ink

编程与开发

查看项目

更新于 10-26 16:17

技能介绍

React Ink 将 React 的组件模型带入终端。它不渲染到 DOM,而是使用自定义 React 渲染器,由 Yoga 布局引擎(React Native 使用的同一 Flexbox 实现)驱动,将界面输出到 stdout。你可以用 <Box> 做布局、<Text> 输出带样式的文本,用 useInput 处理键盘输入,用 useFocus 管理焦点,并继续使用熟悉的 React 模式,包括 hooks、状态、副作用、Suspense 和并发渲染。

适用场景:当用户想用 React 构建交互式 CLI 应用、需要带 Flexbox 布局的终端 UI 组件(Box、Text)、在终端中用 useInput 处理键盘输入、在终端 UI 元素之间管理焦点、在 CLI 中显示进度、加载动画或流式日志、用 create-ink-app 搭建新 CLI 项目、在终端中渲染带颜色/边框/格式的样式文本时触发。不适用于普通 React Web 或 React Native 开发,也不适用于只打印输出的简单 shell 脚本。

安装与初始化:运行 npm install ink react;或使用脚手架 npx create-ink-app my-cli,加 --typescript 可生成 TypeScript 版本。要求 Node >= 20、React >= 19。Ink v6+ 仅支持 ESM,package.json 中需要 "type": "module"。

核心概念:<Box> 是 Flexbox 容器(类似 display: flex 的 div),<Text> 渲染样式文本;只有 <Text> 和字符串字面量可以包含文本内容,不能直接在 <Box> 中放原始文本。布局引擎使用 Yoga,Box 支持 flexDirection、justifyContent、alignItems、gap、padding、margin、边框和绝对定位。useInput 捕获键盘事件,回调接收 (input, key),key 包含 leftArrow、return、escape、ctrl 等布尔标志,需要 stdin 处于 raw 模式。useFocus 将组件标记为可聚焦,Tab/Shift+Tab 循环焦点,useFocusManager 提供程序化控制,焦点状态可用于视觉高亮。<Static> 渲染持久化在动态区域上方的条目,适合已完成的日志行、测试结果或不应在重渲染时被清除的构建输出。render() 返回 {rerender, unmount, waitUntilExit, clear, cleanup};只要存在待处理的定时器、Promise 或 stdin 监听器,应用就会保持存活;通过 useApp().exit() 或 Ctrl+C 退出。

常见任务示例包括:渲染应用并处理退出;用 Box 构建布局;处理键盘输入;构建可聚焦的选择列表;用 Static 显示流式日志;用 Suspense 处理异步数据;用 useWindowSize 响应终端尺寸变化。

错误处理与注意事项:Box 内直接放原始文本会静默破坏渲染,必须用 <Text> 包裹所有文本;在非 TTY 环境(管道输入、CI)中 stdin 不支持 raw 模式时 useInput 不会触发,应先用 useStdin().isRawModeSupported 检查并提供非交互回退;Ink v6 仅支持 ESM,用 require('ink') 会抛出错误,必须使用 import 语法并在 package.json 中设置 "type": "module";<Static> 的条目需要稳定的 key,否则可能重复或消失;只要存在 stdin 监听器或定时器,应用就会保持存活,忘记清理定时器或调用 exit() 会导致 CLI 卡住。

技能还包含参考资料文件:components-api.md(Box、Text、Static、Transform、Newline、Spacer 的完整 props)、hooks-api.md(所有 hooks 的完整 API)、ecosystem.md(社区组件 ink-text-input、ink-select-input、ink-spinner、ink-gradient、ink-big-text)、patterns.md(游戏循环、聊天 UI、路由、并发渲染、子进程输出等高级模式),仅在任务需要时加载。