ink

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ink Platform Skill

Ink平台技能指南

Consolidated skill for building CLI applications with Ink (React for CLIs). Use decision trees below to find the right components and patterns, then load detailed references.

这是一份整合的技能指南，教你使用Ink（面向CLI的React框架）构建CLI应用。你可以通过下方的决策树找到合适的组件与模式，然后查看详细参考文档。

Critical Rules

核心规则

Follow these rules in all Ink code:

All text must be wrapped in
<Text>
. Raw strings outside
```
<Text>
```
will throw an error.
<Text>
only allows text nodes and nested
<Text>
. You cannot nest
```
<Box>
```
inside
```
<Text>
```
.

<Box>
is always
display: flex
. Think of every

<Box>

<div style="display: flex">

Use
useApp().exit()
to exit. Never call
```
process.exit()
```
directly from within components.
Install both
ink
and
react
. They are peer dependencies:
```
npm install ink react
```
.
<Static>
only renders new items. Changes to previously rendered items are ignored.

所有Ink代码都必须遵循以下规则：

所有文本必须包裹在
<Text>
组件中。
```
<Text>
```
之外的原始字符串会抛出错误。
<Text>
仅允许文本节点和嵌套的
<Text>
组件。你不能在
```
<Text>
```
中嵌套
```
<Box>
```
组件。

<Box>
组件默认
display: flex
。可以将每个

<Box>

看作是

<div style="display: flex">

。

使用
useApp().exit()
退出应用。绝不能在组件内部直接调用
```
process.exit()
```
。
同时安装
ink
和
react
。它们是对等依赖：
```
npm install ink react
```
。
<Static>
仅渲染新内容。已渲染内容的变更会被忽略。

How to Use This Skill

如何使用本技能指南

Reference File Structure

参考文档结构

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

./references/core/

contains:

File	Purpose	When to Read
`REFERENCE.md`	Overview, when to use, quick start	Always read first
`api.md`	render(), renderToString(), Instance, measureElement	Writing code
`configuration.md`	Render options, environment vars	Configuring an app
`patterns.md`	Common patterns, best practices	Implementation guidance
`gotchas.md`	Pitfalls, limitations, debugging	Troubleshooting

Component, hook, and concept references in

./references/<area>/

have

REFERENCE.md

as the entry point.

核心参考文档采用5文件模式。跨领域概念则以单文件指南呈现。

./references/core/

目录包含：

文件	用途	阅读时机
`REFERENCE.md`	概览、适用场景、快速开始	务必首先阅读
`api.md`	render()、renderToString()、Instance、measureElement	编写代码时
`configuration.md`	渲染选项、环境变量	配置应用时
`patterns.md`	常见模式、最佳实践	实现指导
`gotchas.md`	陷阱、限制、调试	故障排查时

./references/<area>/

目录下的组件、钩子和概念参考文档均以

REFERENCE.md

作为入口文件。

Reading Order

阅读顺序

Start with
```
core/REFERENCE.md
```
for project overview
Then read additional files relevant to your task:
- Building UI ->
```
components/REFERENCE.md
```
  + specific component files
- Handling input ->
```
hooks/input.md
```
- Layout/positioning ->
```
layout/REFERENCE.md
```
- App lifecycle ->
```
hooks/app-lifecycle.md
```
- Focus management ->
```
hooks/focus.md
```
- Testing ->
```
testing/REFERENCE.md
```
- Accessibility ->
```
accessibility/REFERENCE.md
```
- Troubleshooting ->
```
core/gotchas.md
```
- Best practices / rules ->
```
rules/RULES.md
```
  + specific rule files

首先阅读
```
core/REFERENCE.md
```
了解项目概览
然后根据你的任务阅读相关文件：
- 构建UI ->
```
components/REFERENCE.md
```
  + 具体组件文件
- 处理输入 ->
```
hooks/input.md
```
- 布局/定位 ->
```
layout/REFERENCE.md
```
- 应用生命周期 ->
```
hooks/app-lifecycle.md
```
- 焦点管理 ->
```
hooks/focus.md
```
- 测试 ->
```
testing/REFERENCE.md
```
- 无障碍访问 ->
```
accessibility/REFERENCE.md
```
- 故障排查 ->
```
core/gotchas.md
```
- 最佳实践/规则 ->
```
rules/RULES.md
```
  + 具体规则文件

Example Paths

示例路径

./references/core/REFERENCE.md             # Start here
./references/core/api.md                   # render(), renderToString()
./references/components/text.md            # <Text> component
./references/components/box.md             # <Box> component (layout, borders)
./references/hooks/input.md                # useInput hook
./references/layout/patterns.md            # Common layout recipes
./references/testing/REFERENCE.md          # ink-testing-library
./rules/RULES.md                           # Best practices entry point
./rules/performance.md                     # FPS, Static, memoization
./rules/components.md                      # Per-component rules
./rules/hooks.md                           # Per-hook rules
./rules/core.md                            # render(), errors, environment

./references/core/REFERENCE.md             # 从这里开始
./references/core/api.md                   # render()、renderToString()
./references/components/text.md            # <Text>组件
./references/components/box.md             # <Box>组件（布局、边框）
./references/hooks/input.md                # useInput钩子
./references/layout/patterns.md            # 常见布局方案
./references/testing/REFERENCE.md          # ink-testing-library
./rules/RULES.md                           # 最佳实践入口
./rules/performance.md                     # FPS、Static、 memoization
./rules/components.md                      # 组件专属规则
./rules/hooks.md                           # 钩子专属规则
./rules/core.md                            # render()、错误、环境

Quick Decision Trees

快速决策树

"I need to display content"

"我需要展示内容"

Display content?
├─ Plain or styled text -> components/text.md
├─ Container with layout -> components/box.md
├─ Container with borders -> components/box.md (borderStyle)
├─ Container with background color -> components/box.md (backgroundColor)
├─ Line breaks within text -> components/utilities.md (Newline)
├─ Flexible spacer -> components/utilities.md (Spacer)
├─ Permanent log output (completed items) -> components/utilities.md (Static)
└─ Transform text output (uppercase, gradient) -> components/utilities.md (Transform)

需要展示内容？
├─ 普通或带样式文本 -> components/text.md
├─ 带布局的容器 -> components/box.md
├─ 带边框的容器 -> components/box.md（borderStyle）
├─ 带背景色的容器 -> components/box.md（backgroundColor）
├─ 文本内换行 -> components/utilities.md（Newline）
├─ 弹性间隔符 -> components/utilities.md（Spacer）
├─ 永久日志输出（已完成内容） -> components/utilities.md（Static）
└─ 文本转换（大写、渐变） -> components/utilities.md（Transform）

"I need user input"

"我需要处理用户输入"

User input?
├─ Keyboard shortcuts/arrow keys -> hooks/input.md (useInput)
├─ Raw stdin access -> hooks/stdio.md (useStdin)
├─ Tab/Shift+Tab focus cycling -> hooks/focus.md (useFocus)
├─ Programmatic focus control -> hooks/focus.md (useFocusManager)
└─ Cursor positioning (IME) -> hooks/focus.md (useCursor)

需要处理用户输入？
├─ 键盘快捷键/方向键 -> hooks/input.md（useInput）
├─ 原始stdin访问 -> hooks/stdio.md（useStdin）
├─ Tab/Shift+Tab焦点循环 -> hooks/focus.md（useFocus）
├─ 程序化焦点控制 -> hooks/focus.md（useFocusManager）
└─ 光标定位（IME） -> hooks/focus.md（useCursor）

"I need layout/positioning"

"我需要布局/定位"

Layout?
├─ Horizontal row of elements -> layout/REFERENCE.md (flexDirection: row)
├─ Vertical stack of elements -> layout/REFERENCE.md (flexDirection: column)
├─ Centering content -> layout/patterns.md
├─ Spacing between elements -> layout/REFERENCE.md (gap, margin, padding)
├─ Fixed width/height -> components/box.md (width, height)
├─ Percentage sizing -> components/box.md (width: "50%")
├─ Min/max constraints -> components/box.md (minWidth, maxWidth, maxHeight)
├─ Push elements apart -> components/utilities.md (Spacer)
├─ Flex grow/shrink -> layout/REFERENCE.md (flexGrow, flexShrink)
├─ Wrapping content -> layout/REFERENCE.md (flexWrap)
├─ Overflow control -> components/box.md (overflow)
└─ Complex nested layouts -> layout/patterns.md

需要布局？
├─ 元素水平排列 -> layout/REFERENCE.md（flexDirection: row）
├─ 元素垂直堆叠 -> layout/REFERENCE.md（flexDirection: column）
├─ 内容居中 -> layout/patterns.md
├─ 元素间间距 -> layout/REFERENCE.md（gap、margin、padding）
├─ 固定宽高 -> components/box.md（width、height）
├─ 百分比尺寸 -> components/box.md（width: "50%"）
├─ 最小/最大约束 -> components/box.md（minWidth、maxWidth、maxHeight）
├─ 元素分散排列 -> components/utilities.md（Spacer）
├─ 弹性伸缩 -> layout/REFERENCE.md（flexGrow、flexShrink）
├─ 内容换行 -> layout/REFERENCE.md（flexWrap）
├─ 溢出控制 -> components/box.md（overflow）
└─ 复杂嵌套布局 -> layout/patterns.md

"I need to manage app lifecycle"

"我需要管理应用生命周期"

App lifecycle?
├─ Mount and render -> core/api.md (render)
├─ Render to string (no terminal) -> core/api.md (renderToString)
├─ Exit the app programmatically -> hooks/app-lifecycle.md (useApp, exit)
├─ Wait for app to finish -> core/api.md (waitUntilExit)
├─ Re-render with new props -> core/api.md (rerender)
├─ Unmount the app -> core/api.md (unmount)
└─ Write to stdout/stderr outside Ink -> hooks/stdio.md

需要管理应用生命周期？
├─ 挂载与渲染 -> core/api.md（render）
├─ 渲染为字符串（无终端） -> core/api.md（renderToString）
├─ 程序化退出应用 -> hooks/app-lifecycle.md（useApp、exit）
├─ 等待应用完成 -> core/api.md（waitUntilExit）
├─ 传入新属性重新渲染 -> core/api.md（rerender）
├─ 卸载应用 -> core/api.md（unmount）
└─ 在Ink外部写入stdout/stderr -> hooks/stdio.md

"I need to test my CLI"

"我需要测试我的CLI"

Testing?
├─ Render and check output -> testing/REFERENCE.md
├─ Simulate user input -> testing/REFERENCE.md (stdin.write)
├─ Snapshot testing -> testing/REFERENCE.md
└─ Check last rendered frame -> testing/REFERENCE.md (lastFrame)

需要测试？
├─ 渲染并检查输出 -> testing/REFERENCE.md
├─ 模拟用户输入 -> testing/REFERENCE.md（stdin.write）
├─ 快照测试 -> testing/REFERENCE.md
└─ 检查最后渲染帧 -> testing/REFERENCE.md（lastFrame）

"I need accessibility"

"我需要无障碍访问支持"

Accessibility?
├─ Screen reader support -> accessibility/REFERENCE.md
├─ ARIA roles (checkbox, button, etc.) -> accessibility/REFERENCE.md
├─ ARIA state (checked, disabled, etc.) -> accessibility/REFERENCE.md
├─ Custom screen reader labels -> accessibility/REFERENCE.md (aria-label)
└─ Hide from screen readers -> accessibility/REFERENCE.md (aria-hidden)

需要无障碍访问？
├─ 屏幕阅读器支持 -> accessibility/REFERENCE.md
├─ ARIA角色（复选框、按钮等） -> accessibility/REFERENCE.md
├─ ARIA状态（已选中、禁用等） -> accessibility/REFERENCE.md
├─ 自定义屏幕阅读器标签 -> accessibility/REFERENCE.md（aria-label）
└─ 对屏幕阅读器隐藏内容 -> accessibility/REFERENCE.md（aria-hidden）

"I need to debug/troubleshoot"

"我需要调试/故障排查"

Troubleshooting?
├─ Text rendering issues -> core/gotchas.md
├─ Layout problems -> core/gotchas.md + layout/REFERENCE.md
├─ Input not working -> core/gotchas.md + hooks/input.md
├─ Process not exiting -> core/gotchas.md
├─ CI rendering issues -> core/configuration.md (CI mode)
├─ Console output mixing -> core/configuration.md (patchConsole)
└─ Performance/flickering -> core/configuration.md + rules/performance.md

需要故障排查？
├─ 文本渲染问题 -> core/gotchas.md
├─ 布局问题 -> core/gotchas.md + layout/REFERENCE.md
├─ 输入无响应 -> core/gotchas.md + hooks/input.md
├─ 进程无法退出 -> core/gotchas.md
├─ CI环境渲染问题 -> core/configuration.md（CI模式）
├─ 控制台输出混乱 -> core/configuration.md（patchConsole）
└─ 性能/闪烁问题 -> core/configuration.md + rules/performance.md

"I want best practices / production-ready code"

"我需要最佳实践/生产级代码"

Best practices?
├─ General rules (critical) -> rules/RULES.md
├─ Performance (FPS, Static, memoization) -> rules/performance.md
├─ Per-component patterns & anti-patterns -> rules/components.md
├─ Per-hook patterns & gotchas -> rules/hooks.md
└─ render() / errors / environment behavior -> rules/core.md

需要最佳实践？
├─ 通用规则（关键） -> rules/RULES.md
├─ 性能优化（FPS、Static、memoization） -> rules/performance.md
├─ 组件模式与反模式 -> rules/components.md
├─ 钩子模式与陷阱 -> rules/hooks.md
└─ render()/错误/环境行为 -> rules/core.md

Troubleshooting Index

故障排查索引

Text outside
```
<Text>
```
->
```
core/gotchas.md
```
```
<Box>
```
inside
```
<Text>
```
->
```
core/gotchas.md
```
Process hanging/not exiting ->
```
core/gotchas.md
```
Console.log mixing with output ->
```
core/configuration.md
```
Layout misalignment ->
```
layout/REFERENCE.md
```
Input not received ->
```
hooks/input.md
```
+
```
rules/hooks.md
```
Focus not cycling ->
```
hooks/focus.md
```
+
```
rules/hooks.md
```
CI output issues ->
```
core/configuration.md
```
+
```
rules/core.md
```

Flickering/performance ->

core/configuration.md

rules/performance.md

Anti-patterns / pitfalls ->

rules/components.md

rules/hooks.md

rules/core.md

文本未包裹在
```
<Text>
```
中 ->
```
core/gotchas.md
```
```
<Box>
```
嵌套在
```
<Text>
```
中 ->
```
core/gotchas.md
```
进程挂起/无法退出 ->
```
core/gotchas.md
```
Console.log与Ink输出混合 ->
```
core/configuration.md
```
布局对齐问题 ->
```
layout/REFERENCE.md
```
输入无响应 ->
```
hooks/input.md
```
+
```
rules/hooks.md
```
焦点无法循环 ->
```
hooks/focus.md
```
+
```
rules/hooks.md
```
CI环境输出问题 ->
```
core/configuration.md
```
+
```
rules/core.md
```

闪烁/性能问题 ->

core/configuration.md

rules/performance.md

反模式/陷阱 ->

rules/components.md

、

rules/hooks.md

、

rules/core.md

Product Index

产品索引

Core

核心部分

Area	Entry File	Description
Core	`./references/core/REFERENCE.md`	Overview, quick start, project setup
API	`./references/core/api.md`	render, renderToString, Instance
Config	`./references/core/configuration.md`	Render options, environment variables
Patterns	`./references/core/patterns.md`	Common patterns and recipes
Gotchas	`./references/core/gotchas.md`	Pitfalls and debugging

领域	入口文件	描述
核心	`./references/core/REFERENCE.md`	概览、快速开始、项目搭建
API	`./references/core/api.md`	render、renderToString、Instance
配置	`./references/core/configuration.md`	渲染选项、环境变量
模式	`./references/core/patterns.md`	常见模式与方案
陷阱	`./references/core/gotchas.md`	常见陷阱与调试

Components

组件

Component	Entry File	Description
Overview	`./references/components/REFERENCE.md`	All components at a glance
Text	`./references/components/text.md`	Text display and styling
Box	`./references/components/box.md`	Layout, borders, backgrounds
Utilities	`./references/components/utilities.md`	Newline, Spacer, Static, Transform

组件	入口文件	描述
概览	`./references/components/REFERENCE.md`	所有组件一览
Text	`./references/components/text.md`	文本展示与样式
Box	`./references/components/box.md`	布局、边框、背景
工具组件	`./references/components/utilities.md`	Newline、Spacer、Static、Transform

Hooks

钩子

Hook	Entry File	Description
Overview	`./references/hooks/REFERENCE.md`	All hooks at a glance
Input	`./references/hooks/input.md`	useInput for keyboard handling
App Lifecycle	`./references/hooks/app-lifecycle.md`	useApp for exit control
Stdio	`./references/hooks/stdio.md`	useStdin, useStdout, useStderr
Focus	`./references/hooks/focus.md`	useFocus, useFocusManager, useCursor

钩子	入口文件	描述
概览	`./references/hooks/REFERENCE.md`	所有钩子一览
输入	`./references/hooks/input.md`	useInput键盘处理
应用生命周期	`./references/hooks/app-lifecycle.md`	useApp退出控制
标准IO	`./references/hooks/stdio.md`	useStdin、useStdout、useStderr
焦点	`./references/hooks/focus.md`	useFocus、useFocusManager、useCursor

Cross-Cutting Concepts

跨领域概念

Concept	Entry File	Description
Layout	`./references/layout/REFERENCE.md`	Yoga/Flexbox layout system
Layout Patterns	`./references/layout/patterns.md`	Common layout recipes
Testing	`./references/testing/REFERENCE.md`	ink-testing-library
Accessibility	`./references/accessibility/REFERENCE.md`	Screen reader & ARIA support

概念	入口文件	描述
布局	`./references/layout/REFERENCE.md`	Yoga/Flexbox布局系统
布局模式	`./references/layout/patterns.md`	常见布局方案
测试	`./references/testing/REFERENCE.md`	ink-testing-library
无障碍访问	`./references/accessibility/REFERENCE.md`	屏幕阅读器与ARIA支持

Best Practices (Rules)

最佳实践（规则）

Rule File	Entry File	Description
Overview	`./rules/RULES.md`	Entry point + 10 critical rules
Performance	`./rules/performance.md`	FPS tuning, Static, memoization, incremental rendering
Components	`./rules/components.md`	Box, Text, Static, Transform, Newline, Spacer rules
Hooks	`./rules/hooks.md`	useInput, useApp, useFocus, useCursor, useStdin rules
Core	`./rules/core.md`	render(), renderToString(), errors, CI, Kitty protocol

规则文件	入口文件	描述
概览	`./rules/RULES.md`	入口 + 10条关键规则
性能	`./rules/performance.md`	FPS调优、Static、memoization、增量渲染
组件	`./rules/components.md`	Box、Text、Static、Transform、Newline、Spacer规则
钩子	`./rules/hooks.md`	useInput、useApp、useFocus、useCursor、useStdin规则
核心	`./rules/core.md`	render()、renderToString()、错误、CI、Kitty协议

Resources

资源

Repository: https://github.com/vadimdemedes/ink npm: https://www.npmjs.com/package/ink Testing Library: https://github.com/vadimdemedes/ink-testing-library Create Ink App: https://github.com/vadimdemedes/create-ink-app

代码仓库: https://github.com/vadimdemedes/ink npm包: https://www.npmjs.com/package/ink 测试库: https://github.com/vadimdemedes/ink-testing-library 快速初始化工具: https://github.com/vadimdemedes/create-ink-app