anarlog Linux 通知模块剖析基于 GTK3 自绘通知中心的设计与实现【免费下载链接】anarlogOpen source Granola AI Alternative项目地址: https://gitcode.com/GitHub_Trending/hy/anarlog本文聚焦 anarlog开源 Granola AI 替代品仓库中的notification-linuxcrate深入讲解它在 Linux 桌面上的原生通知实现为什么坚持使用 GTK3 而非 GTK4、如何用 Rust gtk-rs 0.18 自绘一套支持展开/收起、进度条、操作按钮与图标合成的通知窗口并给出可直接运行的最小示例与事件回调接入方案。读完本文你可以独立运行该通知模块并理解其窗口管理、生命周期与主题适配的完整机制。一、模块定位与关键技术决策notification-linux是 anarlog 在 Linux 桌面端负责弹出原生通知的 crate位于 crates/notification-linux与notification-macos、notification-windows形成平台三件套共享同一个跨平台通知数据模型。其开发指南 AGENTS.md 中明确了一个核心架构决策Uses gtk3 (not gtk4) because webkit2gtk-4.1 links to gtk3.也就是说该模块强制使用 GTK3gtk-rs 0.18而非 GTK4原因是 anarlog 桌面端内部依赖webkit2gtk-4.1而 webkit2gtk-4.1 链接的是 GTK3。如果通知模块采用 GTK4同一进程内将同时存在两套 GTK 运行时与各自的 GLib 主循环导致版本冲突、信号混乱与资源双份加载。跟随 webkit2gtk-4.1 使用 GTK3 是最稳妥的共存方案。这一约束直接反映在依赖声明中Cargo.toml[target.cfg(target_os linux).dependencies] gdk 0.18 gdk-pixbuf 0.18 # Must match gtk 0.18s glib; gtk3-rs ended at 0.18, so glib cannot move on its own. glib 0.18 gtk 0.18 pango 0.18 indexmap 2.6 tracing { workspace true }注意依赖注释中的第二个关键点glib 的版本必须与 gtk 0.18 严格对齐。gtk3-rs 系列止步于 0.18因此 glib 不能单独升级否则会出现符号不匹配的链接错误。这是使用 GTK3 生态时最容易踩的坑。同时 crate 声明了一个linux-examplesfeature用于门控需要真实 X11/Wayland 显示的示例程序防止无显示环境下默认编译失败[features] linux-examples [] [[example]] name test_notification required-features [linux-examples]二、快速体验运行最小示例按 AGENTS.md 给出的命令在仓库根目录执行cargo run --example test_notification --features linux-examples -p notification-linux该命令会编译并运行 examples/test_notification.rs其完整逻辑如下use gtk::glib; use gtk::prelude::*; use notification_linux::*; fn main() { gtk::init().expect(Failed to initialize GTK); let notification Notification::builder() .title(Test Notification) .message(This is a test notification from Anarlog) .timeout(std::time::Duration::from_secs(5)) .build(); show(notification); glib::timeout_add_seconds_local_once(10, || { gtk::main_quit(); }); gtk::main(); }示例演示了三个要点先初始化 GTKgtk::init()必须在创建任何窗口前调用否则后续show内部也会自动尝试初始化并记录failed_to_initialize_gtk_notifications错误日志见 impl.rs 的ensure_gtk。用 Builder 构造通知Notification::builder()来自共享接口notification-interfacetimeout传Duration5 秒后通知自动消失并触发timeout回调。必须有 GTK 主循环gtk::main()驱动事件分发示例额外注册了一个 10 秒的定时器主动退出主循环避免程序悬挂。运行后屏幕右上角会出现一张 360×64 的无边框通知卡片5 秒后自动关闭。注意该示例依赖真实的桌面会话SSH 无显示环境无 DISPLAY/WAYLAND_DISPLAY下无法运行。三、共享数据模型通知长什么样notification-linux本身只负责画出来通知的字段语义定义在共享 crate crates/notification-interface 中其核心结构Notificationlib.rs包含key: OptionString去重键同 key 的新通知会顶掉旧通知supersede。title/message标题与正文。timeout: OptionDuration自动消失倒计时None或 0 表示常驻。start_time: Optioni64会议/日程的开始时间unix 秒用于距开始还有 xx倒计时展示。participants/event_details展开态展示的参会人姓名、邮箱、接受/待定/拒绝状态与事件详情What / 时区 / 地点。action_label/action_variant主按钮文案与类型Default/Destructive。options: OptionVecString下拉菜单选项列表。footer: OptionNotificationFooter底部页脚文本 动作按钮 图标。icon: OptionNotificationIcon图标支持多种来源。NotificationIcon是一个带标签的枚举定义了图标取用的五种方式Linux 端在 icon.rs 中逐一映射实现图标变体Linux 端实现Hidden不显示图标BundleId { bundle_id }尝试从 GTK IconTheme 按 bundle id 加载失败则回退默认应用图标SystemSymbol { name }将 SF Symbols 风格名称映射到 Linux 主题图标如phone.fill→phone、video.fill→camera-web、calendar→x-office-calendarPath { path }从文件路径加载支持~/展开缩放到 28×28Overlay { base, badge }合成角标把 badge 缩放到 base 的 54%双线性插值合成到右下角默认应用图标按com.hyprnote.dev→anarlog→hyprnote→application-x-executable的顺序回退查找保证任何桌面环境都能兜底。四、窗口管理与布局引擎通知渲染的核心在 impl.rs它实现了一个线程安全的单例管理器NotificationManager通过thread_local!RefCell持有对外仅暴露两个函数show(notification)与dismiss_all()从 lib.rs 导出。4.1 布局常量const NOTIFICATION_WIDTH: i32 360; // 卡片宽度 const COMPACT_HEIGHT: i32 64; // 收起态高度 const COMPACT_FOOTER_HEIGHT: i32 28; // 页脚额外高度 const EXPANDED_HEIGHT: i32 380; // 展开态高度 const RIGHT_MARGIN: i32 24; // 距屏幕右缘 const TOP_MARGIN: i32 15; // 距屏幕顶部 const NOTIFICATION_SPACING: i32 10; // 卡片间距 const MAX_NOTIFICATIONS: usize 5; // 同屏最多 5 条 const TICK_INTERVAL: Duration Duration::from_millis(50); // 50ms 刷新计时高度规则为展开态固定 380px收起态若有 footer 则 642892px否则 64px。通知锚定在主显示器工作区右上角x workarea 右缘 - 360 - 24y 15 已占用高度多卡片自上而下堆叠overlay_originreposition_notifications。4.2 无边框置顶窗口每个通知都是一个独立的gtk::Window通过以下属性组合实现悬浮卡片效果window.set_decorated(false); // 去掉系统标题栏 window.set_resizable(false); window.set_accept_focus(false); // 不抢焦点 window.set_skip_taskbar_hint(true); // 不占任务栏 window.set_skip_pager_hint(true); // 不占窗口列表 window.set_keep_above(true); // 始终置顶 window.set_type_hint(gdk::WindowTypeHint::Notification); // 声明为通知窗口 window.stick(); // 跨工作区置顶4.3 去重与上限淘汰show的流程体现了通知管理器的核心策略见NotificationManager::show若同key的通知已存在先关闭旧窗口supersede 替换语义若活动通知数 ≥ 5则淘汰最旧的一条DismissReason::Superseded创建窗口、定位、挂载 UI、启动 50ms 的 GLib 定时器通知使用IndexMap按插入序保存保证堆叠顺序稳定。show与dismiss_all都通过glib::MainContext::default().invoke调度到 GTK 主线程执行因此可以从任意线程安全地调用无需额外加锁。五、UI 渲染收起态与展开态NotificationInstance::mount负责重建窗口内容并根据is_expanded选择渲染紧凑视图还是展开视图。5.1 收起态compactbuild_compact组装一条水平布局的卡片左侧可选 28px 图标来自icon::pixbuf_for_icon中间标题14px 加粗超出省略与正文11px 灰色显示剩余时间等动态文案右侧按primary_action渲染两种交互Options 模式MenuButton下拉菜单逐项触发option_selected回调菜单末尾固定追加 Create New Note... 项其索引为选项数用于前端识别新建笔记动作Accept 模式单个动作按钮destructive时加destructive-action-button样式点击内容区时有 Options 按钮则展开菜单有可展开内容则切换展开态否则视为确认confirm回调并关闭有 footer 时追加底部栏footer 文本 可选小图标 动作按钮触发footer_action回调有 timeout 时在卡片底部渲染 3px 高的ProgressBar展示倒计时消耗进度。5.2 展开态expandedbuild_expanded渲染高度 380px 的详情视图头部标题 Show less 收起按钮参会人列表每行显示姓名邮箱右侧用彩色符号标记状态——✓绿色 Accepted、?橙色 Maybe、✗红色 Declined事件详情区What:必填、Invitee Time Zone:、Where:可选支持自动换行主动作按钮可切换 destructive 样式若设置了start_time底部显示距开始剩余时间倒计时标签。5.3 悬停与计时交互鼠标悬停时显示关闭按钮×、暂停倒计时移出后恢复展开时暂停倒计时收起且未悬停时恢复50ms 定时器tick每帧刷新进度条、收起态剩余时间文案与展开态倒计时文案并在满足任一过期条件时触发自动关闭。关闭时先set_sensitive(false)禁用交互200ms 后再真正close()配合 CSS 圆角与半透明背景形成平滑的视觉退出。六、事件回调把用户动作传回业务层通知是纯 UI动作必须回传业务层。callbacks.rs 用六个全局MutexOptionBoxdyn Fn...注册表实现回调总线全部通过 lib.rs 导出注册函数回调签名触发时机setup_notification_confirm_handlerFn(String)点击无选项、无可展开内容的收起卡片setup_notification_accept_handlerFn(String)点击 Accept 主按钮收起/展开态均触发setup_notification_dismiss_handlerFn(String)用户点击关闭按钮setup_notification_timeout_handlerFn(String)倒计时自然结束 / start_time 过期setup_notification_option_selected_handlerFn(String, i32)选择下拉菜单第 index 项setup_notification_footer_action_handlerFn(String)点击 footer 动作按钮回调参数统一为通知的keyString业务层据此定位上下文如NotificationKey::CalendarEvent对应的事件 ID。DismissReason内部枚举区分User / Timeout / Action / Superseded其中Action与Superseded不再额外通知业务层动作本身已通过对应回调上报被替换的旧通知无需通知User与Timeout则分别路由到 dismiss / timeout 回调。该回调路由逻辑配有单元测试callbacks.rs 内routes_each_linux_notification_action_to_its_registered_handler依次触发 confirm / accept / dismiss / timeout / option / footer 六类动作并断言事件序列可作为业务接入时的行为契约参考。七、主题与深色模式NotificationManager::install_styles通过std::sync::Once保证仅注入一次 CSSNOTIFICATION_CSS常量以STYLE_PROVIDER_PRIORITY_APPLICATION优先级注册到全局 StyleContext实现卡片外观border-radius: 14px、半透明白/黑背景浅色rgba(255,255,255,0.95)深色rgba(40,40,42,0.94)组件样式.notification-title、.notification-message、.close-button、.action-button、.destructive-action-button红色系、.footer-action-button、参会状态三色绿/橙/红进度条透明 trough 3px 淡蓝 progress深色模式窗口创建时调用prefers_dark_theme()检查 GTK 设置is_gtk_application_prefer_dark_theme()为 true 时给窗口添加darkclassCSS 中所有颜色随之切换。由于是自绘窗口而非系统通知样式完全可控、跨发行版表现一致这也是 anarlog 选择自绘而非调用 DBus 通知服务的原因之一。八、在业务代码中集成将notification-linux接入业务层的完整模式是注册回调 构造 Notification show三步// 1. 启动时注册动作回调 notification_linux::setup_notification_accept_handler(|key| { // 处理主按钮动作如开始记录key 用于定位通知来源 }); notification_linux::setup_notification_timeout_handler(|key| { // 通知自然消失清理 UI 状态 }); // 2. 任意线程构造并弹出通知 let n Notification::builder() .key(event:abc123) .title(会议即将开始) .message(Product Sync - 15:00) .start_time(unix_now() 120) .action_label(加入会议) .options(vec![稍后提醒.into(), 忽略.into()]) .icon(NotificationIcon::BundleId { bundle_id: com.zoom.Zoom.into() }) .build(); show(n);注意事项主线程约束所有 GTK 操作发生在主线程show/dismiss_all内部已通过glib::MainContext::invoke做线程切换业务线程可直接调用依赖 GTK 主循环宿主程序需运行gtk::main()或等价主循环否则通知不会出现环境前提仅支持 Linux 桌面会话且需要 webkit2gtk-4.1 / GTK3 运行时环境与对应主题图标首次初始化若宿主尚未初始化 GTKshow会尝试自动gtk::init()失败时仅记录错误日志并静默返回不会 panic。九、小结notification-linux用约 800 行 Rust gtk-rs 0.18 实现了完整的桌面通知方案遵守跟随 webkit2gtk-4.1 使用 GTK3的架构约束通过无边框置顶窗口、右上角堆叠布局、5 条上限与 key 去重、50ms 计时器驱动的进度条/倒计时、紧凑/展开双视图、六类事件回调总线以及深色模式 CSS为 anarlog 的会议提醒、麦克风状态与日程通知提供了跨发行版一致的原生体验。开发者在集成或移植该模块时应重点把握三条主线版本锁定gtk 0.18 与 glib 0.18 必须同版本、主线程调度invoke 与主循环、回调契约key 驱动的六类动作。【免费下载链接】anarlogOpen source Granola AI Alternative项目地址: https://gitcode.com/GitHub_Trending/hy/anarlog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
