getTimeFormatEx 函数 (datetimeapi.h)

项目
04/06/2023

将时间格式化为由名称指定的区域设置的时间字符串。函数设置指定时间或本地系统时间的格式。

注意如果设计为仅在 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
);

parameters

[in, optional] lpLocaleName

指向区域设置名称或以下预定义值之一的指针。

[in] dwFlags

指定时间格式选项的标志。应用程序可以指定以下值和 LOCALE_USE_CP_ACP 或 LOCALE_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 结构的日期成员。其中包括： wYear、 wMonth、 wDayOfWeek 和 wDay。

如果指定TIME_NOMINUTESORSECONDS或TIME_NOSECONDS，函数将删除分钟和/或秒成员后面的分隔符。

如果指定了TIME_NOTIMEMARKER，函数将删除时间标记前面和后面的分隔符。

如果指定了TIME_FORCE24HOURFORMAT，该函数将显示任何现有的时间标记，除非还设置了TIME_NOTIMEMARKER标志。

该函数不包括毫秒作为格式化时间字符串的一部分。

该函数不返回错误格式字符串的错误，但只是构成可能的最佳时间字符串。如果传入的图片超过两小时、分钟、秒或时间标记格式，则函数默认为 2。例如，唯一有效的时间标记图片是“t”和“tt”。如果传入“ttt”，则函数假定“tt”。

若要在不执行任何实际格式的情况下获取时间格式，应用程序应使用 GetLocaleInfoEx 函数，指定 LOCALE_STIMEFORMAT。

应用程序可以使用以下元素来构造格式图片字符串。如果使用空格分隔格式字符串中的元素，则这些空格将显示在输出字符串中的同一位置。字母必须采用大写或小写，如所示，例如“ss”，而不是“SS”。格式字符串中用单引号括起来的字符出现在同一位置，在输出字符串中保持不变。

图片	含义
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开始：如果你的应用将语言标记从 Windows.Globalization 命名空间传递到此函数，它必须首先通过调用 ResolveLocaleName 来转换标记。

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

要求


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

另请参阅

getTimeFormatEx 函数 (datetimeapi.h)

语法

parameters

返回值

注解

要求

另请参阅

反馈

反馈

其他资源