GetDateFormatW 函式 (datetimeapi.h)

發行項
08/23/2023

將日期格式化為地區設定識別碼所指定地區設定的日期字串。函式會格式化指定的日期或本機系統日期。

注意基於互通性考慮，應用程式應該偏好 GetDateFormatEx 函式為 GetDateFormat ，因為 Microsoft 正移轉至使用地區設定名稱，而不是新地區設定的地區設定識別碼。任何只會在 Windows Vista 上執行且更新版本的應用程式都應該使用 GetDateFormatEx。

語法

int GetDateFormatW(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate
);

參數

[in] Locale

指定地區設定的地區設定，此函式會設定日期字串的格式。您可以使用 MAKELCID 宏來建立地區設定識別碼，或使用下列其中一個預先定義的值。

[in] dwFlags

指定日期格式選項的旗標。如需詳細定義，請參閱GetDateFormatEx的dwFlags參數。

[in, optional] lpDate

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

[in, optional] lpFormat

用來形成日期的格式圖片字串指標。格式圖片字串的可能值定義在 Day、Month、Year 和 Era Format Pictures中。

函式只會針對格式圖片字串中未指定的資訊使用指定的地區設定，例如地區設定的日期和月份名稱。應用程式可以將此參數設定為 Null ，根據指定地區設定的日期格式來格式化字串。

[out, optional] lpDateStr

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

[in] cchDate

lpDateStr緩衝區的大小，以字元為單位。應用程式可以將此參數設定為 0，以傳回保存格式化日期字串所需的緩衝區大小。在此情況下，不會使用 lpDateStr 所指示的緩衝區。

傳回值

如果成功，則會傳回寫入 lpDateStr 緩衝區的字元數。如果 cchDate 參數設定為 0，則函式會傳回保存格式化日期字串所需的字元數，包括終止的 Null 字元。

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

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 Null不正確。
ERROR_INVALID_FLAGS。為旗標提供的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。

備註

注意此 API 即將更新，以支援 2019 年 5 月日紀元變更。如果您的應用程式支援日曆，您應該驗證它是否能夠正確處理新紀元。如需詳細資訊，請參閱準備您的應用程式以進行日文紀元變更。

請參閱 GetDateFormatEx的。

當此函式的 ANSI 版本搭配僅限 Unicode 的地區設定識別碼使用時，函式可能會成功，因為作業系統使用系統字碼頁。不過，系統字碼頁中未定義的字元會出現在字串中，以問號 (「？) 。

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

注意

datetimeapi.h 標頭會將 GetDateFormat 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	datetimeapi.h
程式庫	Kernel32.lib
DLL	Kernel32.dll