first commit

2026-04-03 13:01:19 +08:00
commit 538eced414
2575 changed files with 645911 additions and 0 deletions
--- a/claude-code-中文Wiki/12-UI组件系统.md
+++ b/claude-code-中文Wiki/12-UI组件系统.md
@@ -0,0 +1,317 @@
+# UI 组件系统
+
+Claude Code 的 UI 组件系统是一个复杂的多层架构，结合了 React 组件、Ink 渲染器和终端 UI 技术。本文档详细介绍各层组件的设计和实现。
+
+## 目录结构
+
+```
+src/
+├── components/           # React 业务组件 (~140个)
+├── ink/                 # Ink 渲染器封装
+│   ├── ink.tsx         # 主渲染器 (1722行)
+│   ├── components/     # Ink 基础 UI 组件
+│   ├── events/         # 事件系统
+│   ├── hooks/          # React Hooks
+│   ├── layout/         # Yoga 布局引擎封装
+│   ├── termio/         # 终端 IO 处理
+│   └── screen.ts       # 屏幕缓冲区管理
+├── screens/            # 全屏 UI 屏幕
+│   ├── Doctor.tsx      # 诊断屏幕
+│   ├── REPL.tsx       # REPL 屏幕
+│   └── ResumeConversation.tsx  # 恢复对话屏幕
+└── outputStyles/       # 输出样式管理
+```
+
+## 1. Ink 渲染器 (ink/)
+
+Ink 是一个用于构建终端 UI 的 React 渲染器。Claude Code 对其进行了深度定制。
+
+### 1.1 主渲染器 (ink.tsx)
+
+**文件路径**: `src/ink/ink.tsx` (1722行)
+
+**核心类**: `Ink`
+
+**主要职责**:
+- 管理 React Fiber 树和渲染生命周期
+- 处理终端输入/输出
+- 管理帧缓冲区和屏幕更新
+- 处理鼠标跟踪和焦点管理
+
+**关键属性**:
+```typescript
+class Ink {
+  private readonly log: LogUpdate                    // 日志更新器
+  private readonly terminal: Terminal               // 终端连接
+  private scheduleRender: () => void                // 渲染调度
+  private container: FiberRoot                     // React 容器
+  private rootNode: dom.DOMElement                 // 根 DOM 节点
+  readonly focusManager: FocusManager               // 焦点管理器
+  private renderer: Renderer                       // 渲染器
+  private stylePool: StylePool                    // 样式池
+  private charPool: CharPool                       // 字符池
+  private hyperlinkPool: HyperlinkPool             // 超链接池
+  readonly selection: SelectionState               // 文本选择状态
+  private searchHighlightQuery: string             // 搜索高亮查询
+}
+```
+
+**渲染流程**:
+1. 接收 React 组件树
+2. 通过 React Reconciler 计算布局 (使用 Yoga 引擎)
+3. 将布局结果渲染到屏幕缓冲区
+4. 通过终端 IO 输出到终端
+
+### 1.2 Ink 组件 (ink/components/)
+
+#### Box 组件
+**文件**: `ink/components/Box.tsx`
+
+Box 是 Ink 的核心布局组件，类似于 Web 的 `div` 和 Flexbox 的结合。
+
+**主要属性**:
+```typescript
+type Props = {
+  flexDirection?: 'row' | 'column'       // 布局方向
+  flexGrow?: number                       // 增长系数
+  flexShrink?: number                     // 收缩系数
+  flexWrap?: 'nowrap' | 'wrap'           // 换行策略
+  gap?: number                           // 间距
+  overflowX?: 'visible' | 'hidden' | 'scroll'  // 水平溢出
+  overflowY?: 'visible' | 'hidden' | 'scroll'  // 垂直溢出
+  // 边距
+  margin?: number
+  marginX?: number
+  marginY?: number
+  padding?: number
+  // ... 边框、背景等样式
+}
+```
+
+**使用示例**:
+```tsx
+<Box flexDirection="column" gap={1} padding={2}>
+  <Text>Hello</Text>
+  <Box flexGrow={1}>Content</Box>
+</Box>
+```
+
+#### Button 组件
+**文件**: `ink/components/Button.tsx`
+
+Button 提供交互式按钮组件，支持焦点、悬停和激活状态。
+
+**状态类型**:
+```typescript
+type ButtonState = {
+  focused: boolean   // 是否获得焦点
+  hovered: boolean   // 是否悬停
+  active: boolean   // 是否激活
+}
+```
+
+**主要属性**:
+```typescript
+type Props = {
+  onAction: () => void          // 点击/回车/空格触发
+  tabIndex?: number            // Tab 顺序
+  autoFocus?: boolean          // 自动聚焦
+  children: ((state: ButtonState) => React.ReactNode) | React.ReactNode
+}
+```
+
+#### ScrollBox 组件
+**文件**: `ink/components/ScrollBox.tsx`
+
+ScrollBox 是支持滚动的容器组件，提供虚拟滚动功能。
+
+**句柄接口**:
+```typescript
+interface ScrollBoxHandle {
+  scrollTo(y: number): void                      // 滚动到指定位置
+  scrollBy(dy: number): void                     // 相对滚动
+  scrollToElement(el: DOMElement, offset?: number): void  // 滚动到元素
+  scrollToBottom(): void                         // 滚动到底部
+  getScrollTop(): number                         // 获取滚动位置
+  getScrollHeight(): number                      // 获取内容高度
+  getViewportHeight(): number                    // 获取视口高度
+  isSticky(): boolean                           // 是否吸附底部
+  subscribe(listener: () => void): () => void    // 订阅滚动变化
+  setClampBounds(min: number, max: number): void  // 设置边界
+}
+```
+
+**特性**:
+- Viewport Culling: 只渲染可见区域内的子元素
+- Sticky Scroll: 新内容自动滚动到底部
+- 节流渲染: 滚动事件节流，避免过度渲染
+
+#### TerminalFocusContext
+**文件**: `ink/components/TerminalFocusContext.tsx`
+
+提供终端焦点状态的 React Context。
+
+#### Other Components
+| 组件 | 文件 | 用途 |
+|------|------|------|
+| Text | Text.tsx | 文本显示，支持颜色、样式 |
+| Link | Link.tsx | 超链接渲染 |
+| Newline | Newline.tsx | 换行符 |
+| Spacer | Spacer.tsx | 空白间距 |
+| RawAnsi | RawAnsi.tsx | 原始 ANSI 转义序列 |
+| NoSelect | NoSelect.tsx | 禁用选择 |
+| ErrorOverview | ErrorOverview.tsx | 错误概览 |
+| AlternateScreen | AlternateScreen.tsx | 替代屏幕 |
+| App | App.tsx | 根应用组件 |
+
+### 1.3 ANSI 处理 (Ansi.tsx)
+
+**文件**: `src/ink/Ansi.tsx`
+
+Ansi 组件解析并渲染包含 ANSI 转义序列的字符串。
+
+**功能**:
+- 解析 SGR (Select Graphic Rendition) 参数
+- 支持颜色、背景色、粗体、斜体、下划线等样式
+- 支持超链接
+- Memoized 防止不必要的重渲染
+
+**属性**:
+```typescript
+type Props = {
+  children: string           // ANSI 字符串
+  dimColor?: boolean         // 是否淡化颜色
+}
+```
+
+### 1.4 事件系统 (ink/events/)
+
+```
+events/
+├── click-event.ts      # 点击事件
+├── focus-event.ts      # 焦点事件
+├── keyboard-event.ts   # 键盘事件
+├── input-event.ts      # 输入事件
+├── terminal-focus-event.ts  # 终端焦点事件
+├── terminal-event.ts   # 终端事件
+├── emitter.ts          # 事件发射器
+├── dispatcher.ts       # 事件分发器
+└── event.ts            # 事件基类
+```
+
+**键盘事件结构**:
+```typescript
+interface KeyboardEvent {
+  key: string           // 按键名称
+  ctrl: boolean         // Ctrl 修饰键
+  shift: boolean        // Shift 修饰键
+  alt: boolean          // Alt 修饰键
+  meta: boolean         // Meta 修饰键
+}
+```
+
+### 1.5 布局系统 (ink/layout/)
+
+使用 Facebook Yoga 布局引擎进行 Flexbox 布局计算。
+
+```
+layout/
+├── yoga.ts    # Yoga 引擎封装
+├── engine.ts  # 布局引擎
+├── node.ts    # 布局节点
+└── geometry.ts # 几何计算
+```
+
+### 1.6 终端 IO (ink/termio/)
+
+```
+termio/
+├── ansi.ts      # ANSI 转义序列解析
+├── parser.ts    # 终端输出解析
+├── dec.ts       # DEC 私有模式
+├── osc.ts       # Operating System Commands
+├── types.ts     # 类型定义
+└── tokenize.ts  # 标记化
+```
+
+## 2. React 业务组件 (components/)
+
+components 目录包含约 140 个 React 组件，提供高级 UI 功能。
+
+### 2.1 主要分类
+
+| 类别 | 示例组件 | 用途 |
+|------|----------|------|
+| 消息 | Message.tsx, MessageRow.tsx, Messages.tsx | 消息显示 |
+| 对话 | ChatInput.tsx, PromptInput/* | 用户输入 |
+| 设置 | Settings/*, ThemePicker.tsx | 设置界面 |
+| 诊断 | DiagnosticsDisplay.tsx, Doctor.tsx | 问题诊断 |
+| 权限 | permissions/* | 权限管理 |
+| MCP | MCPServerApprovalDialog.tsx, mcp/* | MCP 服务器 |
+| 差分 | StructuredDiff.tsx, FileEditToolDiff.tsx | 差异显示 |
+| 搜索 | GlobalSearchDialog.tsx, HistorySearchDialog.tsx | 搜索功能 |
+| 任务 | TaskListV2.tsx, tasks/* | 任务管理 |
+
+### 2.2 设计系统 (components/design-system/)
+
+```
+design-system/
+├── ThemedBox.tsx     # 主题化 Box
+├── ThemedText.tsx     # 主题化 Text
+├── ThemeProvider.tsx   # 主题提供者
+└── color.ts          # 颜色工具
+```
+
+### 2.3 核心组件示例
+
+#### Message.tsx (~79KB)
+消息行组件，处理 Assistant 和 User 消息的渲染。
+
+#### Spinner.tsx (~88KB)
+丰富的旋转指示器组件，支持多种变体。
+
+#### Stats.tsx (~153KB)
+统计信息显示面板。
+
+## 3. 全屏屏幕 (screens/)
+
+### 3.1 Doctor.tsx (73KB)
+诊断屏幕，显示系统健康状态和问题检测。
+
+### 3.2 REPL.tsx (896KB)
+最大的组件，REPL 交互界面，包含完整的命令行编辑功能。
+
+### 3.3 ResumeConversation.tsx (60KB)
+对话恢复屏幕，允许用户恢复之前的会话。
+
+## 4. 输出样式 (outputStyles/)
+
+```
+outputStyles/
+└── loadOutputStylesDir.ts
+```
+
+负责加载和管理输出样式目录。
+
+## 5. 核心概念
+
+### 5.1 帧缓冲区 (Frame)
+每帧包含完整的屏幕内容，由 Ink 渲染器管理双缓冲:
+- `frontFrame`: 当前显示帧
+- `backFrame`: 下一帧（渲染中）
+
+### 5.2 样式池 (StylePool)
+重用样式对象，减少内存分配。
+
+### 5.3 Yoga 布局
+使用 Yoga 引擎计算 Flexbox 布局，支持:
+- flexDirection, justifyContent, alignItems
+- flexGrow, flexShrink
+- margin, padding, gap
+- overflow 处理
+
+### 5.4 虚拟滚动
+ScrollBox 通过只渲染可见内容实现虚拟滚动，提升大列表性能。
+
+### 5.5 焦点管理
+FocusManager 跟踪键盘焦点，支持 Tab/Shift+Tab 导航。