WezTerm 桌面通知全指南window:toast_notification配置方法、平台实现与实战场景【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm本文围绕 WezTerm 的 Lua APIwindow:toast_notification(title, message, [url, [timeout_milliseconds]])展开讲解如何在任意窗口事件如配置重载、任务完成、命令结束中弹出桌面通知并深入解析 Linux (D-Bus)、macOS (UNUserNotificationCenter)、Windows (Toast XML) 三套底层实现与源码级细节。读完本文你将能够在自己的wezterm.lua中写出带超时控制、可点击打开 URL 的桌面通知并理解各平台对超时行为、授权与签名要求的真实差异。函数签名与基本语义window:toast_notification是挂在窗口对象window上的一个方法自 WezTerm 20210502-154244-3f7122cb 版本起可用。其完整签名如下window:toast_notification(title, message, [url, [timeout_milliseconds]])参数类型是否必填说明titlestring必填通知的标题messagestring必填通知的正文内容urlstring 或nil可选若提供点击通知会打开该 URLtimeout_millisecondsnumber 或nil可选通知保持突出显示的时长毫秒行为要点如下通知会一直停留在屏幕上直到被用户关闭、点击或超时时间耗尽若只指定超时、不指定 URL需要把 URL 参数显式传为nil即window:toast_notification(title, msg, nil, 4000)超时时间只是请求而非承诺尤其在 X11/Wayland 环境下系统D-Bus 通知服务端可能不遵守你给定的时长Windows 上则会固定使用一个未公开的时长忽略传入值点击带url的通知会调用 WezTerm 的 URL 打开能力底层由wezterm-open-urlcrate 实现即调用系统默认浏览器打开该地址。该 Lua 方法在 wezterm-gui/src/scripting/guiwin.rs 中注册为window对象的同步方法接收(title, message, url, timeout)四个参数将毫秒值通过std::time::Duration::from_millis转换为Duration后调用wezterm_toast_notification::show。url与timeout在 Rust 侧均为OptionT与 Lua 侧的nil语义一一对应。官方示例配置重载时弹出通知原文档给出的是一个监听窗口事件window-config-reloaded的完整可运行示例——每当配置被重新加载就在该窗口弹出一条提示local wezterm require wezterm wezterm.on(window-config-reloaded, function(window, pane) window:toast_notification(wezterm, configuration reloaded!, nil, 4000) end) return {}说明两点window-config-reloaded事件回调的签名是function(window, pane)window即为拥有该方法的对象该事件的完整定义见 docs/config/lua/window-events/window-config-reloaded.md上面传入4000毫秒约 4 秒但正如前文所述大约 4 秒只是请求值具体停留时长取决于系统。原文档也明确指出这段代码并非理想实现因为可能存在多个窗口每个窗口都会收到该事件从而弹出多条重复通知。改进方向可以是用全局状态记录是否已经提示过、或只在特定窗口如 focused 窗口上触发。源码级原理从 Lua 到各平台通知后端调用链可以概括为Lua window:toast_notification → wezterm-gui/src/scripting/guiwin.rs 的 toast_notification 方法 → wezterm_toast_notification::show(ToastNotification) → 平台后端 backend::show_notif()核心数据结构ToastNotification定义在 wezterm-toast-notification/src/lib.rs包含title、message、可选的url与可选的timeout四个字段。show()会捕获后端错误并记为日志不会让失败影响 WezTerm 主流程。后端按目标平台在编译期通过cfg选择lib.rsLinux / BSD 等非 macOS、非 Windows使用dbus模块走 freedesktop.org 通知规范macOS使用macos模块基于UNUserNotificationCenterWindows使用windows模块基于 Windows 10 的 Toast 通知框架。Linux / Wayland / X11D-Busorg.freedesktop.Notifications实现位于 wezterm-toast-notification/src/dbus.rs通过 zbus 连接会话总线上的org.freedesktop.Notifications服务。几个关键细节发出通知前会先调用GetCapabilities如果传了 URL 但服务端不支持actions能力则直接跳过通知——因为带 URL 的通知会附带一个 Show 操作按钮若服务端不支持该能力提示文字里的点击查看更多将无法生效通知的urgencyhint 被设置为2Critical高紧急度hints.insert(urgency, Value::U8(2 /* Critical */));带 URL 时actions数组为[show, Show]即渲染一个名为 Show 的按钮expire_timeout参数直接映射自timeout的毫秒数传 0 表示持久显示由通知服务端自行决定策略——这正是原文档强调X11/Wayland 环境下超时可能不被尊重的原因发送成功后实现会监听ActionInvoked与NotificationClosed信号前者用于在用户点击 Show 时调用wezterm_open_url::open_url(url)打开链接后者用于结束等待。两条信号流通过abortable与try_join!并发监听任一结束即清理另一个整个流程运行在独立线程中避免 D-Bus 或通知服务端无响应时阻塞主流程。macOSUNUserNotificationCenter 与签名要求实现位于 wezterm-toast-notification/src/macos.rs。首次调用时会执行一次性初始化initialize向UNUserNotificationCenter申请Alert | Provisional | Sound授权注册SHOW_URL_ACTION分类及其Show动作用于带 URL 的通知设置一个常驻的WezTermNotifDelegate代码注释显示其生命周期处理较为特殊采用有意泄漏引用计数的方式保证不被提前释放。发送通知时title映射为UNMutableNotificationContent的 titlemessage映射为 body带 URL 时URL 写入通知的userInfo并设置分类标识为SHOW_URL_ACTION用户点击 Show 时delegate 从userInfo中取出 URL 并调用wezterm_open_url::open_url打开超时通过一个后台线程sleep后调用removeDeliveredNotificationsWithIdentifiers把通知从通知中心移除来实现代码注释明确说明这只是basic take并非最优雅做法需要注意 macOS 上的硬性约束源码中定义了常量NEEDS_SIGN提示应用必须经过代码签名code-signUNUserNotificationCenter才能正常工作——未经签名的构建可能申请授权失败或通知不显示。WezTerm 官方发布的 macOS 包满足该条件。WindowsToast 通知 XML 模板实现位于 wezterm-toast-notification/src/windows.rs通过 Windows Runtime 的ToastNotificationManager发送通知内容以 XML 形式构造使用ToastGeneric模板标题与正文分别放入两个text节点带 URL 时追加一个action contentShow argumentsshow /按钮toast durationlong visual binding templateToastGeneric text{title}/text text{message}/text /binding /visual actions action contentShow argumentsshow / /actions /toastdurationlong以及 Windows 通知体系本身的策略决定了超时参数在 Windows 上始终被忽略、采用固定的未公开的显示时长——与原文档的描述完全一致用户点击 Show 时Activated事件处理器读取参数args show后打开对应 URL发送动作同样被放到独立线程以避免在窗口消息循环派发过程中被卡死。实战扩展通知的典型使用场景长任务完成提示结合wezterm.on与启动新程序的能力可以在长时间运行的任务结束时弹通知。例如结合wezterm.mux.spawn_window或直接运行wezterm cli系列命令时在完成回调中调用本方法local wezterm require wezterm -- 示例配合事件与 async 回调在耗时操作完成后提示 wezterm.on(window-config-reloaded, function(window, pane) window:toast_notification(wezterm, configuration reloaded!, nil, 4000) end)更常见的做法是配合wezterm.action_callback、计时器wezterm.time或wezterm.run_child_process的完成回调使用——把window:toast_notification放在回调内即可实现任务结束提醒。需要注意回调中是否持有有效的window对象决定了能否直接调用本方法若在无窗口上下文中可考虑使用wezterm.toast_notification等价能力或通过 mux 窗口事件桥接见下文内部用途对 multiplexer 的处理。点击通知打开 URL当需要任务完成后一键跳到结果页时传入第三个参数window:toast_notification( build finished, click to open the build log, https://example.com/build-log )该通知会一直停留timeout为nilLinux 上对应 D-Bus 的expire_timeout0表示持久直到用户点击打开或手动关闭。仅指定超时URL 传 nil-- 只想控制时长、不提供 URLurl 参数必须显式传 nil window:toast_notification(wezterm, auto-dismiss after 2s, nil, 2000)与配置选项notification_handling的关系WezTerm 内置的通知不止来自本 Lua 方法。当 mux 产生MuxNotification::Alert等事件时wezterm-gui/src/frontend.rs 会根据配置项notification_handling决定是否把提醒以persistent_toast_notification(title, message)的形式弹出桌面通知。该配置支持四个取值取值含义NeverShow永不显示通知AlwaysShow总是显示通知SuppressFromFocusedPane焦点 pane 产生的通知不显示SuppressFromFocusedTab焦点 tab 产生的通知不显示SuppressFromFocusedWindow焦点窗口产生的通知不显示它与window:toast_notification的差异在于本方法是面向用户 Lua 脚本的显式调用由开发者控制标题、正文、URL 与超时而notification_handling控制的是内置事件驱动通知如远端 pane 的 alert、错误信息的显示策略。两者可以配合用 Lua 方法做自定义业务通知用notification_handling约束内置通知的打扰程度。内部使用场景一览除了 Lua APIWezTerm 自身也在多处调用 toast 能力这些用法可帮助理解其能力边界路径均为仓库内相对位置更新检查wezterm-gui/src/update.rs 在发现新版本时使用persistent_toast_notification_with_click_to_open_url点击通知即打开下载/发布页面下载完成wezterm-gui/src/download.rs 在下载任务结束后弹出可点击通知启动错误与崩溃提示wezterm-gui/src/main.rs 在初始化失败、以及 panic/错误场景fatal_toast_notification见 main.rs时弹出通知帮助用户了解启动失败原因mux 通知传播changelog 显示 multiplexer 会把 toast 通知与调色板传播给客户端见 docs/changelog.md 中关于 toast notifications 的条目远程 pane 的告警可经由此机制在本地弹窗。这些内部调用均基于persistent_toast_notification/persistent_toast_notification_with_click_to_open_url两个便捷函数定义于 wezterm-toast-notification/src/lib.rs它们固定timeout None持久显示恰好对应 Lua 侧不传超时参数的默认行为。版本与限制总结项目说明引入版本20210502-154244-3f7122cb见 docs/changelog.md 中新增window:toast_notification的条目Linux/BSD 后端D-Busorg.freedesktop.Notifications超时为请求值服务端可忽略不支持actions能力时带 URL 的通知会被跳过macOS 后端UNUserNotificationCenter需要应用已代码签名授权被拒时通知无法显示Windows 后端Toast 通知ToastGeneric模板durationlong超时参数固定忽略通用限制通知系统本身可能限制通知数量与显示方式本方法不会阻塞 Lua 主流程若你的环境如某些精简 Linux 桌面没有运行任何 D-Bus 通知守护进程则通知可能直接失败并被记录为日志WezTerm 本身不受影响。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考