AI 应用Agent 工作流开发工具MCP 服务【免费下载链接】cc-wf-studioCC Workflow Studio项目地址https://gitcode.com/gh_mirrors/cc/cc-wf-studio点击查看免费下载本文是 CC Workflow StudioVisual Studio Code 工作流可视化扩展Webview 前端中所有弹窗类组件必须遵循的设计规范与技术指南它规定了「每个新对话框都必须使用radix-ui/react-dialog」的硬性约束、一套覆盖 999910002 的四层 z-index 层级体系以及从实现骨架到验收清单的完整落地流程。阅读本文后你将掌握如何在 dialogs 组件目录 中编写符合规范的新对话框、如何正确编排父子嵌套对话框与确认/预览弹窗的叠放次序并能对照源码中的真实实现如ConfirmDialog、DiffPreviewDialog、SkillBrowserDialog写出可无障碍访问、层级无冲突的代码。一、规范定位与适用范围该规范文件位于仓库的.claude/rules/dialog-design.md通过 frontmatter 中的paths字段将适用范围锚定为paths: - packages/vscode/src/webview/src/components/dialogs/**也就是说凡是在 dialogs 目录 中新增的对话框组件包括 MCP 节点编辑、Skill 浏览与创建、Slack 分享与令牌输入、Sub-Agent 流程配置等都必须遵循此规范。从源码看该目录下目前已落地了 20 余个对话框组件例如组件文件所属功能McpNodeDialog.tsx/McpNodeEditDialog.tsxMCP 节点创建与编辑向导CodexNodeDialog.tsxCodex 节点配置SkillBrowserDialog.tsx/SkillCreationDialog.tsx/SkillNodeEditDialog.tsxSkill 浏览、创建与节点编辑SlackShareDialog.tsx/SlackManualTokenDialog.tsx/SlackConnectionRequiredDialog.tsxSlack 分享与令牌认证SubAgentFlowDialog.tsx/SubAgentCreationDialog.tsx/SubAgentFormDialog.tsxSub-Agent 流程与表单ConfirmDialog.tsx/AlertDialog.tsx/DiffPreviewDialog.tsx确认、警告与 AI 编辑差异预览SampleWorkflowDialog.tsx/WhatsNewDialog.tsx/ClaudeApiUploadDialog.tsx/AntigravityMcpRefreshDialog.tsx示例工作流、更新日志、API 上传等二、库选型Radix UI Dialog 是唯一强制选择规范第一条硬性要求是radix-ui/react-dialog是强制性的每个新对话框必须使用它历史遗留的自建对话框需要逐步迁移到 Radix UI。这一要求在依赖配置中可以得到印证webview/package.json 中已经声明了radix-ui/react-dialog: ^1.1.15并且整个 Radix 家族collapsible、dropdown-menu、popover、select、switch、toggle-group、tooltip都已就位说明 Radix 是该 Webview 前端的统一基础组件库。为什么强制使用 Radix UI Dialog规范给出了三条核心理由这也是实践中最容易踩坑的三个维度无障碍Accessibility自动处理ARIA 属性如aria-modal、aria-labelledby、aria-describedby、焦点管理打开时聚焦内容、关闭后归还焦点到触发器由库自动完成无需手写roledialog、tabIndex、焦点陷阱等样板代码。标准行为的一致性ESC 键关闭、点击遮罩Overlay关闭等交互在所有对话框中保持一致避免每个组件各写一套、行为互相打架。z-index 管理简单直接由于对话框通过Dialog.Portal渲染到body根部层级只取决于 Overlay 上显式设置的zIndex配合下文规范化的四层体系即可完全掌控。值得补充的是在 SkillCreationDialog.tsx 中可以观察到对 Radix 焦点与 ESC 行为的精细化定制提交期间通过onEscapeKeyDown中e.preventDefault()禁止关闭并通过onOpenAutoFocus{(e) e.preventDefault()}关闭自动聚焦让用户自然聚焦WhatsNewDialog.tsx 同样用onOpenAutoFocus阻止默认聚焦。这说明「库自动处理无障碍」不等于「不能定制」Radix 提供了足够的事件钩子供按需覆盖。三、四层 z-index 层级体系核心设计多对话框并存尤其是父子嵌套、确认弹窗叠加全屏预览时最棘手的问题是层级竞争。规范用一张表把整个系统收敛为4 个固定层级Layer z-index Purpose ───────────────────────────────────────────────────── Base 9999 Standalone dialogs, parent dialogs Nested 10000 Child dialogs nested inside a parent Confirm 10001 Confirmation dialogs PreviewOverlay 10002 Full-size previews opened from a confirmation dialogz-index用途示例9999独立对话框 / 父级对话框McpNodeDialog、SkillBrowserDialog、SlackShareDialog、SubAgentFlowDialog、SlackConnectionRequiredDialog、McpNodeEditDialog10000嵌套的子级对话框SkillCreationDialog位于SkillBrowserDialog内部、SlackManualTokenDialog位于SlackShareDialog内部、SubAgentFormDialog10001确认 / 警告对话框ConfirmDialog删除确认等、DiffPreviewDialogAI 编辑确认、AlertDialog10002从确认对话框打开的全尺寸预览DiffPreviewDialog内部的 Overview 预览、SampleWorkflowDialog的预览设计要点层级之间留出 1 的间隔而非紧密相邻既保证「谁后弹出谁压在上方」的直觉子级永远高于父级、确认框永远高于业务框、预览永远最高又为未来新增中间层级留出了整数余地。四、基础实现模式Radix UI Dialog 骨架规范给出了每个新对话框必须遵循的基础结构——把zIndex设置在Dialog.Overlay上这是整套层级体系能否生效的关键所在import * as Dialog from radix-ui/react-dialog; // z-index constants (recommended: manage in a shared constants file) const Z_INDEX { DIALOG_BASE: 9999, DIALOG_NESTED: 10000, DIALOG_CONFIRM: 10001, DIALOG_PREVIEW_OVERLAY: 10002, } as const; export function MyDialog({ isOpen, onClose }: Props) { return ( Dialog.Root open{isOpen} onOpenChange{(open) !open onClose()} Dialog.Portal Dialog.Overlay style{{ position: fixed, inset: 0, backgroundColor: rgba(0, 0, 0, 0.5), display: flex, alignItems: center, justifyContent: center, zIndex: Z_INDEX.DIALOG_BASE, // ← always set this }} Dialog.Content {/* content */} /Dialog.Content /Dialog.Overlay /Dialog.Portal /Dialog.Root ); }几个需要重点理解的点Dialog.Root的open/onOpenChange是受控开关onOpenChange{(open) !open onClose()}把「ESC 或点击遮罩触发的关闭」统一路由到同一个onClose这也是 ESC 与遮罩点击行为一致性的来源。Overlay 上必须设置zIndex规范在验收清单中明确列出。它承载了position: fixed; inset: 0的全屏遮罩display: flexalignItems/justifyContent: center负责将内容居中。Dialog.Content放在 Overlay 内部内容区样式按 VS Code 主题变量书写如var(--vscode-editor-background)、var(--vscode-panel-border)保证深浅色主题下都正确。常量管理的两种做法规范建议将 z-index 常量集中到共享常量文件统一管理。从源码看项目已出现两种落地方式内联对象常量SubAgentCreationDialog.tsx 定义了const Z_INDEX { DIALOG_BASE: 9999 } as const并在 Overlay 上引用SubAgentFormDialog.tsx 定义了DIALOG_NESTED: 10000。直接字面量多数组件如 ConfirmDialog.tsx 的zIndex: 10001、McpNodeDialog.tsx 的zIndex: 9999直接内联数值。两种方式规范都接受但推荐前一种一旦层级体系调整只需改动常量定义即可全局生效避免散落的魔法数字被漏改。五、嵌套对话框模式父级 子级当需要从父对话框内部再打开一个子对话框时例如在 Skill 浏览器中「 Create New Skill」、在 Slack 分享中手动输入 Token规范给出的组合方式非常直观// Parent dialog: z-index 9999 SkillBrowserDialog {/* Child dialog: z-index 10000 */} SkillCreationDialog / /SkillBrowserDialog从源码可以完整还原这条调用链SkillBrowserDialog.tsx 在自身Dialog.Content内部渲染SkillCreationDialog isOpen{isSkillCreationOpen} ... /父级 Overlay 的zIndex: 9999第 311 行子级 SkillCreationDialog.tsx 的 OverlayzIndex: 10000。SlackShareDialog.tsx 同样在根组件内嵌套SlackManualTokenDialog /后者 Overlay 为zIndex: 10000SlackManualTokenDialog.tsx。SubAgentCreationDialog.tsx 与 SubAgentFormDialog.tsx 也是同一套「父 9999 / 子 10000」的配对关系。要点子对话框在 JSX 上作为父对话框的「兄弟节点」渲染在Dialog.Content内但由于 Radix 的Dialog.Portal会把每个对话框独立挂载到body根部所以真正决定叠加顺序的是各自 Overlay 的zIndex——10000 9999子级必然压住父级且两个对话框的焦点与 ARIA 状态互不干扰。六、确认层与全屏预览层10001 / 10002最复杂的层级场景出现在「确认对话框 从确认框打开全屏预览」的组合中规范为这两个角色分配了最高的两层10001ConfirmConfirmDialog用于删除确认等破坏性操作DiffPreviewDialog用于 AI 编辑后的差异确认。两者 Overlay 均为zIndex: 10001ConfirmDialog.tsx、DiffPreviewDialog.tsx。10002PreviewOverlayDiffPreviewDialog中的「Overview 全尺寸预览」以及 SampleWorkflowDialog.tsx 的zIndex: 10002均属于此层。以 DiffPreviewDialog.tsx 为例源码展示了 10002 层的完整写法在确认对话框的Dialog.Portal之外再渲染一个独立的Dialog.Rootopen{showOverview}其 Overlay 使用更深的rgba(0, 0, 0, 0.6)遮罩并设置zIndex: 10002内容区占据92vw × 88vh的近似全屏空间通过onEscapeKeyDown{() setShowOverview(false)}单独管理 ESC 关闭。由于showOverview状态只在确认对话框内部维护这个「从确认框弹出的全屏预览」天然形成了 10001 → 10002 的递进关系关闭预览后焦点与状态又能正确回到确认层。关于焦点与主题色的补充实现细节从 ConfirmDialog.tsx 可以看到生产级实现还会关注这些点在Dialog.Content上设置onEscapeKeyDown{onCancel}确保 ESC 触发的关闭也走业务逻辑而不是 Radix 内部默认路径内容样式全部使用 VS Code 主题 CSS 变量var(--vscode-editor-background)背景、var(--vscode-panel-border)边框、var(--vscode-descriptionForeground)描述文字、var(--vscode-button-secondaryBackground)次级按钮等保证在任意 VS Code 主题下观感一致按钮 hover 通过onMouseEnter/onMouseLeave切换主题变量如--vscode-button-secondaryHoverBackground确认按钮使用var(--vscode-errorForeground)突出危险语义。七、新建对话框验收清单规范以 Checklist 形式给出了每个新对话框发布前的硬性验收项缺一不可使用radix-ui/react-dialog在Dialog.Overlay上设置zIndexz-index 取值遵循层级体系独立 / 父级对话框 → 9999嵌套子对话框 → 10000确认对话框 → 10001从确认对话框打开的全尺寸预览 → 10002ESC 键关闭行为正确点击遮罩关闭行为正确对照这条清单去审查现有实现可以验证规范的执行度所有文件都导入了radix-ui/react-dialog所有 Overlay 都设置了zIndexESC 关闭除了 Radix 默认行为外在ConfirmDialog、DiffPreviewDialog、AntigravityMcpRefreshDialog、AlertDialog、SkillCreationDialog等组件中都有显式的onEscapeKeyDown处理部分结合提交态拦截点击遮罩关闭则统一由onOpenChange{(open) !open onClose()}兜底。八、层级实测对照表源码级佐证规范末尾给出了一份「按层级归类」的实测对照表我结合源码逐一核实zIndex行号见各文件 Overlay 处对话框z-index角色源码位置ConfirmDialog10001确认对话框删除确认等ConfirmDialog.tsxDiffPreviewDialog10001AI 编辑差异确认DiffPreviewDialog.tsxDiffPreviewDialog的 Overview 预览10002从确认对话框打开的全屏预览DiffPreviewDialog.tsxSkillCreationDialog10000子级对话框SkillCreationDialog.tsxSlackManualTokenDialog10000子级对话框SlackManualTokenDialog.tsxSkillBrowserDialog9999父级对话框SkillBrowserDialog.tsxMcpNodeDialog9999独立对话框McpNodeDialog.tsxSubAgentFlowDialog9999父级对话框SubAgentFlowDialog.tsxSlackShareDialog9999父级对话框SlackShareDialog.tsxSlackConnectionRequiredDialog9999独立对话框SlackConnectionRequiredDialog.tsxMcpNodeEditDialog9999独立对话框McpNodeEditDialog.tsx此外规范未列出的AlertDialog10001也遵循了确认层约定说明这套体系在后续新增组件中被持续贯彻。完整组件集合见 dialogs 目录。九、常见误区与排错指南结合规范要点与源码实践编写新对话框时最容易出错的地方集中在以下几条忘记在 Overlay 上设置 zIndex内容Dialog.Content本身不参与层级竞争层级完全由 Overlay 决定。漏设时对话框会退回到文档流默认层级被其它弹层盖住。这是清单中专门列出的一条。子对话框 z-index 用错层级把嵌套子级写成 9999 会导致子级与父级同层、被后挂载的父级 Portal 盖住正确做法是子级固定 10000。在提交/加载期间允许 ESC 或遮罩关闭可能导致异步流程被中断、状态错乱。参考 SkillCreationDialog.tsx 在onEscapeKeyDown中preventDefault()的写法注意此时遮罩点击也应一并拦截可在onOpenChange回调中判断isSubmitting。自定义关闭逻辑绕开onOpenChangeESC、遮罩、代码显式关闭都应统一收敛到onOpenChange{(open) !open onClose()}否则会出现「ESC 关不掉 / 关一半」的怪异行为。硬编码非主题颜色对话框渲染在 VS Code 环境中背景、边框、文字应使用var(--vscode-*)主题变量否则暗色主题下会出现刺眼的白块或看不清的文字。结语这份设计规范的价值在于它把「多对话框并存时的层级竞争」这一前端经典难题收敛为固定四层 z-index 体系 Radix UI 标准实现 强制验收清单三件套让团队内所有成员尤其是 AI 编码助手在 dialogs 目录 新增组件时有一致的、可机械检查的标准。无论是新增一个独立对话框9999、在父级中嵌套子对话框10000还是叠加确认框与全屏预览10001 / 10002都可以按本文给出的骨架、源码范例与排错要点直接落地并确保无障碍、行为一致性与主题适配全部达标。赞分享AI 应用Agent 工作流开发工具MCP 服务【免费下载链接】cc-wf-studioCC Workflow Studio项目地址https://gitcode.com/gh_mirrors/cc/cc-wf-studio点击查看免费下载相关推荐终极指南如何高效管理listen项目中的UI层叠顺序终极指南如何高效管理listen项目中的UI层叠顺序 在现代前端开发中UI层叠顺序z index的管理往往是一个容易被忽视但至关重要的环节。对于Solagsd-2 前端 UI 指南伪元素 z-index 分层详解与负层级防盖字实践gsd 2 前端 UI 指南伪元素 z index 分层详解与负层级防盖字实践 本文基于 gsd 2 仓库内置的 userinterface wiki 技能规人工智能AI Agent代码智能体Agent 编排CLIAI 应用Metro UI CSS Overlay 组件全屏遮罩、Splash 启动屏与 z-index 层级实战指南Metro UI CSS Overlay 组件全屏遮罩、Splash 启动屏与 z index 层级实战指南 Overlay 是 Metro UI CSS 中前端UI组件上一篇micro 编辑器配色与语法高亮完全指南从 colorscheme 到自定义语法文件下一篇Madeira运行ULTRAKILL如何稳定帧率10个性能调优技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考