SetThreadPreferredUILanguages 函式 (winnls.h)

  • 發行項

設定目前線程的線程慣用UI語言。 如需詳細資訊，請參閱 使用者介面語言管理。

注意 操作系統也會使用此函式來識別在 Windows 控制臺上安全使用的語言。
 

語法

BOOL SetThreadPreferredUILanguages(
  [in]            DWORD    dwFlags,
  [in, optional]  PCZZWSTR pwszLanguagesBuffer,
  [out, optional] PULONG   pulNumLanguages
);

參數

[in] dwFlags

旗標，識別要設定之語言的格式和篩選。

下列 格式旗標會 指定要用於線程慣用 UI 語言的語言格式。 旗標互斥，預設值為 MUI_LANGUAGE_NAME。

建議您使用 MUI_LANGUAGE_NAME，而不是使用 MUI_LANGUAGE_ID。

值 意義
MUI_LANGUAGE_ID
 輸入參數語言字串的格式為 語言標識碼 。
MUI_LANGUAGE_NAME
 輸入參數語言字串的格式為 語言名稱 。
 

下列 篩選旗標會 指定語言清單的篩選。 旗標互斥。 根據預設，不會設定MUI_COMPLEX_SCRIPT_FILTER或MUI_CONSOLE_FILTER。 如需篩選旗標的詳細資訊，請參閱一節。

值 意義
MUI_COMPLEX_SCRIPT_FILTER

GetThreadPreferredUILanguages 應該將 取代為具有 複雜腳本的所有語言的適當後援。 指定此旗標時，必須針對所有其他參數傳遞 NULL 。
MUI_CONSOLE_FILTER

GetThreadPreferredUILanguages 應該以適當的後援取代所有無法使用目前操作系統設定在控制台視窗中正確顯示的語言。 指定此旗標時，必須針對所有其他參數傳遞 NULL 。
MUI_RESET_FILTERS
 拿掉任何其他篩選設定，以重設語言清單的篩選。 指定此旗標時，必須針對所有其他參數傳遞 NULL 。 設定此旗標之後，應用程式可以呼叫 GetThreadPreferredUILanguages 來擷取完整的未篩選清單。

[in, optional] pwszLanguagesBuffer

雙 Null 終止的多字串緩衝區指標，其中包含 dwFlags 所指定格式的已排序、以 Null 分隔的清單。

若要清除線程慣用的UI語言清單，應用程式會將此參數設定為Null字串或空的雙 Null 終止字串。 如果應用程式清除語言清單，它應該為 dwFlags 參數指定格式旗標或 0。

當應用程式指定其中一個篩選旗標時，它必須將此參數設定為 NULL。 在此情況下，函式會成功，但不會重設線程慣用的語言。

[out, optional] pulNumLanguages

函式在線程慣用UI語言清單中設定的語言數目指標。 當應用程式指定其中一個篩選旗標時，函式必須將此參數設定為 NULL。

傳回值

如果函式成功或 FALSE，則傳回 TRUE 。否則傳回 TRUE 。

備註

當應用程式在呼叫此函式之後載入資源時，線程特定的喜好設定優先於使用者慣用的語言。

此函式可以設定線程最多五種慣用語言，依喜好設定順序。 如果語言緩衝區包含五個以上的有效語言，函式會設定前五個有效語言，並忽略其餘語言。

如果應用程式使用設定MUI_LANGUAGE_ID旗標呼叫此函式，則語言清單中的字元串必須使用十六進位語言

不包含前置 0x 的標識碼，且長度為 4 個字元。 例如，en-US 應該是

傳遞為 “0409”，en 為 “0009”。

指定MUI_LANGUAGE_ID時，語言清單中的十六進位值必須分別代表實際的語言標識符。 特別是，下列地區設定標識符值無法用來對應至語言標識碼：

使用空的語言清單呼叫此函式，並設定 MUI_CONSOLE_FILTER 旗標的效果與呼叫 SetThreadUILanguage 的效果相同，且語言標識符設定為 0。 語言已適當設定，以在主控台視窗中使用。

此函式傳回之後，應用程式可以呼叫 GetThreadPreferredUILanguages 來驗證並檢查產生的語言清單。 當 SetThreadPreferredUILanguages 設定MUI_CONSOLE_FILTER或MUI_COMPLEX_FILTER時， GetThreadPreferredUILanguages 函式會取代為控制台無法使用目前操作系統語言設定顯示的語言後援。 語言的後援是根據語言 LOCALE_SCONSOLEFALLBACKNAME 的值來決定。

在對 SetThreadPreferredUILanguages 的呼叫中設定MUI_COMPLEX_SCRIPT_FILTER旗標會導致 GetThreadPreferredUILanguages 移除控制台無法使用只能使用 Uniscribe 轉譯的語言來顯示的語言，並將後援語言插入為最終後援。 這類語言的範例包括阿拉伯文或各種索引語言。

在對 SetThreadPreferredUILanguages 的呼叫中設定MUI_CONSOLE_FILTER旗標會導致 GetThreadPreferredUILanguages 移除控制台無法使用目前的系統設定顯示的語言，並將後援語言插入為最終後援，因為控制台僅限於顯示單一 代碼頁中的字元。 例如，如果用戶語言是日文 (日本) ，但目前的控制台代碼頁是俄文 (俄羅斯文) 的代碼頁，控制台主要會顯示日文語言文字作為一系列的字元找不到符號。 GetThreadPreferredUILanguages 會從後援清單中選擇可在控制台中辨識的語言。

注意 資源載入函式，例如 LoadString、 LoadImage 和 FindResource，也會呼叫 GetThreadPreferredUILanguages。
 
若要變更代碼頁，應用程式會使用 setlocale 函式或對等專案。

C# 簽章

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean SetThreadPreferredUILanguages(
            System.UInt32 dwFlags,
            System.String pwszLanguagesBuffer,
            ref System.UInt32 pulNumLanguages
            );

規格需求

需求 值
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 winnls.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

GetThreadPreferredUILanguages

多語系使用者介面

多語系使用者介面函式

SetThreadUILanguage