桌面应用版本控制开发工具【免费下载链接】desktopFocus on what matters instead of fighting with Git.项目地址https://gitcode.com/gh_mirrors/de/desktop点击查看免费下载desktop-notifications 是 GitHub Desktop 内置的一个零依赖、面向 Windows 与 macOS 的 OS 原生通知库本文以其官方文档 docs/index.md 为核心结合其 TypeScript 封装层vendor/desktop-notifications/lib与原生 C 实现vendor/desktop-notifications/src深入剖析初始化、弹通知、事件回调、权限管理与本地构建的全过程。读完本文你将掌握该库的完整 API 用法、toastActivatorClsid参数的真实作用、平台能力探测逻辑以及如何在当前仓库的vendor/desktop-notifications子目录下完成原生模块的编译配置。为什么 GitHub Desktop 要自研通知库在开始 API 之前先理解这个库存在的理由。根据 vendor/desktop-notifications/README.md 的说明GitHub Desktop 团队在评估现有方案后决定自研原因是它们都有难以接受的短板Electron不支持 Windows 通知被折叠进操作中心Action Center后的场景因为 Electron 缺少基于 CLSID 的 COM activator无法利用 CLSID 激活机制node-notifier依赖 snoretoast 处理 Windows 通知每次通知只能检测一个事件且必须使用 snoretoast 中硬编码的同一个 CLSIDelectron-windows-notifications围绕 NodeRT 有大量依赖构建还需要不少手工步骤。因此该库的设计目标非常明确零依赖、对 Windows 通知有良好支持、尽可能复用 TypeScript 声明并且“只实现 GitHub Desktop 需要的功能而不是 1:1 复刻任何其他通知 API”。这也是理解下文所有 API 设计的前提——它是一套精简、实用、opinionated 的接口。API 快速上手文档中的经典用法官方文档 docs/index.md 给出了完整的最小可运行示例这是理解整个库的入口import { initializeNotifications, DesktopNotification, terminateNotifications, } from desktop-notifications // Initialize the notifications environment with the CLSID activator initializeNotifications({YOUR-TOAST-ACTIVATOR-CLSID-GOES-HERE}) // ... // Create and configure your notification const notification new DesktopNotification( This is a title, This is a body ) // Set a handler for click events notification.onclick () { console.log(Hello world!) } // Then show it! notification.show() // ... // Finally, clean up any resources used by the notifications environment terminateNotifications()整个生命周期可以归纳为三步初始化调用initializeNotifications传入 Windows 平台的toastActivatorClsid建立通知环境创建并展示实例化DesktopNotification通过onclick挂接点击事件调用show()弹出系统通知清理所有通知使用完毕后调用terminateNotifications()释放原生资源。需要特别说明的是文档中的DesktopNotification类式 API 属于早期设计。在当前仓库的 lib/index.ts 中实际导出的是函数式 APIinitializeNotifications、showNotification、closeNotification、terminateNotifications、getNotificationsPermission、requestNotificationsPermission以及能力探测函数supportsNotifications、supportsNotificationsPermissionRequest和设置页跳转函数getNotificationSettingsUrl。文档展示了库的设计初衷而源码反映了它的最终形态二者结合阅读可以看清 API 的演进脉络。初始化与 toastActivatorClsidWindows 通知激活的核心initializeNotifications在 native-module.ts 中实现其签名为export const initializeNotifications: ( opts: INotificationOptions ) void opts getNativeModule()?.initializeNotifications(notificationCallback, opts)注意两点实现细节原生模块懒加载_nativeModule初始为undefined首次调用时通过supportsNotifications()判断平台是否支持支持才require(../build/Release/desktop-notifications.node)。源码注释明确说明这是为了“避免启动时崩溃——这种崩溃更难追踪”回调先行注册封装层在调用原生initializeNotifications时会把统一的notificationCallback作为第一个参数传入后续原生层的事件都汇流到这个回调再分发。初始化参数的唯一成员定义在 notification-options.tsexport interface INotificationOptions { /** CLSID used by Windows to report notification events */ readonly toastActivatorClsid?: string }toastActivatorClsid是 Windows 通知体系的关键概念应用要接收 Toast 通知的点击激活事件必须在注册表中注册一个 COM activator并将激活器的 CLSID 写入通知的Activated参数中。系统在用户点击通知时通过该 CLSID 拉起对应组件这正是文档示例中初始化时就要传入 CLSID 的原因。在原生侧main_win.cc 对参数做了严格的运行时校验第一个参数必须是函数否则抛出TypeError: Callback must be a function.第二个参数必须是对象且必须包含toastActivatorClsid属性否则抛出TypeError: The options object must have the toastActivatorClsid property.校验通过后调用Utils::utf8ToWideChar把 CLSID 从 UTF-8 转换为宽字符再构造DesktopNotificationsManager单例持有。在 GitHub Desktop 主仓库中app/src/main-process/notifications.ts与app/src/main-process/main.ts负责在应用启动阶段完成该初始化CLSID 相关的激活器查找逻辑可参考 find-toast-activator-clsid.ts。展示、关闭与回调事件驱动的通知生命周期showNotification异步展示并返回通知 IDexport const showNotification: ( title: string, body: string, userInfo?: Recordstring, any ) Promisestring | null async (...args) { const id crypto.randomUUID() try { await getNativeModule()?.showNotification(id, ...args) } catch (e) { return null } return id }每次展示前用crypto.randomUUID()生成唯一 ID该 ID 就是关闭通知的凭证原生调用失败时吞掉异常并返回null通知展示失败不应拖垮主流程返回的 ID 可传给closeNotification(id)主动关闭某条通知userInfo是可选对象原生层会把它JSON 序列化成字符串随通知携带用户点击通知时再原样回传——详见下文回调部分。原生侧showNotification的实现在 main_win.cc 中依次校验id、title、body必须为字符串userInfo若存在必须是对象随后JSONStringify序列化并调用desktopNotificationsManager-displayToast(id, title, body, userInfo)。若通知系统尚未初始化会记录DN_LOG_ERROR(Cannot show notification: notifications not initialized.)并直接返回。事件回调目前唯一的事件是 click回调体系定义在 notification-callback.tsexport type NotificationCallback T extends Recordstring, any Recordstring, any (event: DesktopNotificationEvent, id: string, userInfo: T) void export const onNotificationEvent T extends Recordstring, any Recordstring, any ( callback: NotificationCallbackT | null ) { globalNotificationCallback callback as NotificationCallback }事件类型目前只有一种click见 notification-event-type.ts通过onNotificationEvent(callback)注册全局处理器callback会收到(event, id, userInfo)三个参数其中userInfo就是showNotification时传入的那个对象——这正是“把业务上下文随通知带去、点击时取回”的标准模式传入null可以取消注册。这也解释了文档中notification.onclick的语义演进无论类式 API 还是函数式 API“点击通知”都是唯一需要响应的用户事件。在 GitHub Desktop 中app/src/lib/stores/notifications-store.ts就利用该回调把点击事件映射回具体的仓库与 PR 场景。权限管理查询、申请与引导用户去系统设置该库把权限抽象为三种状态定义在 notification-permission.tsexport type DesktopNotificationPermission default | granted | denieddefault用户尚未做出选择。注释特别说明在 Windows 上该状态等同于 grantedgranted已授予通知权限denied已拒绝通知权限。配套 API 为/** Gets the current state of the notifications permission. */ export const getNotificationsPermission: () Promise DesktopNotificationPermission () getNativeModule()?.getNotificationsPermission() /** Requests the user to grant permission to display notifications. */ export const requestNotificationsPermission: () Promiseboolean () getNativeModule()?.requestNotificationsPermission()getNotificationsPermission()异步读取当前权限状态requestNotificationsPermission()向系统发起权限申请返回Promiseboolean表示是否获得授权。如果用户拒绝授权可以用getNotificationSettingsUrl()生成跳转到系统通知设置页的特殊 URL见 notification-settings-url.tsreturn process.platform darwin ? x-apple.systempreferences:com.apple.preference.notifications : ms-settings:notificationsmacOS 返回系统偏好设置的通知面板 URLWindows 返回ms-settings:notifications设置页 URL在不支持的平台上返回null。GitHub Desktop 中 test-notifications.tsx 与 preferences/notifications.tsx 正是借助这套 API 完成“测试通知”与“权限状态展示 跳转设置”的交互。平台支持矩阵能力探测的精确判定该库只在受支持的平台上加载原生模块判定逻辑集中在 notification-support.tsexport function supportsNotifications() { if (process.platform darwin) { return supportsDarwinNotifications() } if (process.platform win32) { return supportsWindowsNotifications() } return false }macOS通过os.release()读取 Darwin 内核版本要求主版本号 ≥ 18即macOS 10.14 (Mojave) 及以上Windows要求majorVersion 10且 build 号 ≥15063即Windows 10 Creators Update及以上因为所依赖的 Toast API 中部分能力在 Creators Update 之前不可用build 号缺失时按15063保守处理majorVersion 10也视为支持其他平台一律返回false此时getNativeModule()返回null所有 API 调用都会安全地静默失败。权限申请能力有独立判定supportsNotificationsPermissionRequest()仅在macOS 10.14返回true说明当前只有 macOS 支持运行时申请通知权限Windows 的权限在系统设置中管理。构建与 SetupWindows 上编译原生模块的环境要求官方文档的 Setup 章节针对独立仓库的构建流程在当前仓库中对应的是vendor/desktop-notifications子目录原生模块的编译配置见 binding.gyp依赖清单见 package.json$ cd vendor/desktop-notifications $ yarn由于该库会构建原生模块产物为build/Release/desktop-notifications.node除了较新版本的 Node.js 之外Windows 上还需要以下依赖依据文档记载Python文档要求 Python 2.7并建议安装到默认路径c:\Python27否则需要手动为 node-gyp 配置路径安装时务必勾选Add python.exe to Path选项C 工具链三选一Visual C Build Tools安装后执行npm config set msvs_version 2019让 node 使用该工具链Visual Studio 2019安装时必须勾选Desktop development with C工作负载Node.js 安装原生模块所必需同样执行npm config set msvs_version 2019二者均要求安装Windows 10 SDK这一点文档特别标注了 IMPORTANT。提示文档撰写于 Python 2.7 仍是 node-gyp 主流解释器的时期如今 node-gyp 的 Python 版本要求以你使用的 Node/npm 实际版本为准这里忠实保留文档原始要求便于对照历史环境。这套构建依赖与 GitHub Desktop 主仓库在 Windows 上构建原生依赖的方式一致相关安装脚本可参考 script/post-install.ts。跨平台原生实现速览Windowssrc/win/main_win.cc 是 N-API 入口负责参数校验、UTF-8/宽字符转换、DesktopNotificationsManager单例管理DesktopNotificationsManager.h 与 DesktopNotificationsManager.cpp 实现 Toast 展示与 CLSID 激活事件接收点击事件的激活器由 DesktopNotificationsActionCenterActivator.h 定义macOSsrc/mac/main_mac.mm 与 GHDesktopNotificationsManager.h/.m 基于NSUserNotification/ 用户通知中心实现同样遵循“初始化 → 展示 → 回调 → 终止”的统一生命周期。两个平台的实现都通过 N-APInapi.h暴露给 JavaScript 层这也正是 README 中“基于 N-API 发布预编译二进制、支持不同 Node/Electron 版本”说法的由来。结语desktop-notifications 是一个小而精的范例TypeScript 层给出安全的类型声明与平台能力探测原生层用 N-API 精准对接 Windows Toast 与 macOS 通知。官方文档中的三步生命周期初始化 → 展示/回调 → 清理在源码中一一对应initializeNotifications负责注册 CLSID activatorshowNotification携带userInfo发出通知onNotificationEvent把click事件连同业务数据送回应用。若你需要在 Electron 或 Node 应用中实现 Windows 操作中心可点击的 Toast 通知docs/index.md 是入口lib 与 src 则是可直接研读的完整参考实现。赞分享桌面应用版本控制开发工具【免费下载链接】desktopFocus on what matters instead of fighting with Git.项目地址https://gitcode.com/gh_mirrors/de/desktop点击查看免费下载相关推荐GitHub事件通知系统go-github Notifications API实战GitHub事件通知系统go github Notifications API实战 引言为什么需要GitHub事件通知系统 在现代软件开发流程中团队协作后端API设计Fabric 桌面通知Desktop Notifications完整指南配置、跨平台支持与安全实践Fabric 桌面通知Desktop Notifications完整指南配置、跨平台支持与安全实践 Fabric 是开源的 AI 增强人类工作流框架其桌AI 应用人工智能提示工程CLI本地部署LOTUS开发实战从零构建一个基于语义搜索的智能知识库系统LOTUS开发实战从零构建一个基于语义搜索的智能知识库系统 LOTUS是一款强大的语义查询引擎能够利用LLM技术实现快速、便捷的数据处理。本文将详细介绍如何上一篇vim-minimap 项目常见问题解决方案下一篇如何使用React Native Navigation构建功能强大的跨平台时钟应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
