Claude Code 对话框/弹窗 UI 样式汇总小结实用指南

作者：袖梨 2026-08-22

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Claude Code 对话框/弹窗 UI 样式汇总小结”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

目录
  • 一、权限类对话框
    • 1. 工具权限确认 (tool-permission)
    • 2. Sandbox 网络权限 (sandbox-permission)
    • 3. Worker Sandbox 权限 (worker-sandbox-permission)
    • 4. Worker 等待中指示器 (非阻塞)
  • 二、交互输入类对话框
    • 5. Hook Prompt 对话框 (prompt)
    • 6. MCP Elicitation 对话框 (elicitation)
  • 三、会话管理类对话框
    • 7. 成本阈值对话框 (cost)
    • 8. 闲置得到对话框 (idle-return)
  • 四、新功能引导类对话框
    • 9. IDE 集成引导 (ide-onboarding)
    • 10. Effort 选择引导 (effort-callout)
    • 11. 远程控制引导 (remote-callout)
    • 12. Ultraplan 选择对话框 (ultraplan-choice)
    • 13. Ultraplan 启动对话框 (ultraplan-launch)
  • 五、建议/推广类对话框
    • 14. LSP 插件建议 (lsp-recommendation)
    • 15. 插件提示 (plugin-hint)
    • 16. Desktop 升级引导 (desktop-upsell)
  • 六、消息操作类
    • 17. 消息选择器 / Rewind (message-selector)
  • 七、Ant 内部版（外部构建不可见）
    • 18. 模型切换引导 (model-switch)
    • 19. Undercover 模式引导 (undercover-callout)
  • 优先级总结

会话过程中，所有对话框由 focusedInputDialog 控制，按优先级依次弹出。以下是完整列表。

一、权限类对话框

1. 工具权限确认 (tool-permission)

触发时机： 工具（Bash、Write、Read 等）需用户批准时

UI 描述：

根据工具类型分发到不同的权限子组件：

  • BashPermissionRequest — 显示待执行的 shell 命令、工作目录、以 $ 开头的命令预览
  • FileEditPermissionRequest — 显示文件路径、diff 变更内容（+11/-22 颜色标记）
  • WebFetchPermissionRequest — 显示目标 URL

通用结构：

  • 覆盖层（Overlay），阻止主交互
  • 工具名称标签
  • 操作描述/预览区域
  • 底部分配 <Select> 选项："Allow"、"Allow and don't ask again"、"Deny"
  • Escape 拒绝、Enter 确认

组件： PermissionRequest.tsx → 分发到 BashPermissionRequest / FileEditPermissionRequest 等

2. Sandbox 网络权限 (sandbox-permission)

触发时机： 工具（WebFetch 等）请求访问外部网络时

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  Network request outside of sandbox                              │
│                                                                  │
│  Host: api.example.com                                           │ (dim)
│                                                                  │
│  Do you want to allow this connection?                           │
│                                                                  │
│  > Yes                                                           │
│    Yes, and don't ask again for api.example.com                  │
│    No, and tell Claude what to do differently (esc)              │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <PermissionDialog> 中
  • 主机名以 dim 颜色显示
  • 选项：Allow / Allow + 记住 / Deny + 引导

组件： SandboxPermissionRequest.tsx

3. Worker Sandbox 权限 (worker-sandbox-permission)

触发时机： Swarm worker 子代理请求网络访问，等待 leader 审批

UI 描述： 与 sandbox-permission 结构相同，但借助 mailbox 协议跨进程响应。选项借助 sendSandboxPermissionResponseViaMailbox 发送回 worker。

组件： SandboxPermissionRequest.tsx（同一组件）

4. Worker 等待中指示器 (非阻塞)

触发时机： Sub-agent 正在等待 leader 批准权限时显示

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  ⠋ Waiting for team lead approval                                │ (warning, bold)
│  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│  Tool: WebFetchTool                                              │ (dim)
│  Action: Fetch https://api.example.com/data                      │ (dim)
│  Permission request sent to team "my-team" leader                │
└──────────────────────────────────────────────────────────────────┘
  • 圆角边框 (borderStyle="round", borderColor="warning")
  • 顶部 Spinner + 警告颜色粗体文字
  • WorkerBadge（代理名称 + 颜色）

组件： WorkerPendingPermission.tsx

二、交互输入类对话框

5. Hook Prompt 对话框 (prompt)

触发时机： Hook 得到 type: "prompt" 需用户选择

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  [title]                                              [info]    │
│                                                                  │
│  Request message here...                                         │
│                                        [tool summary]            │ (dim)
│                                                                  │
│  > Option 1                                                      │
│    Option 2                                                      │
│    Option 3                                                      │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <PermissionDialog> 中
  • 标题 + 副标题（请求消息）
  • 右侧可选的 toolInputSummary（dim 颜色）
  • <Select> 选项列表，映射自 hook 得到的 request.options
  • 兼容 app:interrupt 快捷键中止

组件： PromptDialog.tsx

6. MCP Elicitation 对话框 (elicitation)

触发时机： MCP 服务器请求用户输入（表单、URL 确认、等待完成）

UI 描述： 三种模式：

表单模式：

┌──────────────────────────────────────────────────────────────────┐
│  MCP server "serverName" requests your input                     │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐    │
│  │  Text input field...                                     │    │
│  └──────────────────────────────────────────────────────────┘    │
│  ○ Option A    ○ Option B    ○ Option C                         │
│  ☑ Checkbox option                                              │
│                                                                  │
│  [Accept]    [Decline]                                           │
└──────────────────────────────────────────────────────────────────┘
  • 动态表单字段：文本输入、单选/多选枚举、布尔值、日期/时间选择器
  • 验证错误信息
  • 内联快捷键提示

等待模式： 域名 + Spinner + "Reload / Open in Browser / Close"

URL 确认： "MCP server wants to open a URL" + Accept/Decline

组件： ElicitationDialog.tsx（~1169 行，大型表单引擎）

三、会话管理类对话框

7. 成本阈值对话框 (cost)

触发时机： 当前会话 API 费用达到阈值时

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  You've spent $5 on the Anthropic API this session.              │
│                                                                  │
│  Learn more about how to monitor your spending:                  │
│  code.claude.com/docs/en/costs                                   │ (link)
│                                                                  │
│  > Got it, thanks!                                               │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <Dialog> 中
  • 显示当前会话消费金额
  • 提供费用监控文档链接
  • 单一确认选项，确认后设置 hasAcknowledgedCostThreshold: true

组件： CostThresholdDialog.tsx

8. 闲置得到对话框 (idle-return)

触发时机： 用户长时间离开后得到时

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  You've been away 25m and this conversation is 45K tokens.       │
│                                                                  │
│  If this is a new task, clearing context will save usage and     │
│  be faster.                                                      │
│                                                                  │
│  > Continue this conversation                                    │
│    Send message as a new conversation                            │
│    Don't ask me again                                            │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <Dialog> 中
  • 显示离开时长 + 当前 token 数
  • 三选一：继续 / 清空后发送 / 不再提示

组件： IdleReturnDialog.tsx

四、新功能引导类对话框

9. IDE 集成引导 (ide-onboarding)

触发时机： 首次检测到 IDE 扩展时

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  ✻ Welcome to Claude Code for Visual Studio Code                 │
│                                                                  │
│  installed extension v1.2.3                                      │ (dim)
│                                                                  │
│  • Claude has context about your open files and selected lines   │
│  • View code diffs in your IDE       +11 / -22                   │ (diff colors)
│  • Cmd+Esc to quickly launch                                     │
│  • Cmd+Option+K to send selection                                │
│                                                                  │
│  Press Enter to continue                                         │
└──────────────────────────────────────────────────────────────────┘
  • <Dialog> 颜色 theme "ide"
  • 项目符号列表介绍 IDE 集成功能
  • 差异标记颜色展示 diff 指示
  • Enter/Escape 关闭

组件： IdeOnboardingDialog.tsx

10. Effort 选择引导 (effort-callout)

触发时机： 首次采用 Opus 模型时（新功能引导）

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  Choose your effort level                                        │
│                                                                  │
│  Description text explaining what effort level means...          │
│                                                                  │
│  low · medium · high                                             │ (effort indicators)
│                                                                  │
│  > ● Medium (recommended)                                        │
│    ●●● High                                                      │
│    ○ Low                                                         │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <PermissionDialog> 中
  • 30 秒自动消失计时器
  • 三级 effort 选择

组件： EffortCallout.tsx

11. 远程控制引导 (remote-callout)

触发时机： 首次启用 Bridge/远程控制时

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  Remote Control                                                  │
│                                                                  │
│  Description text explaining how remote control works...         │
│  Your CLI session can be accessed from the web or other apps.    │
│                                                                  │
│  > Enable Remote Control for this session                        │
│    Never mind                                                    │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <PermissionDialog> 中
  • 仅显示一次（选择自动持久化）

组件： RemoteCallout.tsx

12. Ultraplan 选择对话框 (ultraplan-choice)

触发时机： 生成执行计划后，询问用户是否继续

UI 描述： 理解这一步时，显示远程执行计划内容供用户审查/批准。内置独立滚动（不与主 ScrollBox 联动）。接收 plan、sessionId、taskId 等回调。

组件： UltraplanChoiceDialog（非独立组件文件，REPL.tsx 内联采用）

13. Ultraplan 启动对话框 (ultraplan-launch)

触发时机： 用户确认后，启动 Ultraplan 远程执行前

UI 描述： 从实现思路看，触发 ultraplan 命令，回声显示公告行，传递断开连接桥接选项，远程会话就绪时附加状态更新。

组件： UltraplanLaunchDialog（非独立组件文件，REPL.tsx 内联采用）

五、建议/推广类对话框

14. LSP 插件建议 (lsp-recommendation)

触发时机： 检测到未安装 LSP 的文件类型时

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  LSP Plugin Recommendation                                       │
│                                                                  │
│  LSP provides code intelligence like go-to-definition and error  │
│  checking.                                                       │
│                                                                  │
│  Plugin: @anthropic/lsp-rust                                     │ (dim)
│  Triggered by: .rs files                                         │ (dim)
│                                                                  │
│  Would you like to install this LSP plugin?                      │
│                                                                  │
│  > Yes, install @anthropic/lsp-rust                               │ (bold)
│    No, not now                                                   │
│    Never for @anthropic/lsp-rust                                  │
│    Disable all LSP recommendations                               │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <PermissionDialog> 中
  • 30 秒自动消失（视为拒绝）

组件： LspRecommendationMenu.tsx

15. 插件提示 (plugin-hint)

触发时机： 外部命令建议安装插件时

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  Plugin Recommendation                                           │
│                                                                  │
│  The "my-command" command suggests installing a plugin.          │
│                                                                  │
│  Plugin: my-plugin                                               │ (dim)
│  Marketplace: official                                           │ (dim)
│                                                                  │
│  Would you like to install it?                                   │
│                                                                  │
│  > Yes, install my-plugin                                        │
│    No                                                            │
│    No, and don't show plugin installation hints again            │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <PermissionDialog> 中
  • 30 秒自动消失

组件： PluginHintMenu.tsx

16. Desktop 升级引导 (desktop-upsell)

触发时机： 最多 3 次启动时提示升级到桌面版

UI 描述：

┌──────────────────────────────────────────────────────────────────┐
│  Try Claude Code Desktop                                         │
│                                                                  │
│  Same Claude Code with visual diffs, live app preview, parallel  │
│  sessions, and more.                                             │
│                                                                  │
│  > Open in Claude Code Desktop                                   │
│    Not now                                                       │
│    Don't ask again                                               │
└──────────────────────────────────────────────────────────────────┘
  • 包裹在 <PermissionDialog> 中
  • 选择 "Open in Desktop" 后切换到 <DesktopHandoff> 子组件

组件： DesktopUpsellStartup.tsx

六、消息操作类

17. 消息选择器 / Rewind (message-selector)

触发时机： 用户按 Ctrl+O 或选择回退消息时

UI 描述：

─── Rewind ──────────────────────────────────────────────────────────  (color: suggestion)

  > #1  "Add error handling to the login flow"       +5 / -2  (file changes)
    #2  "Fix the bug in user authentication"          +3 / -1
    #3  "Refactor the database schema"                 (no changes)
                                                      (code rollback warning)
    Restore code and conversation
    Restore conversation
    Summarize from here: [____________________________]
    Never mind
──────────────────────────────────────────────────────────────────────
  • 非对话框包装器，内联选择器
  • 标题 "Rewind"（color="suggestion"）
  • 每个用户消息显示文件变更统计
  • 代码回滚警告
  • 底部恢复/摘要选项
  • 确认模式显示差异统计

组件： MessageSelector.tsx

七、Ant 内部版（外部构建不可见）

18. 模型切换引导 (model-switch)

条件编译： "external" === 'ant' 时存在

  • 提示用户切换模型
  • onDone(selection, modelAlias?) 回调可用来切换 mainLoopModel

组件： AntModelSwitchCallout

19. Undercover 模式引导 (undercover-callout)

条件编译： "external" === 'ant' 时存在

  • 解释 Undercover 自动启用
  • 轻松解除回调

组件： UndercoverAutoCallout

优先级总结

对话框按以下优先级弹出（高→低）：

优先级对话框条件
最高message-selector用户主动打开
1sandbox-permission网络权限请求
2tool-permission工具权限请求
3promptHook prompt 交互
4worker-sandbox-permissionWorker 网络权限
5elicitationMCP 表单输入
6cost费用阈值提示
7idle-return闲置得到
8ultraplan-choiceUltraplan 计划选择
9ultraplan-launchUltraplan 启动
10ide-onboardingIDE 引导
11model-switch模型切换（ant-only）
12undercover-calloutUndercover 引导（ant-only）
13effort-calloutEffort 选择引导
14remote-callout远程控制引导
15lsp-recommendationLSP 插件建议
16plugin-hint插件建议
最低desktop-upsell桌面版推广

结合项目来看，用户输入时高优先级对话框会暂缓弹出（hasSuppressedDialogs），输入完成后恢复。

落到代码里，到此这篇关于Claude Code 对话框/弹窗 UI 样式汇总小结的文章就介绍到这了,更多相关Claude Code 对话框/弹窗 内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多兼容脚本之家！

相关文章

精彩推荐