Shell_NotifyIconA 函式 (shellapi.h)

發行項
03/01/2024

將訊息傳送至任務欄的狀態區域。

語法

BOOL Shell_NotifyIconA(
  [in] DWORD            dwMessage,
  [in] PNOTIFYICONDATAA lpData
);

參數

[in] dwMessage

類型： DWORD

值，指定要由此函式採取的動作。其值可以是下列其中一個值：

NIM_ADD (0x00000000)

0x00000000。將圖示新增至狀態區域。圖示會透過其 uID 或 guidItem 成員，在 lpdata 所指向的 NOTIFYICONDATA 結構中提供識別符。此標識碼用於 後續對Shell_NotifyIcon 的呼叫，以在圖示上執行稍後的動作。

NIM_MODIFY (0x00000001)

0x00000001。修改狀態區域中的圖示。 lpdata 所指向的 NOTIFYICONDATA 結構會使用最初指派給圖標的標識碼，將它新增至通知區域 (NIM_ADD) ，以識別要修改的圖示。

NIM_DELETE (0x00000002)

0x00000002。從狀態區域刪除圖示。 lpdata 所指向的 NOTIFYICONDATA 結構會在將標識元新增至通知區域時使用原本指派給圖示的標識符， (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 訊息。
如果使用者選取鍵盤的通知圖示，並使用SPACEBAR或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。

不論操作系統版本為何，您都可以藉由呼叫 Shell_NotifyIcon ，將 dwMessage 設定為 NIM_SETVERSION，來選取 Shell 的行為。設定 lpdata 所指向 NOTIFYICONDATA 結構的 uVersion 成員，以指出您是否要 Windows 2000、Windows Vista 或版本 5.0 (Windows 95) 行為。

注意上述訊息不是傳統 Windows 訊息。當呼叫 Shell_NotifyIcon時，會以 dwMessage 中設定的 NIM_ADD 旗標來呼叫 NOTIFYICONDATA 結構 uCallbackMessage 成員中指定的應用程式定義訊息 lParam 值。

從 Windows XP Service Pack 2 (SP2) 開始，自定義圖示可以顯示在通知方塊中。這可讓呼叫程式自定義先前可用資訊、警告和錯誤選項以外的通知，並區分它與使用者的其他類型的通知。

注意

shellapi.h 標頭會將Shell_NotifyIcon定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	shellapi.h
程式庫	Shell32.lib
Dll	Shell32.dll (4.0 版或更新版本)
API 集合	ext-ms-win-shell32-l1-2-1 (於 Windows 10 10.0.10240 版)

另請參閱

通知和通知區域