尧图网站建设 
gpui-kit AlertDialog 实战用 Rust GPUI 构建中断式确认对话框的声明式与命令式 API【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kitAlertDialog 是 gpui-kit 中构建在 Dialog 之上的模态对话框组件专门用于打断用户操作、呈现重要信息并要求用户给出明确回应确认或取消。本文将以官方文档为骨架结合仓库中基础层crates/base与组件层crates/component的源码实现系统讲解 AlertDialog 的默认行为、两种 API 风格声明式triggercontent与命令式WindowExt::open_alert_dialog、按钮自动化封装DialogAction/DialogClose、关闭行为控制以及删除确认、会话超时、更新提示等典型实战场景。读完本文你将能够在自己的 GPUI 桌面应用中快速落地安全、一致、可无障碍访问的确认对话框。AlertDialog 的设计定位与 Dialog 的差异AlertDialog 是一个带预设意见的 Dialog。它复用了 Dialog 的完整底层能力但通过几个关键的保守默认值来保证中断式交互的安全性默认不可点击遮罩关闭Overlay 点击不关闭AlertDialog 默认要求用户明确作出回应防止误触导致重要内容被跳过可通过overlay_closable(true)开启见下文版本差异说明。默认无右上角关闭按钮避免用户在未读内容时随手关闭可用close_button(true)开启。底部按钮默认居中对齐而 Dialog 的按钮默认右对齐这一差异在组件层 doc 注释中有明确说明见 crates/component/src/dialog/alert_dialog.rs。API 精简聚焦于 alert提示与 confirmation确认两类场景提供on_ok/on_cancel/on_close等语义化回调。基础层实现进一步印证了这些默认值。在 crates/base/src/alert_dialog.rs 中AlertDialog::new直接构造了Dialog::new(cx) .role(Role::AlertDialog) .close_on_backdrop_press(false)即基础层为 AlertDialog 显式设置了Role::AlertDialog无障碍语义角色并默认禁用遮罩按压关闭。仓库还提供了对应测试 backdrop_is_not_closable_by_default在测试 Harness 中渲染 AlertDialog 后simulate_click点击 (20, 20) 位置断言close_requested仍为false从测试层面锁定了遮罩默认不可关闭这一行为。导入与根视图配置使用 AlertDialog 需要引入以下符号use gpui_kit::component::dialog::{AlertDialog, DialogAction, DialogClose}; use gpui_kit::component::WindowExt;与 Dialog 相同AlertDialog 的弹层渲染依赖应用根视图Root View提供 dialog layer。请先完成 Dialog 文档中的根视图配置步骤否则对话框无法正确挂载与显示。声明式 APItriggercontent声明式 API 将打开触发源与对话框内容都描述为元素树的一部分trigger(...)设置点击后打开对话框的元素content(...)通过构建器函数定义弹层内的内容。use gpui_kit::component::dialog::{AlertDialog, DialogHeader, DialogTitle, DialogDescription, DialogFooter}; AlertDialog::new(cx) .trigger( Button::new(show-alert) .outline() .label(Show Alert) ) .content(|content, _, cx| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Are you absolutely sure?)) .child(DialogDescription::new().child( This action cannot be undone. \ This will permanently delete your account from our servers. )) ) .child( DialogFooter::new() .child( Button::new(cancel) .outline() .label(Cancel) .on_click(|_, window, cx| { window.close_dialog(cx); }) ) .child( Button::new(ok) .primary() .label(Continue) .on_click(|_, window, cx| { window.push_notification(Confirmed, cx); window.close_dialog(cx); }) ) ) })从源码看trigger内部经由基础层的AlertDialogTrigger实现它在鼠标左键按下时通过handle.set_open(true, DialogChangeReason::TriggerPress, ...)打开对话框crates/base/src/alert_dialog.rs组件层则在.on_open(...)中调用window.open_dialog(...)将构建好的对话框内容注入 dialog layercrates/component/src/dialog/alert_dialog.rs。另外需要注意当使用trigger时.title()、.description()、.icon()、.button_props()会被忽略内容必须通过content(...)声明式定义组件层对此还提供了debug_assert_no_trigger的调试断言crates/component/src/dialog/alert_dialog.rs。用 DialogAction / DialogClose 自动触发动作声明式 API 的进阶用法是使用包装组件DialogAction与DialogClose它们会在子元素被点击时自动派发对应的动作Action从而免去手写window.close_dialog(cx)DialogClose包装按钮并触发Cancel动作调用on_cancel回调DialogAction包装按钮并触发Confirm动作调用on_ok回调。AlertDialog::new(cx) .trigger(Button::new(show-alert).outline().label(Show Alert)) .on_ok(|_, window, cx| { window.push_notification(You confirmed!, cx); true // Return true to close dialog }) .on_cancel(|_, window, cx| { window.push_notification(You cancelled!, cx); true }) .content(|content, _, cx| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Confirm Action)) .child(DialogDescription::new().child(Do you want to proceed?)) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(cancel).outline().label(Cancel) ) ) .child( DialogAction::new().child( Button::new(ok).primary().label(Confirm) ) ) ) })带来的好处无需手动调用close_dialog回调返回true即自动关闭自动连接到on_ok/on_cancel回调消除按钮与回调错位的隐患代码更声明式、更易读回调返回false时可以阻止关闭详见阻止关闭一节。底层实现印证了这种动作派发机制基础层的AlertDialogAction在点击时调用window.dispatch_action(Box::new(crate::actions::Confirm { secondary: false }), cx)而AlertDialogClose/AlertDialogCancel则派发crate::actions::Cancelcrates/base/src/alert_dialog.rs。派发后的动作会由 dialog layer 中的动作监听器匹配到对应回调组件层默认 footer 的 OK / Cancel 按钮同样通过派发Confirm/Cancel动作来驱动回调crates/component/src/dialog/dialog.rs。命令式 APIWindowExt::open_alert_dialog对于点击某个按钮后临时弹出确认框的简单场景命令式 API 更直接通过WindowExttrait 提供的open_alert_dialog方法在回调中链式配置标题、描述与回调window.open_alert_dialog(cx, |alert, _, _| { alert .title(Delete File) .description(Are you sure you want to delete this file? This action cannot be undone.) .show_cancel(true) .on_ok(|_, window, cx| { window.push_notification(File deleted, cx); true // Return true to close dialog }) })open_alert_dialog是WindowExttrait 上的方法位于 crates/component/src/window_ext.rs其实现委托给根视图的 dialog layer 完成挂载。命令式 API 适合快速确认当内容布局复杂、需要与其他组件组合时推荐声明式 API。自定义按钮DialogButtonProps 与 ButtonVariantDialogButtonProps允许统一配置 OK / Cancel 按钮的文本、样式变体与显隐常用于破坏性操作的二次确认use gpui_kit::component::dialog::DialogButtonProps; use gpui_kit::component::button::ButtonVariant; window.open_alert_dialog(cx, |alert, _, _| { alert .title(Delete Account) .description(This will permanently delete your account and all associated data.) .button_props( DialogButtonProps::default() .ok_text(Delete) .ok_variant(ButtonVariant::Danger) .cancel_text(Keep) .show_cancel(true) ) .on_ok(|_, window, cx| { window.push_notification(Account deleted, cx); true }) })其底层结构体定义在 crates/component/src/dialog/dialog.rs默认值为OK 文本OK、OK 变体ButtonVariant::Primary、Cancel 文本Cancel、Cancel 变体为默认变体、show_cancel false且默认on_ok/on_cancel都返回true即默认点击后关闭。render_ok/render_cancel会分别构建派发Confirm/Cancel动作的按钮crates/component/src/dialog/dialog.rs。文本的默认值还经由rust_i18n的t!(Dialog.ok)/t!(Dialog.cancel)提供国际化支持。在对话框中加入图标图标能显著提升警示类内容的注意力。声明式 API 中可将图标放入DialogHeader并居中use gpui_kit::component::{Icon, IconName, ActiveTheme}; AlertDialog::new(cx) .w(px(320.)) .trigger(Button::new(permission).outline().label(Request Permission)) .on_ok(|_, window, cx| { window.push_notification(Permission granted, cx); true }) .content(|content, _, cx| { content .child( DialogHeader::new() .items_center() .child( Icon::new(IconName::TriangleAlert) .size_10() .text_color(cx.theme().warning) ) .child(DialogTitle::new().child(Network Permission Required)) .child(DialogDescription::new().child( We need your permission to access the network to provide better services. )) ) .child( DialogFooter::new() .v_flex() .child( DialogAction::new().child( Button::new(allow).w_full().primary().label(Allow) ) ) .child( DialogClose::new().child( Button::new(deny).w_full().outline().label(Dont Allow) ) ) ) })命令式 API 则通过.icon(...)直接传入图标元素window.open_alert_dialog(cx, |alert, _, cx| { alert .title(Warning) .description(This action requires confirmation.) .icon( Icon::new(IconName::AlertTriangle) .size_8() .text_color(cx.theme().warning) ) })从 组件层build_surface的实现 可以看到当设置了 icon 或 title 时头部会以h_flex行布局包裹图标与v_flex的标题/描述列图标与文字自动对齐。仓库的 Story 示例中也有完整的图标 权限请求案例crates/story/src/stories/alert_dialog_story.rs可运行 story 应用直接观察效果。破坏性操作确认对于删除、清空等不可逆操作建议触发按钮使用.danger()变体、描述明确后果、确认按钮同样使用危险样式AlertDialog::new(cx) .trigger( Button::new(delete-account) .outline() .danger() .label(Delete Account) ) .on_ok(|_, window, cx| { window.push_notification(Account deletion initiated, cx); true }) .content(|content, _, _| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Delete Account)) .child(DialogDescription::new().child( This will permanently delete your account \ and all associated data. This action cannot be undone. )) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(cancel).flex_1().outline().label(Cancel) ) ) .child( DialogAction::new().child( Button::new(delete) .flex_1() .outline() .danger() .label(Delete Forever) ) ) ) })自定义宽度与布局默认宽度见 API 参考表文档约定为 420px。当默认宽度不满足需求时可通过width(...)或.w(...)显式指定AlertDialog::new(cx) .width(px(500.)) .trigger(Button::new(custom-width).label(Custom Width)) .content(|content, _, _| { // ... dialog content })注意组件层 Dialog 的DialogProps默认宽度定义为px(448.)crates/component/src/dialog/dialog.rs因此实际渲染宽度以显式传入的width为准若你需要严格的尺寸一致性建议始终显式设置宽度。控制关闭行为允许点击遮罩关闭window.open_alert_dialog(cx, |alert, _, _| { alert .title(Notice) .description(Click outside this dialog or press ESC to close it.) .overlay_closable(true) })版本差异提示组件层的overlay_closable方法目前已被标记为#[deprecated]AlertDialog backdrop dismissal is disabled by design见 crates/component/src/dialog/alert_dialog.rs其实现为空操作——即从设计上禁用了遮罩关闭基础层同样默认close_on_backdrop_press(false)。若你需要可遮罩关闭的弹层建议改用更灵活的 Dialog。禁用 ESC 键盘关闭ESC 默认可用keyboard默认true。对必须读完的重要通知类内容可禁用它window.open_alert_dialog(cx, |alert, _, _| { alert .title(Important Notice) .description(Please read this carefully before proceeding.) .keyboard(false) })显示关闭按钮window.open_alert_dialog(cx, |alert, _, _| { alert .title(Information) .description(Some information...) .close_button(true) })close_button默认false组件层AlertDialog::new中显式close_button(false)而通用 Dialog 的默认值是trueDialogProps默认close_button: true这正是 AlertDialog保守默认值的体现。阻止关闭让回调返回 falseon_ok/on_cancel回调返回true关闭对话框返回false则保持打开。这在进程运行中不允许关闭的场景非常有用use gpui_kit::component::dialog::DialogButtonProps; window.open_alert_dialog(cx, |alert, _, _| { alert .title(Processing) .description(A process is running. Click Continue to stop it or Cancel to keep waiting.) .button_props( DialogButtonProps::default() .ok_text(Continue) .show_cancel(true) ) .on_ok(|_, window, cx| { // Return false to prevent closing window.push_notification(Cannot close: Process still running, cx); false }) .on_cancel(|_, window, cx| { window.push_notification(Waiting..., cx); false }) })底层机制DialogButtonProps的on_ok/on_cancel默认实现就是|_, _, _| truecrates/component/src/dialog/dialog.rs因此未设置回调的按钮点击后自动关闭是默认行为一旦你提供了回调关闭与否就完全由返回值决定。关闭后的回调on_closeon_close在对话框关闭后触发位于on_ok或on_cancel之后适合做清理、埋点或导航window.open_alert_dialog(cx, |alert, _, _| { alert .title(Confirm) .description(Are you sure?) .on_close(|_, window, cx| { window.push_notification(Dialog closed, cx); }) })API 参考AlertDialog方法说明new(cx)创建新的 AlertDialog 实例trigger(element)设置触发元素点击后打开对话框声明式 APIcontent(builder)使用构建器函数设置对话框内容声明式 APItitle(title)设置对话框标题命令式 APIdescription(desc)设置对话框描述命令式 APIicon(icon)设置对话框图标命令式 APIbutton_props(props)设置按钮属性文本、样式、显隐show_cancel(bool)显示/隐藏取消按钮默认false另有便捷方法confirm()可直接开启取消按钮width(px)设置对话框宽度文档默认值420pxoverlay_closable(bool)允许点击遮罩关闭默认false注组件层该方法已废弃设计上禁用遮罩关闭close_button(bool)显示/隐藏关闭按钮默认falsekeyboard(bool)支持 ESC 关闭默认trueon_ok(callback)设置 OK 按钮回调返回true关闭对话框on_cancel(callback)设置取消按钮回调返回true关闭对话框on_close(callback)设置对话框关闭后的回调DialogButtonProps方法说明ok_text(text)设置 OK 按钮文本默认 OKcancel_text(text)设置取消按钮文本默认 Cancelok_variant(variant)设置 OK 按钮样式变体默认ButtonVariant::Primarycancel_variant(variant)设置取消按钮样式变体默认变体show_cancel(bool)显示/隐藏取消按钮默认falseon_ok(callback)设置 OK 回调返回true才关闭on_cancel(callback)设置取消回调返回true才关闭DialogAction包装组件子元素被点击时自动触发Confirm动作从而调用 AlertDialog 上设置的on_ok回调。DialogAction::new().child( Button::new(ok).primary().label(Confirm) )行为点击时派发Confirm动作 → 调用on_ok回调 → 回调返回true则关闭、返回false则保持打开。DialogClose包装组件子元素被点击时自动触发Cancel动作从而调用on_cancel回调。DialogClose::new().child( Button::new(cancel).outline().label(Cancel) )行为点击时派发Cancel动作 → 调用on_cancel回调 → 回调返回true或未设置回调则关闭、返回false则保持打开。完整实战示例删除确认两种 API命令式 API 按钮属性Button::new(delete) .danger() .label(Delete) .on_click(|_, window, cx| { window.open_alert_dialog(cx, |alert, _, _| { alert .title(Delete File?) .description(This action cannot be undone.) .button_props( DialogButtonProps::default() .ok_text(Delete) .ok_variant(ButtonVariant::Danger) .show_cancel(true) ) .on_ok(|_, window, cx| { // Perform delete operation window.push_notification(File deleted, cx); true }) }); })声明式 API DialogAction/DialogCloseAlertDialog::new(cx) .trigger(Button::new(delete).danger().label(Delete)) .on_ok(|_, window, cx| { window.push_notification(File deleted, cx); true }) .content(|content, _, cx| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Delete File?)) .child(DialogDescription::new().child(This action cannot be undone.)) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(cancel).outline().label(Cancel) ) ) .child( DialogAction::new().child( Button::new(delete-confirm).danger().label(Delete) ) ) ) })会话超时window.open_alert_dialog(cx, |alert, _, _| { alert .content(|content, _, _| { content .child( DialogHeader::new() .items_center() .child(DialogTitle::new().child(Session Expired)) .child(DialogDescription::new().child( Your session has expired due to inactivity. \ Please log in again to continue. )) ) .child( DialogFooter::new() .child( Button::new(sign-in) .label(Sign in) .primary() .flex_1() .on_click(|_, window, cx| { window.push_notification(Redirecting to login..., cx); window.close_dialog(cx); }) ) ) }) })更新可用AlertDialog::new(cx) .trigger(Button::new(update).outline().label(Update Available)) .on_cancel(|_, window, cx| { window.push_notification(Update postponed, cx); true }) .on_ok(|_, window, cx| { window.push_notification(Starting update..., cx); true }) .content(|content, _, _| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Update Available)) .child(DialogDescription::new().child( A new version (v2.0.0) is available. \ This update includes new features and bug fixes. )) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(later).flex_1().outline().label(Later) ) ) .child( DialogAction::new().child( Button::new(update-now).flex_1().primary().label(Update Now) ) ) ) })最佳实践选择合适的 API简单确认用命令式 APIopen_alert_dialog复杂布局或需要与其他组件组合时用声明式 APItriggercontent。优先使用 DialogAction / DialogClose用包装组件代替手写window.close_dialog()代码更声明式、回调自动关联、不易出错。明确表达意图为删除等危险操作使用合适的按钮变体如ButtonVariant::Danger向用户传达动作的严重性。提供清晰的描述确保用户理解操作的后果尤其是破坏性操作此操作不可撤销等文案必须显式给出。善用图标但不滥用图标能增强警告/错误的注意力但应在语义恰当的位置使用如警示图标配警示文案。谨慎阻止关闭仅在用户确认确实必要如进程运行中时才阻止关闭避免造成对话框无法关闭的挫败感。保持一致性全应用统一对话框按钮顺序与样式降低用户学习成本。相关组件与延伸阅读Dialog 完整文档 —— 更灵活的通用对话框组件含根视图配置DialogHeader / DialogTitle / DialogDescription / DialogFooter —— 声明式内容分区组件DialogAction / DialogClose —— 确认/取消动作的包装组件基础层实现WindowExt —— 提供open_alert_dialog等窗口级弹层入口AlertDialog Story 示例 —— 覆盖默认、命令式、图标、破坏性、自定义 footer、键盘禁用、阻止关闭等全部场景的完整演示代码基础层测试 —— 验证遮罩默认不可关闭行为的单元测试【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gpui-kit AlertDialog 实战：用 Rust + GPUI 构建中断式确认对话框的声明式与命令式 API
gpui-kit AlertDialog 实战用 Rust GPUI 构建中断式确认对话框的声明式与命令式 API【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kitAlertDialog 是 gpui-kit 中构建在 Dialog 之上的模态对话框组件专门用于打断用户操作、呈现重要信息并要求用户给出明确回应确认或取消。本文将以官方文档为骨架结合仓库中基础层crates/base与组件层crates/component的源码实现系统讲解 AlertDialog 的默认行为、两种 API 风格声明式triggercontent与命令式WindowExt::open_alert_dialog、按钮自动化封装DialogAction/DialogClose、关闭行为控制以及删除确认、会话超时、更新提示等典型实战场景。读完本文你将能够在自己的 GPUI 桌面应用中快速落地安全、一致、可无障碍访问的确认对话框。AlertDialog 的设计定位与 Dialog 的差异AlertDialog 是一个带预设意见的 Dialog。它复用了 Dialog 的完整底层能力但通过几个关键的保守默认值来保证中断式交互的安全性默认不可点击遮罩关闭Overlay 点击不关闭AlertDialog 默认要求用户明确作出回应防止误触导致重要内容被跳过可通过overlay_closable(true)开启见下文版本差异说明。默认无右上角关闭按钮避免用户在未读内容时随手关闭可用close_button(true)开启。底部按钮默认居中对齐而 Dialog 的按钮默认右对齐这一差异在组件层 doc 注释中有明确说明见 crates/component/src/dialog/alert_dialog.rs。API 精简聚焦于 alert提示与 confirmation确认两类场景提供on_ok/on_cancel/on_close等语义化回调。基础层实现进一步印证了这些默认值。在 crates/base/src/alert_dialog.rs 中AlertDialog::new直接构造了Dialog::new(cx) .role(Role::AlertDialog) .close_on_backdrop_press(false)即基础层为 AlertDialog 显式设置了Role::AlertDialog无障碍语义角色并默认禁用遮罩按压关闭。仓库还提供了对应测试 backdrop_is_not_closable_by_default在测试 Harness 中渲染 AlertDialog 后simulate_click点击 (20, 20) 位置断言close_requested仍为false从测试层面锁定了遮罩默认不可关闭这一行为。导入与根视图配置使用 AlertDialog 需要引入以下符号use gpui_kit::component::dialog::{AlertDialog, DialogAction, DialogClose}; use gpui_kit::component::WindowExt;与 Dialog 相同AlertDialog 的弹层渲染依赖应用根视图Root View提供 dialog layer。请先完成 Dialog 文档中的根视图配置步骤否则对话框无法正确挂载与显示。声明式 APItriggercontent声明式 API 将打开触发源与对话框内容都描述为元素树的一部分trigger(...)设置点击后打开对话框的元素content(...)通过构建器函数定义弹层内的内容。use gpui_kit::component::dialog::{AlertDialog, DialogHeader, DialogTitle, DialogDescription, DialogFooter}; AlertDialog::new(cx) .trigger( Button::new(show-alert) .outline() .label(Show Alert) ) .content(|content, _, cx| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Are you absolutely sure?)) .child(DialogDescription::new().child( This action cannot be undone. \ This will permanently delete your account from our servers. )) ) .child( DialogFooter::new() .child( Button::new(cancel) .outline() .label(Cancel) .on_click(|_, window, cx| { window.close_dialog(cx); }) ) .child( Button::new(ok) .primary() .label(Continue) .on_click(|_, window, cx| { window.push_notification(Confirmed, cx); window.close_dialog(cx); }) ) ) })从源码看trigger内部经由基础层的AlertDialogTrigger实现它在鼠标左键按下时通过handle.set_open(true, DialogChangeReason::TriggerPress, ...)打开对话框crates/base/src/alert_dialog.rs组件层则在.on_open(...)中调用window.open_dialog(...)将构建好的对话框内容注入 dialog layercrates/component/src/dialog/alert_dialog.rs。另外需要注意当使用trigger时.title()、.description()、.icon()、.button_props()会被忽略内容必须通过content(...)声明式定义组件层对此还提供了debug_assert_no_trigger的调试断言crates/component/src/dialog/alert_dialog.rs。用 DialogAction / DialogClose 自动触发动作声明式 API 的进阶用法是使用包装组件DialogAction与DialogClose它们会在子元素被点击时自动派发对应的动作Action从而免去手写window.close_dialog(cx)DialogClose包装按钮并触发Cancel动作调用on_cancel回调DialogAction包装按钮并触发Confirm动作调用on_ok回调。AlertDialog::new(cx) .trigger(Button::new(show-alert).outline().label(Show Alert)) .on_ok(|_, window, cx| { window.push_notification(You confirmed!, cx); true // Return true to close dialog }) .on_cancel(|_, window, cx| { window.push_notification(You cancelled!, cx); true }) .content(|content, _, cx| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Confirm Action)) .child(DialogDescription::new().child(Do you want to proceed?)) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(cancel).outline().label(Cancel) ) ) .child( DialogAction::new().child( Button::new(ok).primary().label(Confirm) ) ) ) })带来的好处无需手动调用close_dialog回调返回true即自动关闭自动连接到on_ok/on_cancel回调消除按钮与回调错位的隐患代码更声明式、更易读回调返回false时可以阻止关闭详见阻止关闭一节。底层实现印证了这种动作派发机制基础层的AlertDialogAction在点击时调用window.dispatch_action(Box::new(crate::actions::Confirm { secondary: false }), cx)而AlertDialogClose/AlertDialogCancel则派发crate::actions::Cancelcrates/base/src/alert_dialog.rs。派发后的动作会由 dialog layer 中的动作监听器匹配到对应回调组件层默认 footer 的 OK / Cancel 按钮同样通过派发Confirm/Cancel动作来驱动回调crates/component/src/dialog/dialog.rs。命令式 APIWindowExt::open_alert_dialog对于点击某个按钮后临时弹出确认框的简单场景命令式 API 更直接通过WindowExttrait 提供的open_alert_dialog方法在回调中链式配置标题、描述与回调window.open_alert_dialog(cx, |alert, _, _| { alert .title(Delete File) .description(Are you sure you want to delete this file? This action cannot be undone.) .show_cancel(true) .on_ok(|_, window, cx| { window.push_notification(File deleted, cx); true // Return true to close dialog }) })open_alert_dialog是WindowExttrait 上的方法位于 crates/component/src/window_ext.rs其实现委托给根视图的 dialog layer 完成挂载。命令式 API 适合快速确认当内容布局复杂、需要与其他组件组合时推荐声明式 API。自定义按钮DialogButtonProps 与 ButtonVariantDialogButtonProps允许统一配置 OK / Cancel 按钮的文本、样式变体与显隐常用于破坏性操作的二次确认use gpui_kit::component::dialog::DialogButtonProps; use gpui_kit::component::button::ButtonVariant; window.open_alert_dialog(cx, |alert, _, _| { alert .title(Delete Account) .description(This will permanently delete your account and all associated data.) .button_props( DialogButtonProps::default() .ok_text(Delete) .ok_variant(ButtonVariant::Danger) .cancel_text(Keep) .show_cancel(true) ) .on_ok(|_, window, cx| { window.push_notification(Account deleted, cx); true }) })其底层结构体定义在 crates/component/src/dialog/dialog.rs默认值为OK 文本OK、OK 变体ButtonVariant::Primary、Cancel 文本Cancel、Cancel 变体为默认变体、show_cancel false且默认on_ok/on_cancel都返回true即默认点击后关闭。render_ok/render_cancel会分别构建派发Confirm/Cancel动作的按钮crates/component/src/dialog/dialog.rs。文本的默认值还经由rust_i18n的t!(Dialog.ok)/t!(Dialog.cancel)提供国际化支持。在对话框中加入图标图标能显著提升警示类内容的注意力。声明式 API 中可将图标放入DialogHeader并居中use gpui_kit::component::{Icon, IconName, ActiveTheme}; AlertDialog::new(cx) .w(px(320.)) .trigger(Button::new(permission).outline().label(Request Permission)) .on_ok(|_, window, cx| { window.push_notification(Permission granted, cx); true }) .content(|content, _, cx| { content .child( DialogHeader::new() .items_center() .child( Icon::new(IconName::TriangleAlert) .size_10() .text_color(cx.theme().warning) ) .child(DialogTitle::new().child(Network Permission Required)) .child(DialogDescription::new().child( We need your permission to access the network to provide better services. )) ) .child( DialogFooter::new() .v_flex() .child( DialogAction::new().child( Button::new(allow).w_full().primary().label(Allow) ) ) .child( DialogClose::new().child( Button::new(deny).w_full().outline().label(Dont Allow) ) ) ) })命令式 API 则通过.icon(...)直接传入图标元素window.open_alert_dialog(cx, |alert, _, cx| { alert .title(Warning) .description(This action requires confirmation.) .icon( Icon::new(IconName::AlertTriangle) .size_8() .text_color(cx.theme().warning) ) })从 组件层build_surface的实现 可以看到当设置了 icon 或 title 时头部会以h_flex行布局包裹图标与v_flex的标题/描述列图标与文字自动对齐。仓库的 Story 示例中也有完整的图标 权限请求案例crates/story/src/stories/alert_dialog_story.rs可运行 story 应用直接观察效果。破坏性操作确认对于删除、清空等不可逆操作建议触发按钮使用.danger()变体、描述明确后果、确认按钮同样使用危险样式AlertDialog::new(cx) .trigger( Button::new(delete-account) .outline() .danger() .label(Delete Account) ) .on_ok(|_, window, cx| { window.push_notification(Account deletion initiated, cx); true }) .content(|content, _, _| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Delete Account)) .child(DialogDescription::new().child( This will permanently delete your account \ and all associated data. This action cannot be undone. )) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(cancel).flex_1().outline().label(Cancel) ) ) .child( DialogAction::new().child( Button::new(delete) .flex_1() .outline() .danger() .label(Delete Forever) ) ) ) })自定义宽度与布局默认宽度见 API 参考表文档约定为 420px。当默认宽度不满足需求时可通过width(...)或.w(...)显式指定AlertDialog::new(cx) .width(px(500.)) .trigger(Button::new(custom-width).label(Custom Width)) .content(|content, _, _| { // ... dialog content })注意组件层 Dialog 的DialogProps默认宽度定义为px(448.)crates/component/src/dialog/dialog.rs因此实际渲染宽度以显式传入的width为准若你需要严格的尺寸一致性建议始终显式设置宽度。控制关闭行为允许点击遮罩关闭window.open_alert_dialog(cx, |alert, _, _| { alert .title(Notice) .description(Click outside this dialog or press ESC to close it.) .overlay_closable(true) })版本差异提示组件层的overlay_closable方法目前已被标记为#[deprecated]AlertDialog backdrop dismissal is disabled by design见 crates/component/src/dialog/alert_dialog.rs其实现为空操作——即从设计上禁用了遮罩关闭基础层同样默认close_on_backdrop_press(false)。若你需要可遮罩关闭的弹层建议改用更灵活的 Dialog。禁用 ESC 键盘关闭ESC 默认可用keyboard默认true。对必须读完的重要通知类内容可禁用它window.open_alert_dialog(cx, |alert, _, _| { alert .title(Important Notice) .description(Please read this carefully before proceeding.) .keyboard(false) })显示关闭按钮window.open_alert_dialog(cx, |alert, _, _| { alert .title(Information) .description(Some information...) .close_button(true) })close_button默认false组件层AlertDialog::new中显式close_button(false)而通用 Dialog 的默认值是trueDialogProps默认close_button: true这正是 AlertDialog保守默认值的体现。阻止关闭让回调返回 falseon_ok/on_cancel回调返回true关闭对话框返回false则保持打开。这在进程运行中不允许关闭的场景非常有用use gpui_kit::component::dialog::DialogButtonProps; window.open_alert_dialog(cx, |alert, _, _| { alert .title(Processing) .description(A process is running. Click Continue to stop it or Cancel to keep waiting.) .button_props( DialogButtonProps::default() .ok_text(Continue) .show_cancel(true) ) .on_ok(|_, window, cx| { // Return false to prevent closing window.push_notification(Cannot close: Process still running, cx); false }) .on_cancel(|_, window, cx| { window.push_notification(Waiting..., cx); false }) })底层机制DialogButtonProps的on_ok/on_cancel默认实现就是|_, _, _| truecrates/component/src/dialog/dialog.rs因此未设置回调的按钮点击后自动关闭是默认行为一旦你提供了回调关闭与否就完全由返回值决定。关闭后的回调on_closeon_close在对话框关闭后触发位于on_ok或on_cancel之后适合做清理、埋点或导航window.open_alert_dialog(cx, |alert, _, _| { alert .title(Confirm) .description(Are you sure?) .on_close(|_, window, cx| { window.push_notification(Dialog closed, cx); }) })API 参考AlertDialog方法说明new(cx)创建新的 AlertDialog 实例trigger(element)设置触发元素点击后打开对话框声明式 APIcontent(builder)使用构建器函数设置对话框内容声明式 APItitle(title)设置对话框标题命令式 APIdescription(desc)设置对话框描述命令式 APIicon(icon)设置对话框图标命令式 APIbutton_props(props)设置按钮属性文本、样式、显隐show_cancel(bool)显示/隐藏取消按钮默认false另有便捷方法confirm()可直接开启取消按钮width(px)设置对话框宽度文档默认值420pxoverlay_closable(bool)允许点击遮罩关闭默认false注组件层该方法已废弃设计上禁用遮罩关闭close_button(bool)显示/隐藏关闭按钮默认falsekeyboard(bool)支持 ESC 关闭默认trueon_ok(callback)设置 OK 按钮回调返回true关闭对话框on_cancel(callback)设置取消按钮回调返回true关闭对话框on_close(callback)设置对话框关闭后的回调DialogButtonProps方法说明ok_text(text)设置 OK 按钮文本默认 OKcancel_text(text)设置取消按钮文本默认 Cancelok_variant(variant)设置 OK 按钮样式变体默认ButtonVariant::Primarycancel_variant(variant)设置取消按钮样式变体默认变体show_cancel(bool)显示/隐藏取消按钮默认falseon_ok(callback)设置 OK 回调返回true才关闭on_cancel(callback)设置取消回调返回true才关闭DialogAction包装组件子元素被点击时自动触发Confirm动作从而调用 AlertDialog 上设置的on_ok回调。DialogAction::new().child( Button::new(ok).primary().label(Confirm) )行为点击时派发Confirm动作 → 调用on_ok回调 → 回调返回true则关闭、返回false则保持打开。DialogClose包装组件子元素被点击时自动触发Cancel动作从而调用on_cancel回调。DialogClose::new().child( Button::new(cancel).outline().label(Cancel) )行为点击时派发Cancel动作 → 调用on_cancel回调 → 回调返回true或未设置回调则关闭、返回false则保持打开。完整实战示例删除确认两种 API命令式 API 按钮属性Button::new(delete) .danger() .label(Delete) .on_click(|_, window, cx| { window.open_alert_dialog(cx, |alert, _, _| { alert .title(Delete File?) .description(This action cannot be undone.) .button_props( DialogButtonProps::default() .ok_text(Delete) .ok_variant(ButtonVariant::Danger) .show_cancel(true) ) .on_ok(|_, window, cx| { // Perform delete operation window.push_notification(File deleted, cx); true }) }); })声明式 API DialogAction/DialogCloseAlertDialog::new(cx) .trigger(Button::new(delete).danger().label(Delete)) .on_ok(|_, window, cx| { window.push_notification(File deleted, cx); true }) .content(|content, _, cx| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Delete File?)) .child(DialogDescription::new().child(This action cannot be undone.)) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(cancel).outline().label(Cancel) ) ) .child( DialogAction::new().child( Button::new(delete-confirm).danger().label(Delete) ) ) ) })会话超时window.open_alert_dialog(cx, |alert, _, _| { alert .content(|content, _, _| { content .child( DialogHeader::new() .items_center() .child(DialogTitle::new().child(Session Expired)) .child(DialogDescription::new().child( Your session has expired due to inactivity. \ Please log in again to continue. )) ) .child( DialogFooter::new() .child( Button::new(sign-in) .label(Sign in) .primary() .flex_1() .on_click(|_, window, cx| { window.push_notification(Redirecting to login..., cx); window.close_dialog(cx); }) ) ) }) })更新可用AlertDialog::new(cx) .trigger(Button::new(update).outline().label(Update Available)) .on_cancel(|_, window, cx| { window.push_notification(Update postponed, cx); true }) .on_ok(|_, window, cx| { window.push_notification(Starting update..., cx); true }) .content(|content, _, _| { content .child( DialogHeader::new() .child(DialogTitle::new().child(Update Available)) .child(DialogDescription::new().child( A new version (v2.0.0) is available. \ This update includes new features and bug fixes. )) ) .child( DialogFooter::new() .child( DialogClose::new().child( Button::new(later).flex_1().outline().label(Later) ) ) .child( DialogAction::new().child( Button::new(update-now).flex_1().primary().label(Update Now) ) ) ) })最佳实践选择合适的 API简单确认用命令式 APIopen_alert_dialog复杂布局或需要与其他组件组合时用声明式 APItriggercontent。优先使用 DialogAction / DialogClose用包装组件代替手写window.close_dialog()代码更声明式、回调自动关联、不易出错。明确表达意图为删除等危险操作使用合适的按钮变体如ButtonVariant::Danger向用户传达动作的严重性。提供清晰的描述确保用户理解操作的后果尤其是破坏性操作此操作不可撤销等文案必须显式给出。善用图标但不滥用图标能增强警告/错误的注意力但应在语义恰当的位置使用如警示图标配警示文案。谨慎阻止关闭仅在用户确认确实必要如进程运行中时才阻止关闭避免造成对话框无法关闭的挫败感。保持一致性全应用统一对话框按钮顺序与样式降低用户学习成本。相关组件与延伸阅读Dialog 完整文档 —— 更灵活的通用对话框组件含根视图配置DialogHeader / DialogTitle / DialogDescription / DialogFooter —— 声明式内容分区组件DialogAction / DialogClose —— 确认/取消动作的包装组件基础层实现WindowExt —— 提供open_alert_dialog等窗口级弹层入口AlertDialog Story 示例 —— 覆盖默认、命令式、图标、破坏性、自定义 footer、键盘禁用、阻止关闭等全部场景的完整演示代码基础层测试 —— 验证遮罩默认不可关闭行为的单元测试【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考