NOTIFYICONDATAW 結構 (shellapi.h)

發行項
03/08/2023

包含系統需要在通知區域中顯示通知的資訊。由Shell_NotifyIcon使用。

語法

typedef struct _NOTIFYICONDATAW {
  DWORD cbSize;
  HWND  hWnd;
  UINT  uID;
  UINT  uFlags;
  UINT  uCallbackMessage;
  HICON hIcon;
#if ...
  WCHAR szTip[64];
#else
  WCHAR szTip[128];
#endif
  DWORD dwState;
  DWORD dwStateMask;
  WCHAR szInfo[256];
  union {
    UINT uTimeout;
    UINT uVersion;
  } DUMMYUNIONNAME;
  WCHAR szInfoTitle[64];
  DWORD dwInfoFlags;
  GUID  guidItem;
  HICON hBalloonIcon;
} NOTIFYICONDATAW, *PNOTIFYICONDATAW;

成員

cbSize

類型： DWORD

這個結構的大小，以位元組為單位。

hWnd

類型： HWND

視窗的控制碼，可接收與通知區域中圖示相關聯的通知。

uID

類型： UINT

工作列圖示的應用程式定義識別碼。 Shell 會使用 (hWnd 加上 uID) 或 guidItem 來識別叫用 Shell_NotifyIcon 時要運作的圖示。您可以為每個不同的uID指派多個與單一hWnd相關聯的圖示。如果指定 guidItem ， 則會忽略 uID 。

uFlags

類型： UINT

旗標，指出結構的哪些其他成員包含有效的資料，或提供工具提示的其他資訊，以說明其顯示方式。這個成員可以是下列值的組合：

NIF_MESSAGE (0x00000001)

0x00000001。 uCallbackMessage成員有效。

NIF_ICON (0x00000002)

0x00000002。 hIcon成員有效。

NIF_TIP (0x00000004)

0x00000004。 szTip成員有效。

NIF_STATE (0x00000008)

0x00000008。 dwState 和dwStateMask成員有效。

NIF_INFO (0x00000010)

0x00000010。顯示球形通知。 szInfo、szInfoTitle、dwInfoFlags和uTimeout成員都是有效的。請注意， uTimeout 僅適用于 Windows 2000 和 Windows XP。

若要顯示氣球通知，請指定NIF_INFO並提供 szInfo中的文字。
若要移除氣球通知，請指定NIF_INFO，並透過 szInfo提供空字串。
若要新增通知區域圖示而不顯示通知，請勿設定NIF_INFO旗標。

NIF_GUID (0x00000020)

0x00000020。

Windows 7 和更新版本： guidItem 有效。
Windows Vista 和更早版本：保留。

NIF_REALTIME (0x00000040)

0x00000040。 Windows Vista 和更新版本。如果無法立即顯示批註通知，請捨棄它。將此旗標用於代表即時資訊的通知，如果稍後顯示，則為無意義或誤導的資訊。例如，指出「您的電話正在響鈴」的訊息。只有在與 NIF_INFO 旗標結合時，NIF_REALTIME才有意義。

NIF_SHOWTIP (0x00000080)

0x00000080。 Windows Vista 和更新版本。使用標準工具提示。一般而言， 當 uVersion 設定為 NOTIFYICON_VERSION_4 時，標準工具提示會隱藏，而且可由應用程式繪製的快顯 UI 取代。如果應用程式想要顯示具有NOTIFYICON_VERSION_4的標準工具提示，它可以指定NIF_SHOWTIP來表示仍應該顯示標準工具提示。

uCallbackMessage

類型： UINT

應用程式定義的訊息識別碼。系統會使用此識別碼，將通知訊息傳送至 hWnd中所識別的視窗。這些通知訊息會在滑鼠事件或暫留出現在圖示的周框、使用鍵盤選取或啟動圖示時，或這些動作發生在球形通知中時傳送。

當 uVersion 成員為 0 或 NOTIFYICON_VERSION時，訊息的 wParam 參數會包含發生事件之工作列圖示的識別碼。此識別碼長度可以是 32 位。 lParam參數會保存與事件相關聯的滑鼠或鍵盤訊息。例如，當指標移至工作列圖示上方時， lParam 會設定為 WM_MOUSEMOVE。

當 uVersion 成員NOTIFYICON_VERSION_4時，應用程式會繼續透過 uCallbackMessage 成員以應用程式定義訊息的形式接收通知事件，但該訊息的 lParam 和 wParam 參數解譯會變更如下：

LOWORD (lParam) 包含通知事件，例如NIN_BALLOONSHOW、NIN_POPUPOPEN或WM_CONTEXTMENU。
HIWORD (lParam) 包含圖示識別碼。圖示識別碼限制為 16 位的長度。
GET_X_LPARAM (wParam) 傳回通知事件的 X 錨點座標NIN_POPUPOPEN、NIN_SELECT、NIN_KEYSELECT，以及WM_MOUSEFIRST與WM_MOUSELAST之間的所有滑鼠訊息。如果鍵盤產生任何訊息， wParam 會設定為靶心圖表標的左上角。針對所有其他訊息， wParam 未定義。
GET_Y_LPARAM (wParam) 傳回 X 錨點所定義的通知事件和訊息的 Y 錨點座標。

hIcon

類型： HICON

要加入、修改或刪除之圖示的控制碼。 Windows XP 和更新版本支援最多 32 BPP 的圖示。

如果只提供 16x16 圖元圖示，則會將系統內的大小調整為高 DPI 值。這可能會導致不具吸引力的結果。建議您在資源檔中同時提供 16x16 圖元圖示和 32x32 圖示。使用 LoadIconMetric 確保已適當地載入和調整正確的圖示。如需程式碼範例，請參閱。

szTip[64]

類型： TCHAR[64]

以 Null 結尾的字串，指定標準工具提示的文字。最多可以有 64 個字元，包括終止的 Null 字元。

針對 Windows 2000 和更新版本， szTip 最多可以有 128 個字元，包括終止的 Null 字元。

szTip[128]

類型： TCHAR[64]

以 Null 結尾的字串，指定標準工具提示的文字。最多可以有 64 個字元，包括終止的 Null 字元。

針對 Windows 2000 和更新版本， szTip 最多可以有 128 個字元，包括終止的 Null 字元。

dwState

類型： DWORD

Windows 2000 和更新版本。圖示的狀態。下列其中一個或兩個值：

NIS_HIDDEN (0x00000001)

0x00000001。圖示已隱藏。

NIS_SHAREDICON (0x00000002)

0x00000002。圖示資源會在多個圖示之間共用。

dwStateMask

類型： DWORD

Windows 2000 和更新版本。值，指定擷取或修改 dwState 成員的位。可能的值與 dwState的值相同。例如，將此成員設定為 NIS_HIDDEN 只會在忽略圖示共用位時修改專案的隱藏狀態，而不論其值為何。

szInfo[256]

類型： TCHAR[256]

Windows 2000 和更新版本。以 Null 結束的字串，指定要顯示在批註方塊通知中的文字。它最多可以有 256 個字元，包括終止的 Null 字元，但應該限制為英文的 200 個字元以容納當地語系化。若要從 UI 移除批註方塊通知，請刪除具有NIM_DELETE) 的圖示 (，或在uFlags中設定NIF_INFO旗標，並將szInfo設定為空字串。

DUMMYUNIONNAME

DUMMYUNIONNAME.uTimeout

類型： UINT

Windows 2000 和更新版本。

注意從 Windows Vista 起，此成員已被取代。通知顯示時間現在會根據系統協助工具設定。

與 uVersion聯集。通知的逾時值，以毫秒為單位。系統會強制執行最小和最大逾時值。 uTimeout中指定的值太大，會設定為最大值。太小的值預設為最小值。系統最小和最大逾時值目前分別設定為 10 秒和 30 秒。如需 uTimeout的進一步討論，請參閱。

DUMMYUNIONNAME.uVersion

類型： UINT

Windows 2000 和更新版本。從 Windows Vista) 起， 與 uTimeout (聯集。指定應該使用哪個版本的 Shell 通知圖示介面。如需這些版本差異的詳細資訊，請參閱 Shell_NotifyIcon。只有在使用 Shell_NotifyIcon 傳送 NIM_SETVERSION 訊息時，才會採用這個成員。

szInfoTitle[64]

類型： TCHAR[64]

Windows 2000 和更新版本。以 Null 結束的字串，指定批註方塊通知的標題。此標題會出現在文字正上方的較大字型中。最多可以有 64 個字元，包括終止的 Null 字元，但應該限制為英文的 48 個字元，以容納當地語系化。

dwInfoFlags

類型： DWORD

Windows 2000 和更新版本。可設定為修改批註方塊通知行為和外觀的旗標。圖示會放在標題的左邊。如果 szInfoTitle 成員長度為零，則不會顯示圖示。

NIIF_NONE (0x00000000)

0x00000000。無圖示。

NIIF_INFO (0x00000001)

0x00000001。資訊圖示。

NIIF_WARNING (0x00000002)

0x00000002。警告圖示。

NIIF_ERROR (0x00000003)

0x00000003。錯誤圖示。

NIIF_USER (0x00000004)

0x00000004。 Windows XP SP2 和更新版本。

Windows XP：使用 hIcon 中識別的圖示作為通知方塊的標題圖示。
Windows Vista 和更新版本：使用 hBalloonIcon 中所識別的圖示作為通知方塊的標題圖示。

NIIF_NOSOUND (0x00000010)

0x00000010。 Windows XP 和更新版本。請勿播放相關聯的音效。僅適用于通知。

NIIF_LARGE_ICON (0x00000020)

0x00000020。 Windows Vista 和更新版本。大型版本的圖示應該用來做為通知圖示。這會對應至SM_CXICON x SM_CYICON維度的圖示。如果未設定此旗標，則會使用維度SM_CXSMICON x SM_CYSMICON的圖示。

此旗標可以搭配所有股票圖示使用。
搭配 hIcon (NIIF_USER) 使用舊版自訂圖示的應用程式，必須在匣圖示 (hIcon) 中提供新的 SM_CXICON x SM_CYICON 版本。這些圖示會在系統匣或系統控制台 (SCA) 中顯示時相應減少。
使用 hBalloonIcon) (NIIF_USER的新自訂圖示必須在提供的圖示 (hBalloonIcon) 中提供SM_CXICON x SM_CYICON版本。

NIIF_RESPECT_QUIET_TIME (0x00000080)

0x00000080。 Windows 7 和更新版本。如果目前的使用者處於「無訊息時間」，請勿顯示氣球通知，這是新使用者第一次登入其帳戶之後的第一小時。在此期間，不應該傳送或顯示大部分的通知。這可讓使用者習慣使用新的電腦系統，而不會干擾這些系統。作業系統升級或全新安裝之後，每個使用者也會發生無訊息時間。在無訊息時間以這個旗標傳送的通知不會排入佇列;它只是關閉而未擁有。如果應用程式在該時間仍然有效，應用程式稍後可以重新傳送通知。

由於應用程式無法預測何時可能會遇到無訊息時間，因此我們建議任何表示接受無訊息時間的應用程式一律會在所有適當的通知上設定此旗標。

在無訊息期間，某些通知仍應該傳送，因為使用者預期會以回應使用者動作的意見反應，例如當他或她插入 USB 裝置或列印檔案時。

如果目前的使用者不在無訊息時間，則此旗標沒有任何作用。

NIIF_ICON_MASK (0x0000000F)

0x0000000F。 Windows XP 和更新版本。保留的。

guidItem

類型： GUID

Windows XP 和更新版本。

Windows 7 和更新版本：可識別圖示的已註冊 GUID。此值會覆寫 uID ，而且是識別圖示的建議方法。 NIF_GUID旗標必須在 uFlags 成員中設定。
Windows XP 和 Windows Vista：保留;必須設定為 0。

如果您的應用程式是要在 Windows Vista 和 Windows 7 上執行，請務必檢查 Windows 版本，而且只有在 Windows 7 或更新版本時才指定非零 guidItem 。

如果您在一次呼叫 Shell_NotifyIcon中識別具有 GUID 的通知圖示，則必須使用該相同的 GUID 來識別處理該相同圖示的任何後續 Shell_NotifyIcon 呼叫中的圖示。

若要產生要用於此成員的 GUID，請使用 GUID 產生工具，例如Guidgen.exe。

hBalloonIcon

類型： HICON

Windows Vista 和更新版本。應用程式所提供的自訂通知圖示控制碼，應該與通知區域圖示無關。如果這個成員不是 Null，而且NIIF_USER旗標是在 dwInfoFlags 成員中設定，則會使用此圖示做為通知圖示。如果此成員為 Null，則會執行舊版行為。

備註

如需通知 UI 和內容最佳做法的詳細資訊，請參閱 Windows 使用者體驗互動指導方針中的通知。

如果您在uFlags成員中設定NIF_INFO旗標，則會使用批註樣式通知。如需這些通知的詳細資訊，請參閱批註工具提示。

一次不能顯示一個以上的球形通知工作列。如果應用程式嘗試在顯示通知時顯示通知，新的通知會排入佇列，並在較舊的通知消失時顯示。在 Windows Vista 之前的 Windows 版本中，不論原始通知的 uTimeout 值為何，在至少系統最小逾時長度顯示現有通知之前，才會顯示新的通知。如果使用者似乎未使用電腦，則系統不會將此時間計入逾時。

只有 Windows 2000 和更新版本才支援此結構的數個成員。若要啟用這些成員，請在標頭中包含下列其中一行：

// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA

// Windows XP and earlier:
#define _WIN32_IE 0x0500

請注意，您必須使用其大小來初始化結構。如果您使用目前定義的結構大小，應用程式可能無法與舊版Shell32.dll一起執行，這預期結構較小。您可以定義適當的版本號碼，以針對舊版Shell32.dll執行應用程式 (，請參閱殼層和通用控制項版本) 。不過，如果您的應用程式也需要在較新的系統上執行，這可能會造成問題。

您可以適當地設定 NOTIFYICONDATA 結構的大小，以維持與所有Shell32.dll版本的應用程式相容性，同時仍使用目前的標頭檔。在初始化結構之前，請使用 DllGetVersion 來判斷系統上已安裝哪一個Shell32.dll版本，並使用下列其中一個值初始化 cbSize ：

Shell32.dll版本	cbSize
6.0.6 或更高版本 (Windows Vista 和更新版本)	sizeof (NOTIFYICONDATA)
6.0 (Windows XP)	NOTIFYICONDATA_V3_SIZE
5.0 (Windows 2000)	NOTIFYICONDATA_V2_SIZE
低於 5.0 的版本	NOTIFYICONDATA_V1_SIZE

針對 cbSize 使用此值可讓您的應用程式在與舊版Shell32.dll相容的方法中使用 NOTIFYICONDATA 。

下列程式碼範例顯示版本檢查，可讓使用 guidItem 成員的應用程式同時在 Windows Vista 和 Windows 7 上執行。它會提供布耳函數，如果作業系統是 Windows 7，則會傳回 TRUE 。除非此成員傳回 TRUE， 否則 guidItem 成員必須設定為 0。

注意此程式碼專屬於 Windows 7 版本號碼。預期未來的 Windows 和 Windows Server 版本將支援 guidItem 成員，而且此時必須更新此程式碼，才能識別較新的版本號碼也有效。

BOOL IsWin7OrLater()
{
    // Initialize the OSVERSIONINFOEX structure.
    OSVERSIONINFOEX osvi;
    ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
    osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
    osvi.dwMajorVersion = 6;
    osvi.dwMinorVersion = 1;

    // Initialize the condition mask.
    DWORDLONG dwlConditionMask = 0;
    VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);
    VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);

    // Perform the test.
    return VerifyVersionInfo(&osvi, 
                             VER_MAJORVERSION | VER_MINORVERSION,
                             dwlConditionMask);
}

下列程式碼範例示範如何使用 LoadIconMetric 來載入圖示，以搭配高 DPI 使用。

// Declare NOTIFYICONDATA details. 
// Error handling is omitted here for brevity. Do not omit it in your code.

NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;

// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID = 
    {0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;

// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");

// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));

// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;

疑難排解

如果您使用 guidItem 成員來識別圖示，而且看不到該圖示，或 Shell_NotifyIcon 的某些呼叫失敗，下列其中一個情況可能是原因：

NIF_GUID旗標未在每個呼叫中設定Shell_NotifyIcon。一旦您在呼叫 Shell_NotifyIcon時，使用 GUID 識別通知圖示之後，您必須使用相同的 GUID 來識別處理該相同圖示的任何後續 Shell_NotifyIcon 呼叫中的圖示。
包含圖示的二進位檔案已移動。二進位檔案的路徑包含在圖示 GUID 的註冊中，而且無法變更。只有在檔案路徑和 GUID 未變更時，才會透過升級來保留與圖示相關聯的設定。如果路徑必須變更，應用程式應該移除註冊現有圖示時新增的任何 GUID 資訊。移除該資訊之後，您可以將二進位檔案移至新的位置，並使用新的 GUID 重新註冊該檔案。與原始 GUID 註冊相關聯的任何設定都會遺失。
這也會在並存安裝的情況下發生。處理並存安裝時，新版本的應用程式應該更新二進位檔案的 GUID。

注意當原始和移動的二進位檔案都是由同一家公司簽署 Authenticode時，才會發生移動檔案的唯一例外狀況。在此情況下，會透過移動來保留設定。

注意

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

規格需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
標頭	shellapi.h

另請參閱

通知和通知區域

共用方式為

NOTIFYICONDATAW 結構 (shellapi.h)

語法

成員

NIF_MESSAGE (0x00000001)

NIF_ICON (0x00000002)

NIF_TIP (0x00000004)

NIF_STATE (0x00000008)

NIF_INFO (0x00000010)

NIF_GUID (0x00000020)

NIF_REALTIME (0x00000040)

NIF_SHOWTIP (0x00000080)

NIS_HIDDEN (0x00000001)

NIS_SHAREDICON (0x00000002)

NIIF_NONE (0x00000000)

NIIF_INFO (0x00000001)

NIIF_WARNING (0x00000002)

NIIF_ERROR (0x00000003)

NIIF_USER (0x00000004)

NIIF_NOSOUND (0x00000010)

NIIF_LARGE_ICON (0x00000020)

NIIF_RESPECT_QUIET_TIME (0x00000080)

NIIF_ICON_MASK (0x0000000F)

備註

疑難排解

規格需求

另請參閱

意見反應

其他資源