共用方式為


GetTimeFormatEx 函式 (datetimeapi.h)

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

注意 如果設計為只在 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_ACPLOCALE_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 結構的日期成員。 這些包括: wYearwMonthwDayOfWeekwDay

如果指定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

另請參閱

GetDateFormatEx

GetLocaleInfoEx

GetTimeFormat

國家語言支援

國家語言支援函式