共用方式為


GetDateFormatEx 函式 (datetimeapi.h)

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

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

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

語法

int GetDateFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate,
  [in, optional]  LPCWSTR          lpCalendar
);

參數

[in, optional] lpLocaleName

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

[in] dwFlags

指定當 lpFormat 設定為 NULL 時可設定的各種函式選項的旗標。 應用程式可以指定下列值和 LOCALE_USE_CP_ACPLOCALE_NOUSEROVERRIDE的組合。

謹慎 強烈建議不要使用 LOCALE_NOUSEROVERRIDE ,因為它會停用使用者喜好設定。
 
意義
DATE_AUTOLAYOUT
Windows 7 和更新版本: 使用地區設定和行事曆資訊來偵測從右至左和從左至右閱讀版面配置的需求,並據以新增標記。 這個值不能與DATE_LTRREADING或DATE_RTLREADING搭配使用。 DATE_AUTOLAYOUT優先於DATE_LTRREADING和DATE_RTLREADING,因為它會使用地區設定和行事歷來判斷正確新增標記。
DATE_LONGDATE
使用長日期格式。 這個值不能與DATE_MONTHDAY、DATE_SHORTDATE或DATE_YEARMONTH搭配使用。
DATE_LTRREADING
新增由左至右閱讀版面配置的標記。 這個值不能與DATE_RTLREADING搭配使用。
DATE_RTLREADING
為從右至左閱讀版面配置新增標記。 這個值不能與DATE_LTRREADING搭配使用
DATE_SHORTDATE
使用簡短日期格式。 此為預設值。 這個值不能與DATE_MONTHDAY、DATE_LONGDATE或DATE_YEARMONTH搭配使用。
DATE_USE_ALT_CALENDAR
如果有替代行事曆,請使用替代行事歷來格式化日期字串。 如果設定此旗標,函式會使用該替代行事曆的預設格式,而不是使用任何使用者覆寫。 使用者覆寫只會在指定的替代行事歷沒有預設格式的事件中使用。
DATE_YEARMONTH
Windows Vista: 使用年/月格式。 這個值不能與DATE_MONTHDAY、DATE_SHORTDATE或DATE_LONGDATE搭配使用。
DATE_MONTHDAY
Windows 10:使用適用於指定地區設定的月份和日期格式組合。 這個值不能與DATE_YEARMONTH、DATE_SHORTDATE或DATE_LONGDATE搭配使用。
 

如果應用程式未指定DATE_YEARMONTH、DATE_MONTHDAY、DATE_SHORTDATE或DATE_LONGDATE,且 lpFormat 設定為 NULL,則DATE_SHORTDATE為預設值。

[in, optional] lpDate

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

[in, optional] lpFormat

用來形成日期之格式圖片字串的指標。 格式圖片字串的可能值定義於 日、月、年和紀元格式圖片中。

例如,若要取得日期字串 “Wed, Oct 31 94”,應用程式會使用圖片字串 “ddd',' MMM dd yy”。

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

[out, optional] lpDateStr

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

[in] cchDate

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

[in, optional] lpCalendar

保留;必須設定為 NULL

傳回值

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

如果函式不成功,此函式會傳回 0。 若要取得擴充的錯誤資訊,應用程式可以呼叫 GetLastError,這可以傳回下列其中一個錯誤碼:

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

備註

注意 此 API 正在更新,以支援 2019 年 5 月日本紀元變更。 如果您的應用程式支援日曆,您應該驗證它是否正確地處理新紀元。 如需詳細資訊 ,請參閱為日文紀元變更準備您的應用程式
 
此函式支援的最早日期是 1601 年 1 月 1 日。

日期名稱、縮寫日期名稱、月份名稱和縮寫月份名稱都會根據地區設定標識符進行當地語系化。

lpDate 所指示之結構的日期值必須有效。 函式會檢查每個日期值:年、月、日和周中的日。 如果星期數不正確,函式會使用正確的值,而且不會傳回錯誤。 如果任何其他日期值超出正確的範圍,函式會失敗,並將最後一個錯誤設定為ERROR_INVALID_PARAMETER。

函式會忽略 lpDate 所指示之 SYSTEMTIME 結構的時間成員。 其中包括 wHourwMinutewSecondwMilliseconds

如果 lpFormat 參數包含不正確的格式字串,則函式不會傳回任何錯誤,但只會形成最佳的可能日期字串。 例如,有效的唯一年份圖片是 L“yyyy” 和 L“yy”,其中 “L” 表示 Unicode (16 位字元) 字串。 如果傳入 L“y” ,函式會假設 L“yy”。 如果傳入 L“yyy”,函式會假設 L“yyyy”。 如果傳入四個以上的日期 (L“dddd”) 或四個月 (L“MMMM”) 圖片,則函式預設為 L“dddd” 或 L“MMMM”。

應用程式應該以日期格式圖片中的單引弧括住任何文字,該文字應該以其確切格式括住日期字串。 單引號也可以用來做為逸出字元,以允許在日期字串中顯示單引號本身。 不過,逸出序列必須括在兩個單引號內。 例如,若要將日期顯示為 “May '93”,格式字元串為:L“MMMM ''''yy”。 第一個和最後一個單引號是括住的引號。 第二個和第三個單引號是逸出序列,允許在百年之前顯示單引號。

當日期圖片同時包含日期格式 (d 或 dd) ,以及 MMMM) 的完整月份 (名稱,則會在日期字串串中擷取月份名稱的世代形式。

若要取得預設的簡短和完整日期格式,而不執行任何實際格式設定,應用程式應該使用 GetLocaleInfoEx 搭配 LOCALE_SSHORTDATELOCALE_SLONGDATE 常數。 若要取得替代行事曆的日期格式,應用程式會使用 GetLocaleInfoEx 搭配 LOCALE_IOPTIONALCALENDAR 常數。 若要取得特定行事曆的日期格式,應用程式會使用 GetCalendarInfoEx,傳遞適當的 行事曆標識符。 它可以呼叫 EnumCalendarInfoExEnumDateFormatsEx 來擷取特定行事曆的日期格式。

此函式可以從 自定義地區設定擷取數據。 數據不保證從計算機到計算機或在應用程式執行之間相同。 如果您的應用程式必須保存或傳輸數據,請參閱 使用持續性地區設定數據

DATE_LONGDATE格式包含兩種日期模式:包含星期數的模式,以及不包含星期數的模式。 例如,「星期二,2016 年 10 月 18 日」或「2016 年 10 月 18 日」。 如果您的應用程式需要確保日期使用下列其中一種模式,而不是其他類型的模式,您的應用程式應該執行下列動作:

  1. 呼叫 EnumDateFormatsExEx 函 式,以取得DATE_LONGDATE格式的所有日期格式。
  2. 尋找傳遞至您為 EnumDateFormatsExEx 所指定之回呼函式的第一個日期格式,其符合您要求的行事曆標識符,並具有符合您應用程式需求的日期格式字符串。 例如,如果您的應用程式要求日期包含星期數的完整名稱,則尋找包含 「dddd」 的第一個日期格式,或尋找不包含 「d」 或 「dd」 的第一個日期格式,如果您的應用程式要求日期包含縮寫名稱或周日的完整名稱。
  3. 呼叫 GetDateFormatEx 函式,並將 lpFormat 參數設定為回呼函式中識別為適當格式的日期格式字串。

如果長時間日期格式的星期數是否存在與應用程式無關,您的應用程式可以直接呼叫 GetDateFormatEx ,而不需要先呼叫 EnumDateFormatsEx 來列舉所有長日期格式。

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

從 Windows 8 開始:GetDateFormatEx 會在 Datetimeapi.h 中宣告。 在 Windows 8 之前,它會在 Winnls.h 中宣告。

規格需求

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

另請參閱

日、月、年和紀元格式圖片

EnumDateFormatsExEx

GetCalendarInfoEx

GetDateFormat

NLS:名稱型 API 範例

國家語言支援

國家語言支援函式