getDateFormatEx 函数 (datetimeapi.h)

项目
02/26/2024

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

注意如果设计为仅在 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_ACP 或 LOCALE_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， Aug 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 指示的结构中的日期值必须有效。函数检查每个日期值：year、month、day 和 day of week。如果星期中的某一天不正确，则函数使用正确的值，并且不返回错误。如果任何其他日期值超出正确的范围，该函数将失败，并将最后一个错误设置为ERROR_INVALID_PARAMETER。

函数忽略 lpDate 指示的 SYSTEMTIME 结构的时间成员。其中包括 wHour、 wMinute、 wSecond 和 wMilliseconds。

如果 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_SSHORTDATE 或 LOCALE_SLONGDATE 常量一起使用。为了获取备用日历的日期格式，应用程序使用具有LOCALE_IOPTIONALCALENDAR常量的 GetLocaleInfoEx。为了获取特定日历的日期格式，应用程序使用 GetCalendarInfoEx 传递相应的日历标识符。它可以调用 EnumCalendarInfoEx 或 EnumDateFormatsEx 来检索特定日历的日期格式。

此函数可以从自定义区域设置检索数据。不保证数据在计算机之间或应用程序运行之间的数据相同。如果应用程序必须保留或传输数据，请参阅使用永久性区域设置数据。

DATE_LONGDATE格式包括两种类型的日期模式：包含星期数的模式和不包括星期中的某一天的模式。例如，“星期二，2016 年 10 月 18 日”或“2016 年 10 月 18 日”。如果应用程序需要确保日期使用其中一种模式，而不是使用其他类型的模式，则应用程序应执行以下操作：

调用 EnumDateFormatsExExEx 函数以获取DATE_LONGDATE格式的所有日期格式。
查找传递到为 EnumDateFormatsExEx 指定的回调函数的第一个日期格式格式，该格式与请求的日历标识符匹配，并且具有与应用程序要求匹配的日期格式字符串。例如，如果应用程序要求日期包含星期数的全名，请查找包含“dddd”的第一个日期格式;如果应用程序要求日期包含缩写名称或星期日期的全名，则查找不包含“ddd”和“ddd”的第一个日期格式。
调用 GetDateFormatEx 函数，并将 lpFormat 参数设置为在回调函数中标识为相应格式的日期格式字符串。

如果一周中某一天是否存在长日期格式对应用程序并不重要，则应用程序可以直接调用 GetDateFormatEx ，而无需通过调用 EnumDateFormatsExEx 首先枚举所有长日期格式。

从Windows 8开始：如果你的应用将语言标记从 Windows.Globalization 命名空间传递到此函数，它必须首先通过调用 ResolveLocaleName 来转换标记。

从 Windows 8 开始：GetDateFormatEx 在 Datetimeapi.h 中声明。在Windows 8之前，它在 Winnls.h 中声明。

要求

要求	值
最低受支持的客户端	Windows Vista [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	datetimeapi.h
Library	Kernel32.lib
DLL	Kernel32.dll