• 图形学
• 桌面应用

导读

Windows 桌面应用几乎离不开系统托盘（通知区域）图标：后台驻留、消息提醒、快捷菜单都依赖它。本文以 RGF 仓颉版（RGF_CJ）rgf.win_def子包中的_NOTIFYICONDATAW结构体为线索，完整讲解该结构体的 15 个构造参数、内嵌联合体属性、配套的NIM_*/NIF_*/NIIF_*常量，以及底层的Shell_NotifyIconW绑定与wShell_NotifyIconW安全封装。读完本文，你可以在 RGF 应用中从零添加、修改、删除托盘图标，并正确设置气泡通知与通知版本号。

一、_NOTIFYICONDATAW是什么

_NOTIFYICONDATAW是 RGF 对 Windows 原生结构体NOTIFYICONDATAW（ShellAPI，宽字符版本）的仓颉语言映射，用于向系统 Shell 描述"一个托盘图标该长什么样、有哪些字段有效、显示什么气泡提示"。它带有@C标注，表明该结构体与 C ABI 布局兼容，可安全地传给底层 foreign 函数：

@C public struct _NOTIFYICONDATAW

在 hshellapi.cj 中可以看到它唯一的构造函数，所有字段都带默认值，这意味着你只需要为关心的字段传参即可：

public _NOTIFYICONDATAW( let cbSize!:DWORD = UInt32(sizeOf<_NOTIFYICONDATAW>()), let hWnd!:HWND = HWND(), let uID!:UINT = 0, let uFlags!:UINT = 0, let uCallbackMessage!:UINT = 0, let hIcon!:HICON = HICON(), let szTip!:VArray<WCHAR,$128> = VArray<WCHAR, $128>(repeat: 0), let dwState!:DWORD = 0, let dwStateMask!:DWORD = 0, let szInfo!:VArray<WCHAR,$256> = VArray<WCHAR, $256>(repeat: 0), let unionU!:UINT = 0, let szInfoTitle!:VArray<WCHAR,$64> = VArray<WCHAR, $64>(repeat: 0), let dwInfoFlags!:DWORD = 0, let guidItem!:GUID = GUID(), let hBalloonIcon!:HICON = HICON() )

二、构造参数逐一详解

结构与 Win32 原生定义一一对应，字段语义如下：

定长宽字符数组字段

szTip、szInfo、szInfoTitle三个字段均为仓颉的定长数组类型VArray<WCHAR, $N>（依次为 128、256、64），并在构造时默认用repeat: 0整体清零。写入文本时需注意字节上限：szTip最多 127 个字符、szInfo最多 255 个字符、szInfoTitle最多 63 个字符（均需保留一个宽字符作为终止符），超长内容会被系统截断。

三、联合体：uTimeout与uVersion

结构体内部第 10 个参数unionU是一个联合体占位字段（源码中以注释"这是一个联合体"标明），它根据使用场景有两种语义，分别通过两个只读属性暴露：

public prop uTimeout:UINT{ get(){ unionU }; } public prop uVersion:UINT{ get(){ unionU }; }

• uTimeout：当调用NIM_MODIFY且uFlags含NIF_INFO时，表示气泡通知的显示时长（毫秒）。系统会按该值决定气泡停留时间。
• uVersion：配合NIM_SETVERSION使用，表示 Shell 通知接口版本。应用可传入版本号（经典为NOTIFYICON_VERSION）来获得对应的回调行为与消息格式。

由于两者共享同一块内存，实际使用中需按当前操作语义选择对应的属性理解其含义。

四、类型别名与指针形态

与结构体配套，hshellapi.cj 还定义了两种常用形态：

public type NOTIFYICONDATAW = _NOTIFYICONDATAW public type PNOTIFYICONDATAW = CPointer<_NOTIFYICONDATAW>

• NOTIFYICONDATAW：不带下划线的便捷别名，面向日常书写；
• PNOTIFYICONDATAW：结构体指针，用于与底层 foreign 函数对接。

五、配套常量：NIM、NIF、NIIF 三组标志

使用该结构体必然涉及三组常量，全部定义在 hshellapi.cj，类型均为UInt32：

NIM_（Shell_NotifyIconW 的 dwMessage 操作码）

NIF_（uFlags 有效字段标志，可按位或）

NIIF_（dwInfoFlags 气泡图标标志）

六、调用入口：wShell_NotifyIconW封装

_NOTIFYICONDATAW结构体本身不产生任何行为，真正驱动它的是 ShellAPI 的Shell_NotifyIconW。RGF 在 hshellapi.cj 中先以 foreign 函数声明原生入口，再提供安全封装：

foreign func Shell_NotifyIconW(dwMessage:DWORD, lpData:PNOTIFYICONDATAW):WINBOOL; public func wShell_NotifyIconW(dwMessage:DWORD, data:NOTIFYICONDATAW):Bool{ var tmp = data unsafe{ Shell_NotifyIconW(dwMessage,inout tmp) } != 0 }

封装要点：

• 接收按值传递的结构体，内部复制到局部变量后以inout取地址传给 foreign 函数，屏蔽了底层指针操作；
• 将 Win32 的WINBOOL返回值转换为仓颉Bool（非 0 即为true）；
• 该函数签名也同步登记在rgf.win_defAPI 列表与函数文档中，供开发者直接检索使用。

七、完整使用示例

结合上述 API，一个典型的托盘图标生命周期如下（示意代码，需配合 RGF 窗口句柄使用）：

// 1. 添加托盘图标：设置窗口句柄、图标、提示文本与回调消息 let nid = _NOTIFYICONDATAW( hWnd = hwnd, // 承载回调的窗口 uID = 1, // 图标标识 uFlags = NIF_MESSAGE | NIF_ICON | NIF_TIP, uCallbackMessage = 0x8000, // 自定义托盘回调消息 hIcon = hIcon, // 图标句柄 szTip = /* 填充不超过 127 个宽字符 */, szInfo = /* 填充不超过 255 个宽字符 */, szInfoTitle = /* 填充不超过 63 个宽字符 */, dwInfoFlags = NIIF_INFO ) wShell_NotifyIconW(NIM_ADD, nid) // true 表示成功 // 2. 修改气泡通知内容 let nid2 = _NOTIFYICONDATAW( hWnd = hwnd, uID = 1, uFlags = NIF_INFO, szInfo = /* 新通知正文 */, szInfoTitle = /* 新标题 */, dwInfoFlags = NIIF_WARNING ) wShell_NotifyIconW(NIM_MODIFY, nid2) // 3. 删除托盘图标 wShell_NotifyIconW(NIM_DELETE, _NOTIFYICONDATAW(hWnd = hwnd, uID = 1))

八、版本与系统要求注意

• hBalloonIcon与NIIF_LARGE_ICON均要求Windows Vista 及以上（NTDDI_VERSION >= 0x06000000），源码注释已明确标注；
• NIIF_RESPECT_QUIET_TIME要求Windows 7 及以上（NTDDI_VERSION >= 0x06010000）；
• 涉及unionU时，NIM_SETVERSION场景按uVersion理解、NIF_INFO气泡场景按uTimeout（毫秒）理解，二者不可混用。

九、延伸阅读

• 结构体完整定义：_NOTIFYICONDATAW
• 底层源码实现：src/win_def/hshellapi.cj
• 调用函数文档：wShell_NotifyIconW
• 常量全集：rgf.win_def变量与常量
• 子包总览：rgf.win_defreadme

• 图形学
• 桌面应用