Share via

ToUnicodeEx 函式 (winuser.h)

  • 發行項

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

語法

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

參數

[in] wVirtKey

類型： UINT

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

[in] wScanCode

類型： UINT

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

[in] 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+數值按鍵 組合。

如果設定位 1，ToUnicodeEx 會轉譯標示為按鍵中斷事件的掃描碼，除了其一般處理密鑰製作事件之外。

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

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

[in, optional] dwhkl

類型： HKL

用來轉譯指定程式代碼的輸入地區設定標識碼。 此參數可以是 LoadKeyboardLayout 函式先前傳回的任何輸入地區設定標識符。

傳回值

類型： int

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

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

備註

輸入地區設定標識碼是比鍵盤版面配置更廣泛的概念，因為它也可以包含語音轉換程式、輸入方法 編輯器 (輸入法) 或任何其他形式的輸入。

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

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

一般而言， ToUnicodeEx 會根據虛擬機碼程式代碼執行翻譯。 不過，在某些情況下， wScanCode 參數的位 15 可用來區分按鍵按下和按鍵釋放 (，例如 ALT+numpad 按鍵專案) 。

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

規格需求

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

另請參閱

概念

鍵盤輸入

LoadKeyboardLayout

參考

ToAsciiEx

VkKeyScan