Share via

ToUnicode 函式 (winuser.h)

  • 發行項

將指定的虛擬按鍵程式代碼和鍵盤狀態轉譯為對應的 Unicode 字元或字元。

語法

int ToUnicode(
  [in]           UINT       wVirtKey,
  [in]           UINT       wScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWSTR     pwszBuff,
  [in]           int        cchBuff,
  [in]           UINT       wFlags
);

參數

[in] wVirtKey

類型： UINT

要翻譯的虛擬金鑰程式代碼。 請參閱 虛擬金鑰代碼。

[in] wScanCode

類型： UINT

要翻譯之金鑰的硬體 掃描代碼 。 如果索引鍵已啟動，則會設定此值的高序位。

[in, optional] lpKeyState

類型： const BYTE*

包含目前鍵盤狀態之 256 位元組陣組的指標。 陣列中的每個元素 (位元組) 都包含一個索引鍵的狀態。

如果已設定位元組的高序位，索引鍵會關閉。 如果設定，則為低位，表示索引鍵已開啟。 在此函式中，只有 CAPS LOCK 鍵的切換位相關。 忽略 NUM LOCK 和 SCROLL LOCK 鍵的切換狀態。 如需詳細資訊，請參閱 GetKeyboardState 。

[out] pwszBuff

類型： LPWSTR

接收轉譯字元或字元做為UTF-16字碼單位陣列的緩衝區。 即使變數名稱建議為 Null 終止，這個緩衝區仍可能會傳回，而不會以 Null 終止。 您可以使用這個方法的傳回值來判斷已寫入的字元數。

[in] cchBuff

類型： int

pwszBuff 參數所指向緩衝區的大小，以字元為單位。

[in] wFlags

類型： UINT

函式的行為。

如果設定了位 0，功能表就會作用中。 在此模式中， 不會處理 Alt+數值按鍵 組合。

如果設定位 2，鍵盤狀態不會變更 (Windows 10 1607 版和更新版本)

保留所有其他位 (到 31) 。

傳回值

類型： int

函式會傳回下列其中一個值。

傳回值 描述
value< 0
 指定的虛擬按鍵是 (腔調字或變音符號) 的 無效索引鍵 字元。 不論鍵盤配置為何，都會傳回這個值，即使已輸入數個字元且儲存在鍵盤狀態也一樣。 可能的話，即使使用 Unicode 鍵盤配置，函式已將寄不出的按鍵字元的間距版本寫入 pwszBuff 所指定的緩衝區。 例如，函式會寫入字元 ACCENT ACCENT (U+00B4) ，而不是將字元結合 (於 U+0301) 。
0
 指定的虛擬按鍵沒有鍵盤目前狀態的轉譯。 未寫入 pwszBuff 所指定的緩衝區。
value > 0
 一或多個 UTF-16 程式代碼單位會寫入 pwszBuff 所指定的緩衝區。 傳回 的 pwszBuff 可能包含超過傳回值所指定的字元。 發生這種情況時，任何額外的字元都無效，而且應該忽略。

備註

若要指定用來翻譯指定程式碼之鍵盤配置的句柄，請使用 ToUnicodeEx函 式。

某些鍵盤配置可能會傳回數個字元和/或增補字元做為 pwszBuff 中的 Surrogate 字組。 如果寄不出的按鍵字元 (輔色或讀音符號) 儲存在鍵盤配置中，無法結合指定的虛擬按鍵來形成單一字元，則先前輸入的無效字元可以與目前的字元結合。

提供給 ToUnicodeEx 函式的參數可能不足以轉譯虛擬按鍵程式代碼，因為先前 的死鍵 會儲存在鍵盤配置中。

一般而言， ToUnicode 會根據虛擬密鑰程式代碼執行轉譯。 不過，在某些情況下， wScanCode 參數的位 15 可用來區分按鍵按下和按鍵放開 (例如 ALT+numpad 鍵輸入) 。

當 ToUnicode 轉譯虛擬按鍵程式代碼時，它也會變更內核模式鍵盤緩衝區的狀態。 此狀態變更會影響死鍵、連字、 Alt+數值鍵盤按鍵 專案等等。 如果與 TranslateMessage (搭配使用，這也可能會造成不想要的副作用，這也會變更內核模式鍵盤緩衝區的狀態) 。

規格需求

需求 值
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 winuser.h (包含 Windows.h)
程式庫 User32.lib
Dll User32.dll

另請參閱

概念

鍵盤輸入

參考

ToAscii

ToUnicodeEx

VkKeyScan