GetTimeFormatEx 函式 (datetimeapi.h)

發行項
04/06/2023

將時間格式化為名稱所指定地區設定的時間字串。函式會格式化指定的時間或本機系統時間。

注意如果設計為只在 Windows Vista 和更新版本上執行，應用程式應該優先呼叫此函式給 GetTimeFormat 。

注意此函式可以格式化版本之間變更的資料，例如，因為自訂地區設定。如果您的應用程式必須保存或傳輸資料，請參閱使用持續性地區設定資料。

語法

int GetTimeFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

參數

[in, optional] lpLocaleName

地區設定名稱的指標，或下列其中一個預先定義的值。

[in] dwFlags

指定時間格式選項的旗標。應用程式可以指定下列值和 LOCALE_USE_CP_ACP 或 LOCALE_NOUSEROVERRIDE的組合。

謹慎強烈建議不要使用 LOCALE_NOUSEROVERRIDE ，因為它會停用使用者喜好設定。

值	意義
TIME_NOMINUTESORSECONDS	請勿使用分鐘或秒。
TIME_NOSECONDS	請勿使用秒數。
TIME_NOTIMEMARKER	請勿使用時間標記。
TIME_FORCE24HOURFORMAT	一律使用 24 小時的時間格式。

[in, optional] lpTime

SYSTEMTIME結構的指標，其中包含要格式化的時間資訊。如果函式是使用目前的本機系統時間，應用程式可以將此參數設定為 Null 。

[in, optional] lpFormat

用來格式化時間字串之格式圖片的指標。如果應用程式將此參數設定為 Null，則函式會根據指定地區設定的時間格式來格式化字串。如果應用程式未將參數設定為 Null，則函式只會針對格式圖片字串中未指定的資訊使用地區設定，例如地區設定特定的時間標記。如需格式圖片字串的詳細資訊，請參閱一節。

[out, optional] lpTimeStr

這個函式擷取格式化時間字串的緩衝區指標。

[in] cchTime

大小，以字元為單位，表示 lpTimeStr所指示的時間字串緩衝區。或者，應用程式可以將此參數設定為 0。在此情況下，函式會傳回時間字串緩衝區所需的大小，而且不會使用 lpTimeStr 參數。

傳回值

傳回 lpTimeStr所指示之緩衝區中擷取的字元數。如果 cchTime 參數設定為 0，則函式會傳回保留格式化時間字串所需的緩衝區大小，包括終止的 Null 字元。

如果函式未成功，此函式會傳回 0。若要取得延伸的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 Null不正確。
ERROR_INVALID_FLAGS。為旗標提供的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。
ERROR_OUTOFMEMORY。沒有足夠的儲存體可完成這項作業。

備註

如果時間標記存在且未設定TIME_NOTIMEMARKER旗標，則函式會根據指定的地區設定識別碼當地語系化時間標記。時間標記的範例包括英文 (美國) 的「AM」和「PM」。

lpTime所指示結構中的時間值必須有效。函式會檢查每個時間值，以判斷其是否位於適當的值範圍內。如果任何時間值超出正確的範圍，則函式會失敗，並將最後一個錯誤設定為ERROR_INVALID_PARAMETER。

函式會忽略 SYSTEMTIME 結構的日期成員。這些包括： wYear、 wMonth、 wDayOfWeek和 wDay。

如果指定TIME_NOMINUTESORSECONDS或TIME_NOSECONDS，則函式會在分鐘和/或秒成員之後移除分隔符號。

如果指定了TIME_NOTIMEMARKER，函式會移除時間標記前面和之後的分隔符號。

如果指定TIME_FORCE24HOURFORMAT，則函式會顯示任何現有的時間標記，除非同時設定TIME_NOTIMEMARKER旗標。

函式不包含毫秒做為格式化時間字串的一部分。

函式不會傳回不正確的格式字串錯誤，但只會形成最佳的可能時間字串。如果傳入超過兩小時、分鐘、秒或時間標記格式圖片，則函式預設為兩個。例如，有效的唯一時間標記圖片是「t」和「tt」。如果傳入「ttt」，函式會假設「tt」。

若要取得時間格式而不執行任何實際格式設定，應用程式應該使用 GetLocaleInfoEx 函式，並指定 LOCALE_STIMEFORMAT。

應用程式可以使用下列元素來建構格式圖片字串。如果使用空格分隔格式字串中的專案，這些空格會出現在輸出字串中的相同位置。字母必須以大寫或小寫表示，例如「ss」，而不是「SS」。以單引號括住的格式字串中的字元會出現在相同的位置，且輸出字串中未變更。

Picture	意義
h	沒有前置零的小時數，則為單一位數時數;12 小時制
hh	單一位數時數為前置零的小時數;12 小時制
H	沒有前置零的小時數，則為單一位數時數;24 小時制
HH	單一位數時數為前置零的小時數;24 小時制
m	單一位數分鐘沒有前置零的分鐘數
mm	單一位數分鐘數為前置零的分鐘數
s	在單一位數秒內沒有前置零的秒數
ss	具有前置零的秒數，以單一位數秒為單位
t	一個字元時間標記字串，例如 A 或 P
tt	多重字元時間標記字串，例如 AM 或 PM

例如，若要取得時間字串

"11:29:40 PM"

應用程式應該使用圖片字串

"hh':'mm':'ss tt"

此函式可以從自訂地區設定擷取資料。資料不保證從電腦到電腦或在應用程式執行之間相同。如果您的應用程式必須保存或傳輸資料，請參閱使用持續性地區設定資料。

從Windows 8開始：如果您的 app 從Windows.Globalization命名空間將語言標記傳遞至此函式，則必須先呼叫ResolveLocaleName來轉換標記。

從Windows 8開始：GetTimeFormatEx會在 Datetimeapi.h 中宣告。在Windows 8之前，它會在 Winnls.h 中宣告。

規格需求


最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平臺	Windows
標頭	datetimeapi.h
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

GetTimeFormatEx 函式 (datetimeapi.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

意見反應

其他資源