GetDateFormatW 函数（datetimeapi.h）

项目
11/20/2024

将日期的格式设置为区域设置标识符指定的区域设置的日期字符串。该函数设置指定日期或本地系统日期的格式。

注意出于互操作性原因，应用程序应首选 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

指向用于构成日期的格式图片字符串的指针。格式图片字符串的可能值在日、月、年和纪元格式图片中定义。

该函数仅对格式图片字符串中未指定的信息使用指定的区域设置，例如区域设置的日和月名称。应用程序可以将此参数设置为 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 Professional [仅限桌面应用]
支持的最低服务器	Windows 2000 Server [仅限桌面应用]
目标平台	窗户
标头	datetimeapi.h
库	Kernel32.lib
DLL	Kernel32.dll