gpui-kit Notification 组件实战在 GPUI 应用中构建可自动消失的 Toast 通知与系统通知中心投递【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kitgpui-kit 的Notification组件是一个面向 GPUI 桌面应用的 toast 通知系统用于向用户显示短暂消息通知默认出现在窗口右上角支持超时后自动消失并提供多种类型、标题、自定义内容与操作按钮。本文将以website/zh-CN/component/notification.md为骨架结合crates/component下的源码实现完整讲解通知层的挂载、构建器 API、唯一 ID 管理、系统通知中心投递及平台差异帮助你为状态反馈、确认信息和异步操作提示构建专业级通知体验。目录导入与模块结构第一步在根视图中渲染通知层基础通知与快捷构造方法四种通知类型与视觉语义标题、图标与自定义样式自动隐藏的计时规则操作按钮与可点击通知自定义内容内嵌 Markdown唯一通知 ID手动管理长任务状态系统通知中心投递与平台要求通知外观与布局的全局设置综合示例导入与模块结构在你的 Cargo 项目中添加 gpui-kit 依赖后按如下方式导入use gpui_kit::component::{ notification::{Notification, NotificationType}, WindowExt };Notification与NotificationType定义在 crates/component/src/notification.rs并通过 crates/component/src/lib.rs 的pub mod notification;对外暴露。整个通知功能由三层协作完成Notification可链式构建的单条通知消息、标题、类型、ID、动作等实现Render、Styled并分别EventEmitterDismissEvent/EventEmitterDismissRequest见 crates/component/src/notification.rsNotificationList维护同一窗口内所有通知的实体列表负责推送、分组、生命周期推进与关闭见 crates/component/src/notification.rsRoot与WindowExt把NotificationList挂到窗口根视图并向Window提供push_notification等便捷方法。第一步在根视图中渲染通知层要显示通知必须先让应用根视图渲染 notification layer。Root::render_notification_layer会把当前激活的通知渲染在应用内容之上实现位于 crates/component/src/root.rs它读取窗口的Root根视图并挂载root.notification实体当存在激活的 Sheet 时还会按 Sheet 的Placement上/右/下/左自动留出对应边距避免通知层与 Sheet 重叠。use gpui_kit::component::{TitleBar, Root}; struct Example {} impl Render for Example { fn render(mut self, window: mut Window, cx: mut ContextSelf) - impl IntoElement { let notification_layer Root::render_notification_layer(window, cx); div() .size_full() .child( v_flex() .size_full() .child(TitleBar::new()) .child(div().flex_1().child(Hello world!)), ) // 将通知层渲染在应用内容之上 .children(notification_layer) } }基础通知与快捷构造方法推送一条最简单的通知可以直接把字符串交给window.push_notificationwindow.push_notification(This is a notification., cx);也可以使用Notification构建器显式指定消息Notification::new() .message(Your changes have been saved.)push_notification接受任何实现了IntoNotification的类型——源码中为String、SharedString、str、Cowstr以及(NotificationType, T)元组都提供了From实现见 crates/component/src/notification.rs。(NotificationType::Info, message)这种写法实际展开为Notification::new().message(content).with_type(type_)。除new()之外源码还提供了四个类型化的快捷构造方法crates/component/src/notification.rsNotification::info(message)— Info 类型Notification::success(message)— Success 类型Notification::warning(message)— Warning 类型Notification::error(message)— Error 类型四种通知类型与视觉语义NotificationType是一个派生Default的枚举默认值为Info见 crates/component/src/notification.rs。每种类型通过icon()方法映射到不同的图标与主题色crates/component/src/notification.rs类型图标主题色InfoIconName::Infotheme().infoSuccessIconName::CircleChecktheme().successWarningIconName::TriangleAlerttheme().warningErrorIconName::CircleXtheme().dangerwindow.push_notification( (NotificationType::Info, File saved successfully.), cx, ); window.push_notification( (NotificationType::Success, Payment processed successfully.), cx, ); window.push_notification( (NotificationType::Warning, Network connection is unstable.), cx, ); window.push_notification( (NotificationType::Error, Failed to save file. Please try again.), cx, );带类型的通知渲染时会用对应图标和颜色填充通知左侧的图标位若没有设置类型则使用.icon()自定义的图标。标题、图标与自定义样式带标题Notification::new() .title(Update Available) .message(A new version of the application is ready to install.) .with_type(NotificationType::Info)标题以text_smfont_semibold样式渲染在消息上方crates/component/src/notification.rs。标题和消息均为可选没有标题时通知只显示消息两者都缺失时该通知将不会被投递到系统通知中心见下文系统通知章节。自定义图标Notification::new() .message(Custom icon notification) .icon(Icon::new(IconName::Bell)).icon()接受任何impl IntoIcon如果同时设置了类型类型自带图标优先见 crates/component/src/notification.rs 的渲染逻辑。自定义样式Notification实现了Styled因此可以直接链式调用样式方法.bg()、.rounded()、.text_color()等来覆盖默认外观。默认外观由BaseToast提供边框色theme().border、背景theme().tokens.popover、圆角theme().radius_lg与toast_shadow阴影见 crates/component/src/notification.rs。自动隐藏的计时规则// 关闭自动隐藏只能手动关闭 Notification::new() .message(This notification stays until manually closed.) .autohide(false) // 开启自动隐藏默认值 Notification::new() .message(This will disappear automatically.) .autohide(true) // 默认默认自动隐藏时长为 5 秒在 crates/component/src/notification.rs 中NotificationList::push会将autohide映射为ToastOptions { timeout: autohide.then_some(Duration::from_secs(5)) }。此外还有两个重要的计时行为悬停/聚焦暂停指针悬停在通知上或某条通知获得键盘焦点时倒计时暂停指针移开或焦点离开后继续。后台不暂停窗口未激活时倒计时照常进行因此不能错过的消息应关闭自动隐藏.autohide(false)或改用系统通知投递。这一行为有测试用例inactive_window_does_not_pause_autohide与focus_pauses_autohide_and_present_phase_is_projected佐证crates/component/src/notification.rs。生命周期计时由NotificationList::start_advancing驱动crates/component/src/notification.rs以 50ms 为周期推进过渡相位NOTIFICATION_ADVANCE_INTERVAL当没有通知挂载时自动停止计时器避免空闲窗口空转。进入动画时长 400ms、退出动画 200ms、位移偏移 96px见文件顶部常量 crates/component/src/notification.rs。操作按钮与可点击通知操作按钮通过.action()可以在通知右侧添加一个按钮。注意一旦设置了 action通知将自动关闭自动隐藏Notification::action内部强制self.autohide false见 crates/component/src/notification.rs渲染时按钮会被缩放为small()尺寸Notification::new() .title(Connection Lost) .message(Unable to connect to server.) .with_type(NotificationType::Error) .autohide(false) .action(|_, cx| { Button::new(retry) .primary() .label(Retry) .on_click(cx.listener(|this, _, window, cx| { println!(Retrying connection...); this.dismiss(window, cx); })) })按钮点击回调中通过this.dismiss(window, cx)关闭通知——dismiss会发出DismissRequest事件crates/component/src/notification.rsNotificationList订阅该事件后驱动退出动画并最终触发DismissEvent与on_close回调。可点击通知整条通知也可以响应点击。此时点击通知会先关闭它再触发你的回调Notification::new() .message(Click to view details) .on_click(cx.listener(|_, _, _, cx| { println!(Notification clicked); cx.notify(); }))on_click回调签名是Fn(ClickEvent, mut Window, mut App)crates/component/src/notification.rs。此外渲染层还注册了中键点击处理——中键点击也会关闭通知on_aux_clickevent.is_middle_click()见 crates/component/src/notification.rs。通知右上角的关闭按钮在悬停时显示group_hover点击后stop_propagation再 dismiss。on_close回调Fn(mut Window, mut App)在通知以任何方式关闭时触发关闭按钮、中键点击、自动隐藏、点击处理器或程序化关闭见 crates/component/src/notification.rs。自定义内容内嵌 Markdown当需要比「标题 消息」更丰富的展示时使用.content()提供任意 GPUI 元素。它接受一个返回AnyElement的闭包use gpui_kit::component::text::markdown; let markdown_content r# ## Custom Notification - **Feature**: New dashboard available - **Status**: Ready to use - [Learn more](https://example.com) #; Notification::new() .content(|_, window, cx| { markdown(markdown_content).into_any_element() })markdown函数来自 crates/component/src/text 模块用于把 Markdown 字符串渲染为元素。自定义内容会渲染在标题和消息下方注意当只使用.content()而没有 title/message 时系统通知投递会被跳过系统通知需要文本。唯一通知 ID手动管理长任务状态默认情况下每条通知使用随机 UUID 作为 ID因此彼此独立、永不互相替换见Notification::new中uuid::Uuid::new_v4()crates/component/src/notification.rs。当你需要手动管理通知——例如长任务状态或持久警告——可以为通知分配唯一 ID用相同 ID 再次推送会替换前一条通知。struct UpdateNotification; Notification::new() .id::UpdateNotification() .message(System update available) .autohide(false) struct TaskNotification; Notification::warning(Task failed to complete) .id1::TaskNotification(task-123) .title(Task Failed).id::T()以类型T作为唯一标识TypeId见 crates/component/src/notification.rs.id1::T(key)以「类型 元素 ID」共同标识可区分同一类型下的多条通知见 crates/component/src/notification.rs。后续通过WindowExt提供的方法移除// 移除所有 id 匹配 T 的通知包括 .id 与 .id1 注册的 window.remove_notification::UpdateNotification(cx); // 仅移除 (T, key) 对应的单条通知 window.remove_notification1::TaskNotification(task-123, cx); // 清空当前窗口全部通知 window.clear_notifications(cx);这些方法定义在 crates/component/src/window_ext.rs最终委托给Root的对应实现crates/component/src/root.rs。remove_notification::T对应NotificationList::close_by_type会同时命中.id::T()与.id1::T(任意 key)的所有通知该行为由测试close_by_type_removes_id_and_all_id1_of_same_type验证crates/component/src/notification.rs而remove_notification1只精确移除(T, key)匹配的单条测试close_with_id_and_element_id_removes_only_matching_keycrates/component/src/notification.rs。系统通知中心投递与平台要求通知不仅可以作为应用内 toast还可以投递到操作系统的通知中心。使用NotificationDelivery选择去向枚举值行为InApp默认仅显示应用内 toastSystem仅投递系统通知中心不显示 toastInAppAndSystem同时显示 toast 并投递系统通知中心use gpui_kit::component::notification::{Notification, NotificationDelivery}; // 单条通知覆盖.system() 和 .in_app_and_system() 是 // .delivery(NotificationDelivery::...) 的简写。 Notification::info(Your download is ready.) .title(Download complete) .system() // 或为所有通知设置全局默认值 Theme::global_mut(cx).notification.delivery NotificationDelivery::InAppAndSystem;NotificationDelivery定义在 crates/component/src/notification.rs并提供includes_in_app()/includes_system()两个判定方法。投递时的语义均有源码与测试支撑标题/正文映射title 和 message 分别成为系统通知的标题和正文两者都缺失时不投递。只有 message 时message 成为系统通知标题见push_system的匹配逻辑 crates/component/src/notification.rs测试system_delivery_posts_to_center_without_in_app_toast验证。替换与撤回用相同的.id::T()再次推送会替换之前的系统通知通过带gpui-component/notification/前缀的稳定 tag 实现见system_tag()crates/component/src/notification.rswindow.remove_notification::T(cx)/window.clear_notifications(cx)会撤回对应的系统通知。自动隐藏与保留toast 自动隐藏时系统通知保留在通知中心测试explicit_close_retracts_system_notification_but_autohide_does_not验证crates/component/src/notification.rs。点击行为点击系统通知会激活应用及其窗口、关闭对应的应用内 toast如有、并以默认的ClickEvent触发on_click见SystemNotificationRegistry::handle_responsecrates/component/src/notification.rs。NotificationDelivery::System模式下没有 toast因此on_close不会被调用。响应处理器归属gpui_kit::component::init会注册应用级的on_system_notification_response处理器crates/component/src/notification.rs之后请勿再自行注册——gpui 只保留一个处理器。应用通过cx.show_system_notification直接发送的系统通知不受影响响应处理器会忽略非本库前缀的 tag测试response_for_a_foreign_tag_is_ignored验证crates/component/src/notification.rs。平台要求平台要求撤回macOS必须从可信位置如/Applications的打包.app运行cargo run裸跑时静默禁用。首次投递会触发系统授权弹窗拒绝后系统会记住该选择后续投递静默失败支持Windows启动早期调用cx.set_app_identity(identifier, name)支持Linux需要 XDG 通知守护进程不支持自然过期通知外观与布局的全局设置NotificationSettings定义在 crates/component/src/notification.rs作为主题的一部分挂在theme().notification见 crates/component/src/theme/mod.rs。其默认值如下字段默认值说明placementAnchor::TopRight通知出现的位置单条通知可用.placement()覆盖每种位置各自独立堆叠margins上下左右 16px顶部额外加上TITLE_BAR_HEIGHT通知距窗口边缘的间距顶部留白避免与标题栏重叠max_items10同时显示的最大通知数width382px通知宽度deliveryNotificationDelivery::InApp全局默认投递方式全局修改方式let settings mut Theme::global_mut(cx).notification; settings.placement Anchor::BottomRight; settings.max_items 5; settings.width px(420.); settings.delivery NotificationDelivery::InAppAndSystem;NotificationList渲染时会按placement把可见通知分组到不同锚点的堆栈中groupedcrates/component/src/notification.rs并支持TopLeft / TopCenter / TopRight / BottomLeft / BottomCenter / BottomRight / LeftCenter / RightCenter共 8 个锚点。每个堆栈的 element id 以锚点本身为键保证堆栈在其它位置通知消失时不会重放进入动画测试stack_element_id_survives_other_placements_disappearing验证crates/component/src/notification.rs。单条通知覆盖全局位置Notification::info(bottom-left corner) .placement(Anchor::BottomLeft)综合示例表单校验失败Notification::error(Please correct the following errors before submitting.) .title(Validation Failed) .autohide(false) .action(|_, _, cx| { Button::new(review) .outline() .label(Review Form) .on_click(cx.listener(|this, _, window, cx| { // 跳转到表单并关闭通知 this.dismiss(window, cx); })) })文件上传进度使用唯一 ID 让同一条通知在任务生命周期内被不断替换更新struct UploadNotification; // 开始上传 window.push_notification( Notification::info(Uploading file...) .id::UploadNotification() .title(File Upload) .autohide(false), cx, ); // 完成后替换为成功状态 window.push_notification( Notification::success(File uploaded successfully!) .id::UploadNotification() .title(Upload Complete), cx, );系统状态更新Notification::warning(System maintenance will begin in 30 minutes.) .title(Scheduled Maintenance) .autohide(false) .action(|_, cx| { Button::new(details) .link() .label(View Details) .on_click(cx.listener(|this, _, window, cx| { this.dismiss(window, cx); })) })批处理操作结果富文本内容use gpui_kit::component::text::markdown; let results_content r# ## Batch Operation Complete **Processed**: 150 items **Success**: 147 items **Failed**: 3 items [View failed items](https://link.gitcode.com/i/955bf2f7c38d24071b2fa55f6f3ffe00) #; Notification::success(Batch operation completed with some failures.) .title(Operation Results) .content(|window, cx| { markdown(results_content).into_any_element() }) .autohide(false)交互式确认点击 操作按钮组合struct SaveConfirmation; Notification::new() .id::SaveConfirmation() .title(Unsaved Changes) .message(You have unsaved changes. Save before leaving?) .autohide(false) .action(|_, cx| { Button::new(save) .primary() .label(Save) .on_click(cx.listener(|this, _, window, cx| { println!(Saving changes...); this.dismiss(window, cx); })) }) .on_click(cx.listener(|_, _, _, cx| { println!(Save reminder clicked); cx.notify(); }))小结gpui-kit 的Notification组件把「窗口右上角 toast 操作系统通知中心」统一进一个构建器 APINotification::new()链式设置消息、标题、类型、图标、唯一 ID、自动隐藏、动作按钮与自定义内容WindowExt提供push_notification/remove_notification/remove_notification1/clear_notifications四个窗口级操作Root::render_notification_layer负责把通知层盖在应用内容之上。其底层由ToastManager驱动 50ms 粒度、5 秒默认时长的生命周期计时并正确处理悬停/聚焦暂停与后台继续的细节系统通知投递则通过带命名空间前缀的稳定 tag 实现替换、撤回与点击回跳。对于长任务状态、持久告警等场景建议关闭自动隐藏或使用系统投递并配合唯一 ID 让通知随任务状态平滑演进。【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考