Shell_NotifyIconW 函数 (shellapi.h)

项目
05/30/2024

将消息发送到任务栏的状态区域。

语法

BOOL Shell_NotifyIconW(
  [in] DWORD            dwMessage,
  [in] PNOTIFYICONDATAW lpData
);

参数

[in] dwMessage

类型：DWORD

一个值，该值指定要由此函数执行的操作。可以具有以下一个值：

NIM_ADD (0x00000000)

0x00000000。将图标添加到状态区域。图标在 lpdata 通过其 uID 或 guidItem 成员指向的 NOTIFYICONDATA 结构中提供标识符。此标识符用于对 Shell_NotifyIcon 的后续调用，以便对图标执行后续操作。

NIM_MODIFY (0x00000001)

0x00000001。修改状态区域中的图标。 lpdata 指向的 NOTIFYICONDATA 结构使用最初在将图标添加到通知区域时分配给该图标的 ID (NIM_ADD) 来标识要修改的图标。

NIM_DELETE (0x00000002)

0x00000002。从状态区域中删除图标。 lpdata 指向的 NOTIFYICONDATA 结构使用最初在将图标添加到通知区域时分配给该图标的 ID (NIM_ADD) 来标识要删除的图标。

NIM_SETFOCUS (0x00000003)

0x00000003。仅Shell32.dll 版本 5.0 及更高版本。将焦点返回到任务栏通知区域。通知区域图标在完成 UI 操作后应使用此消息。例如，如果图标显示快捷菜单，但用户按 ESC 将其取消，请使用 NIM_SETFOCUS 将焦点返回到通知区域。

NIM_SETVERSION (0x00000004)

0x00000004。仅Shell32.dll 版本 5.0 及更高版本。指示通知区域按照 lpdata 所指向结构的 uVersion 成员中指定的版本号的行为。版本号指定可识别的成员。

每次 (NIM_ADD) 添加通知区域图标时，都必须调用NIM_SETVERSION。不需要使用 NIM_MODIFY 调用它。用户注销后，版本设置不会保留。

有关详细信息，请参见“备注”部分。

[in] lpData

类型： PNOTIFYICONDATA

指向 NOTIFYICONDATA 结构的指针。结构的内容取决于 dwMessage 的值。它可以定义要添加到通知区域的图标、使该图标显示通知，或标识要修改或删除的图标。

返回值

类型： BOOL

如果成功，则返回 TRUE ，否则返回 FALSE 。如果 dwMessage 设置为 NIM_SETVERSION，则如果成功更改版本，则函数返回 TRUE ;如果不支持请求的版本，则返回 FALSE 。

注解

从 Windows 2000 (Shell32.dll 版本 5.0) 开始，如果将 lpdata 指向的 NOTIFYICONDATA 结构的 uVersion 成员设置为 NOTIFYICON_VERSION_4 或更高版本，Shell_NotifyIcon鼠标和键盘事件的处理方式与早期版本的 Windows 不同。差异包括：

如果用户使用键盘选择通知图标的快捷菜单，Shell 现在会向关联的应用程序发送 WM_CONTEXTMENU 消息。早期版本发送 WM_RBUTTONDOWN 和 WM_RBUTTONUP 消息。
如果用户使用键盘选择通知图标并使用空格键或 ENTER 键激活它，则 5.0 版 Shell 会向关联的应用程序发送NIN_KEYSELECT通知。早期版本发送 WM_RBUTTONDOWN 和 WM_RBUTTONUP 消息。
如果用户使用鼠标选择通知图标并使用 ENTER 键激活它，Shell 现在会向关联的应用程序发送NIN_SELECT通知。早期版本发送 WM_RBUTTONDOWN 和 WM_RBUTTONUP 消息。

从 Windows XP (Shell32.dll 版本 6.0) 起，如果用户将鼠标指针传递到与气球通知关联的图标上，Shell 将发送以下消息：

NIN_BALLOONSHOW。显示气球时发送， (气球排队) 。
NIN_BALLOONHIDE。当气球消失时发送。例如，删除图标时。如果因超时而关闭气球，或者用户单击鼠标，则不会发送此消息。
从 Windows 7 开始，当用户在新计算机上) (第一个小时的静默时间尝试显示设置了 NIIF_RESPECT_QUIET_TIME 标志的通知时，也会发送NIN_BALLOONHIDE。在这种情况下，从不显示气球。
NIN_BALLOONTIMEOUT。在因超时而关闭气球时发送。
NIN_BALLOONUSERCLICK。关闭气球时发送，因为用户单击了鼠标。

除了这些消息，从 Windows Vista (Shell32.dll 版本 6.0.6) 开始，如果用户将鼠标指针传递到与气球通知关联的图标上，Windows Vista Shell 还会添加以下消息：

NIN_POPUPOPEN。当用户将光标悬停在图标上以指示应使用更丰富的弹出 UI 代替标准文本工具提示时发送。
NIN_POPUPCLOSE。当光标不再悬停在图标上以指示应关闭丰富的弹出 UI 时发送。

无论操作系统版本如何，都可以通过在 dwMessage设置为 NIM_SETVERSION 的情况下调用 Shell_NotifyIcon 来选择 Shell 的行为方式。设置 lpdata 指向的 NOTIFYICONDATA 结构的 uVersion 成员，以指示你希望 Windows 2000、Windows Vista 或 5.0 版本 (Windows 95) 行为。

注意上面讨论的消息不是传统的 Windows 消息。 Shell_NotifyIcon 当使用 dwMessage 中设置的 NIM_ADD 标志调用时，它们作为应用程序定义的消息的 lParam 值发送，该消息是在 lpdata 指向的 NOTIFYICONDATA 结构的 uCallbackMessage 成员中指定的。

从 Windows XP Service Pack 2 (SP2) 开始，自定义图标可以显示在通知气球中。这允许调用进程自定义之前可用的信息、警告和错误选项之外的通知，并将其与其他类型的用户通知区分开来。

在 Windows 10 上，气球消息显示为横幅通知，然后保留在通知中心直到关闭。在 Windows 11 上，横幅通知的行为更严格地遵循传统行为，使其成为暂时性的通知。当禁止通知超时或以其他方式消除时，通知中心不会显示该通知。

注意

shellapi.h 标头将 Shell_NotifyIcon 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shellapi.h
Library	Shell32.lib
DLL	Shell32.dll (4.0 或更高版本)
API 集	windows 10 版本 10.0.10240 中引入的 ext-ms-win-shell-shell32-l1-2-1 ()

另请参阅

通知和通知区域

通过