claude-code/docs/ui-components.md

UI 组件与前端分析

UI 架构

Claude Code 使用 React + Ink 构建 Terminal UI，组件层次分明。

graph TB
    subgraph 入口层
        Main[main.tsx<br/>CLI 入口]
        Ink[ink.ts<br/>Ink 渲染器包装]
        App[App.tsx<br/>根组件]
    end

    subgraph 全屏界面
        Screens[screens/<br/>Doctor, REPL, Resume]
    end

    subgraph 布局组件
        Fullscreen[FullscreenLayout.tsx]
        StatusLine[StatusLine.tsx<br/>状态栏]
        TextInput[TextInput.tsx<br/>文本输入]
        VimInput[VimTextInput.tsx<br/>Vim 输入]
    end

    subgraph 消息组件
        Messages[Messages.tsx<br/>消息列表]
        MessageRow[MessageRow.tsx<br/>消息行]
        Message[Message.tsx<br/>单条消息]
        MessageResp[MessageResponse.tsx<br/>响应消息]
        VirtualList[VirtualMessageList.tsx<br/>虚拟滚动列表]
    end

    subgraph 工具组件
        ToolLoader[ToolUseLoader.tsx<br/>工具加载器]
        FileEditDiff[FileEditToolDiff.tsx<br/>编辑差异]
        BashProgress[BashModeProgress.tsx<br/>Bash 进度]
        NotebookReject[NotebookEditToolUseRejectedMessage.tsx]
    end

    subgraph 对话框组件
        TrustDialog[TrustDialog/<br/>信任对话框]
        MCPDialog[MCPServerApprovalDialog.tsx<br/>MCP 审批]
        ExportDialog[ExportDialog.tsx<br/>导出对话框]
        AutoMode[AutoModeOptInDialog.tsx<br/>自动模式确认]
        CostDialog[CostThresholdDialog.tsx<br/>成本阈值]
        BridgeDialog[BridgeDialog.tsx<br/>桥接对话框]
    end

    subgraph 输入组件
        PromptInput[PromptInput/<br/>提示输入]
        BaseInput[BaseTextInput.tsx<br/>基础文本输入]
        SearchBox[SearchBox.tsx<br/>搜索框]
    end

    Main --> Ink --> App
    App --> Screens
    App --> Fullscreen
    App --> StatusLine
    App --> TextInput
    App --> Messages
    Messages --> VirtualList --> MessageRow --> Message
    App --> ToolLoader
    App --> PromptInput

组件分类

核心布局组件

组件	文件	功能
App	App.tsx	应用根组件
FullscreenLayout	FullscreenLayout.tsx	全屏布局
StatusLine	StatusLine.tsx	底部状态栏
TextInput	TextInput.tsx	主输入框
VimTextInput	VimTextInput.tsx	Vim 模式输入框
PromptInput	PromptInput/	提示输入组件
VirtualMessageList	VirtualMessageList.tsx	虚拟滚动消息列表

消息展示组件

组件	文件	功能
Messages	Messages.tsx	消息容器
MessageRow	MessageRow.tsx	消息行
Message	Message.tsx	单条消息
MessageResponse	MessageResponse.tsx	响应消息
MessageModel	MessageModel.tsx	模型信息
MessageTimestamp	MessageTimestamp.tsx	时间戳
CompactSummary	CompactSummary.tsx	压缩摘要
Markdown	Markdown.tsx	Markdown 渲染

工具相关组件

组件	文件	功能
ToolUseLoader	ToolUseLoader.tsx	工具使用加载动画
BashModeProgress	BashModeProgress.tsx	Bash 命令进度
FileEditToolDiff	FileEditToolDiff.tsx	文件编辑差异展示
FileEditToolUpdatedMessage	FileEditToolUpdatedMessage.tsx	编辑更新消息
StructuredDiff	StructuredDiff.tsx	结构化差异展示
StructuredDiffList	StructuredDiffList.tsx	差异列表

对话框组件

组件	功能
TrustDialog/	信任确认对话框
MCPServerApprovalDialog	MCP 服务器审批
MCPServerMultiselectDialog	MCP 多选对话框
ExportDialog	导出对话框
AutoModeOptInDialog	自动模式选择
AutoUpdater(AutoUpdaterWrapper)	自动更新
CostThresholdDialog	成本阈值确认
BridgeDialog	IDE 桥接对话框
IdleReturnDialog	空闲返回对话框
BypassPermissionsModeDialog	权限绕过确认
WorktreeExitDialog	Worktree 退出对话框
GlobalSearchDialog	全局搜索
HistorySearchDialog	历史搜索
QuickOpenDialog	快速打开

导航和信息组件

组件	功能
Stats	Stats.tsx 统计信息
Spinner	Spinner.tsx 加载动画
EffortIndicator	EffortIndicator.ts 思考力度指示
ModelPicker	ModelPicker.tsx 模型选择器
ThemePicker	ThemePicker.tsx 主题选择器
LanguagePicker	LanguagePicker.tsx 语言选择器
OutputStylePicker	OutputStylePicker.tsx 输出样式选择器
ThinkingToggle	ThinkingToggle.tsx 思考模式切换
FastIcon	FastIcon.tsx 快速模式图标
ContextVisualization	ContextVisualization.tsx 上下文可视化

团队和代理组件

组件	功能
CoordinatorAgentStatus	协调器代理状态
AgentProgressLine	代理进度行
TeammateViewHeader	队友视图头部
TaskListV2	任务列表 V2
PrBadge	PR 徽章

IDE 集成组件

组件	功能
IdeStatusIndicator	IDE 状态指示器
IdeAutoConnectDialog	IDE 自动连接
IdeOnboardingDialog	IDE 新手引导
ShowInIDEPrompt	在 IDE 中显示提示
FilePathLink	文件路径链接
LogSelector	日志选择器

Vim 模式

flowchart TD
    A[vim/] --> B[motions.ts<br/>移动操作]
    A --> C[operators.ts<br/>操作符]
    A --> D[textObjects.ts<br/>文本对象]
    A --> E[transitions.ts<br/>状态转换]
    A --> F[types.ts<br/>类型定义]

    G[VimTextInput.tsx] --> A
    H[useVimInput.ts] --> A

    I[vim 命令<br/>/commands/vim] --> J[切换 Vim 模式]

快捷键系统

flowchart TD
    A[keybindings/] --> B[defaultBindings.ts<br/>默认绑定]
    A --> C[parser.ts<br/>快捷键解析]
    A --> D[resolver.ts<br/>快捷键解析器]
    A --> E[match.ts<br/>快捷键匹配]
    A --> F[schema.ts<br/>Schema 定义]
    A --> G[template.ts<br/>模板]
    A --> H[validate.ts<br/>验证]
    A --> I[reservedShortcuts.ts<br/>保留快捷键]
    A --> J[shortcutFormat.ts<br/>格式化]
    A --> K[loadUserBindings.ts<br/>用户自定义]

    L[KeybindingContext.tsx] --> M[快捷键上下文]
    N[KeybindingProviderSetup.tsx] --> M
    O[useKeybinding.ts] --> P[使用快捷键]
    Q[useShortcutDisplay.ts] --> R[快捷键显示]

React Hooks

项目包含约 70 个自定义 React Hooks：

核心 Hooks

Hook	功能
useCanUseTool	工具权限检查
useMergedTools	合并内置和 MCP 工具
useMergedCommands	合并命令列表
useMergedClients	合并客户端
useMainLoopModel	主循环模型管理
useGlobalKeybindings	全局快捷键
useCommandKeybindings	命令快捷键
useTextInput	文本输入管理

状态 Hooks

Hook	功能
useDynamicConfig	动态配置
useSettings	设置管理
useSettingsChange	设置变更监听
useTasksV2	任务管理 V2
useTaskListWatcher	任务列表监听
useMemoryUsage	内存使用
useScheduledTasks	定时任务

IDE 集成 Hooks

Hook	功能
useIDEIntegration	IDE 集成
useIdeSelection	IDE 选择
useIdeAtMentioned	IDE @ 提及
useIdeConnectionStatus	IDE 连接状态
useIdeLogging	IDE 日志

会话 Hooks

Hook	功能
useReplBridge	REPL Bridge
useRemoteSession	远程会话
useSSHSession	SSH 会话
useSessionBackgrounding	会话后台化
useBackgroundTaskNavigation	后台任务导航

代理 Hooks

Hook	功能
useSwarmInitialization	集群初始化
useSwarmPermissionPoller	集群权限轮询
useTeammateViewAutoExit	队友视图自动退出

其他 Hooks

Hook	功能
useVoiceIntegration / useVoice	语音集成
useClipboardImageHint	剪贴板图片提示
usePasteHandler	粘贴处理
useTypeahead	自动补全
useHistorySearch	历史搜索
useDiffData	差异数据
useDiffInIDE	IDE 差异显示
useVirtualScroll	虚拟滚动
useTerminalSize	终端尺寸
useCommandQueue	命令队列

设计系统 (design-system/)

内置组件库提供一致的 UI 基础：

组件	功能
ThemedBox / ThemedText	主题感知的容器/文本
Dialog	对话框组件
Tabs	标签页组件
Button	按钮组件
ProgressBar	进度条
FuzzyPicker	模糊选择器
CheckboxInput	复选框输入

布局系统

使用 Yoga Layout（Flexbox 引擎）进行终端布局计算，支持：

• Flexbox 弹性布局
• 响应式终端尺寸适配
• 基于 useTerminalSize 的动态调整

主题系统

flowchart TD
    A[ThemeProvider] --> B[themeSetting<br/>用户设置]
    A --> C[systemTheme<br/>系统检测]
    A --> D[currentTheme<br/>实际渲染主题]

    B --> E[light / dark / auto]
    C --> F[终端主题监听<br/>自动检测变化]
    D --> G[动态切换<br/>实时预览]

Buddy 伙伴精灵 (buddy/)

终端伙伴精灵系统，提供视觉陪伴和交互反馈：

flowchart TD
    A[CompanionSprite<br/>主精灵组件] --> B[动画系统]
    A --> C[对话气泡]
    A --> D[交互功能]

    B --> E[idle<br/>空闲动画]
    B --> F[fidget<br/>活动动画]
    B --> G[blink<br/>眨眼动画]
    B --> H[15帧循环序列]

    C --> I[提示信息气泡<br/>~10秒显示]
    C --> J[淡出效果<br/>最后3秒渐暗]

    D --> K[pet<br/>抚摸交互]
    D --> L[burst<br/>Hearts 爆发动画<br/>~2.5秒]