# FormatTime

将 YYYYMMDDHH24MISS 时间戳转换为指定的日期/时间格式.

    String := FormatTime(YYYYMMDDHH24MISS, Format)

## 参数

YYYYMMDD...

  类型: 字符串

  留空此参数以使用当前本地日期和时间. 否则, 请指定 YYYYMMDDHH24MISS 格式时间戳的全部或前面的部分.

Format

  类型: 字符串

  如果省略, 则它默认为时间后跟着长日期, 并且会对它们根据当前用户区域设置进行格式化. 例如: 4:55 PM Saturday, November 27, 2004

  否则, 请指定一个或多个下面的日期-时间格式以及在它们之间的任何原义空格和标点(逗号不需要转义; 它们可以正常使用). 在下面的例子中, 请注意 M 必须为大写: M/d/yyyy h:mm tt

## 返回值

类型: 字符串

该函数返回指定时间戳的转换版本.

如果 YYYYMMDDHH24MISS 包含无效的日期和/或时间部分 -- 例如非闰年的 2 月 29 日 -- 那么日期和/或时间将从返回值中省略. 虽然只支持 1601 年到 9999 年之间的年份, 但只要时间部分有效, 仍然可以为更早的年份生成格式化的时间.

如果 Format 包含超过 2000 个字符, 则返回一个空字符串.

## 日期格式(区分大小写)

Format | 描述
--- | ---
d | 不含前导零的天数(1 – 31)
dd | 含前导零的天数(01 – 31)
ddd | 在当前的用户语言里星期几的简称(例如, 周一)
dddd | 在当前的用户语言里星期几的全称(例如, 星期一)
M | 不含前导零的月份(1 – 12)
MM | 含前导零的月份(01 – 12)
MMM | 在当前的用户语言里月份的简称(例如, 一月)
MMMM | 在当前的用户语言里月份的全称(例如, 一月)
y | 不含世纪的年份, 不含前导零(0 – 99)
yy | 不含世纪的年份, 含前导零(00 – 99)
yyyy | 含世纪的年份. 例如: 2005
gg | 当前用户区域设置的时代/纪元字符串(如果没有则为空)

## 时间格式(区分大小写)

Format | 描述
--- | ---
h | 不含前导零的小时数; 十二小时制格式(1 – 12)
hh | 含前导零的小时数; 十二小时制格式(01 – 12)
H | 不含前导零的小时数; 二十四小时制格式(0 – 23)
HH | 含前导零的小时数; 二十四小时制格式(00 – 23)
m | 不含前导零的分钟数(0 – 59)
mm | 含前导零的分钟数(00 – 59)
s | 不含前导零的秒数(0 – 59)
ss | 含前导零的秒数(00 – 59)
t | 单字符时间标记, 例如 A 或 P(取决于区域设置)
tt | 多字符时间标记, 例如 AM 或 PM(取决于区域设置)

## 独立格式

下面的格式必须 单独 使用; 即在 Format 参数中不能含有其他格式或文本. 这些格式不区分大小写.

Format | 描述
--- | ---
(空) | 留空 Format 来生成时间后跟着长日期. 例如, 在某些区域设置中它可能看起来像这样 4:55 PM Saturday, November 27, 2004(译者注: 显示的内容与顺序与系统设置有关, 中文: 下午 4:55 星期六,2004年11月27日)
Time | 当前用户区域设置的时间表示, 例如 5:26 PM(译者注: 显示的内容与顺序与系统设置有关, 中文: 下午 5:26)
ShortDate | 当前用户区域设置的短日期表示, 例如 02/29/04(译者注: 显示的内容与顺序与系统设置有关, 中文: 2004/2/29 )
LongDate | 当前用户区域设置的长日期表示, 例如 Friday, April 23, 2004(译者注: 显示的内容与顺序与系统设置有关, 中文: 星期五,2004年4月23日)
YearMonth | 当前用户区域设置的年份和月份格式, 例如 February, 2004(译者注: 显示的内容与顺序与系统设置有关, 中文: 2004年2月)
YDay | 不含前导零的年份的天数(1 – 366)
YDay0 | 含前导零的年份的天数(001 – 366)
WDay | 星期的天数(1 – 7). 星期天为 1.
YWeek | ISO 8601 中规定的完全年份和周数. 例如: 200453. 如果含有 1 月 1 日的星期有四天以上在新年里, 则它被认为是新年的第一星期. 否则, 它为前一年的最后一个星期, 而下一星期为新年的第一星期. 因此, 1 月 4 日和首个星期四总是在第一周.

## 附加选项

下列选项可以紧跟在 YYYYMMDDHH24MISS 时间戳后(如果没有时间戳, 它们也可以单独使用). 在下面的例子中, 请注意最后的四项间没有逗号:

    OutputVar := FormatTime("20040228 LSys D1 D4")

R: 反转. 让日期在时间之前(仅当 Format 为空时才有意义).

Ln: 如果此选项 不 存在, 则使用当前用户区域设置来格式化字符串. 要使用系统的区域设置, 请指定 LSys. 要使用特殊的区域设置, 请指定字母 L 后面跟着十六进制或十进制的区域设置标识符(LCID). 关于如何构建 LCID 的信息, 请在 www.microsoft.com 上搜索下列短语: Locale Identifiers

Dn: 日期选项. 请指定 n 为下列数字的其中一个:

- 0 = 强制使用默认选项. 这也会让短日期生效.
- 1 = 使用短日期(仅当 Format 为空时才有意义; 与 2 和 8 不兼容).
- 2 = 使用长日期(仅当 Format 为空时才有意义; 与 1 和 8 不兼容).
- 4 = 使用备用日历(如果有).
- 8 = 使用年份-月份格式(仅当 Format 为空时才有意义; 与 1 和 2 不兼容).
- 0x10 = 为从左到右的阅读顺序布局添加标记.
- 0x20 = 为从右到左的阅读顺序布局添加标记.
- 0x80000000 = 不遵循任何用户对系统默认日期格式的覆盖.
- 0x40000000 = 使用系统 ANSI 代码页而不是区域设置代码页进行字符串转换.

Tn: 时间选项. 请指定 n 为下列数字的其中一个:

- 0 = 强制使用默认选项. 这也使得会显示分钟数和秒数.
- 1 = 省略分钟数和秒数.
- 2 = 省略秒数.
- 4 = 省略时间标记(例如 AM/PM).
- 8 = 始终使用二十四小时制而不是十二小时制.
- 12 = 上面两个参数的组合.
- 0x80000000 = 不遵循任何用户对系统默认日期格式的覆盖.
- 0x40000000 = 使用系统 ANSI 代码页而不是区域设置代码页进行字符串转换.

注意: Dn 和 Tn 可以使用多次以使多个选项生效, 例如: `FormatTime("20040228 D2 D4 T1 T8")`

## 备注

您希望从 Format原义转换到最终字符串中的字母和数字应该用单引号括起来, 如此例所示: `"'Date:' MM/dd/yy 'Time:' hh:mm:ss tt"`.

相反, 非字母数字字符(例如空格, tab, 换行符(`n), 斜杠, 冒号, 逗号和其他标点) 不需要包围在单引号中. 例外情况是单引号字符本身: 要产生原义的单引号, 请使用四个连续的单引号(''''), 不过如果它们已经包含在一对外部引号中则仅使用连续的两个就行了.

如果 Format 同时包含日期和时间元素, 则它们不能混用. 换句话说, 这个字符串应该分成两半: 一半时间, 一半日期. 例如, 包含 "hh yyyy mm" 的格式字符串不会产生期望的结果, 因为它在两个时间元素间包含日期元素.

当 Format 包含数值的天数(d 或 dd) 后跟着月份的全称(MMMM), 则使用月份名称的所有格形式(如果当前语言有所有格形式).

相关提示, 可以使用 DateAdd 和 DateDiff 对日期和时间进行加减和比较.

## 相关

要进行反向的转换 -- 即, 从 格式化的日期/时间 转换到 YYYYMMDDHH24MISS 格式 -- 请参阅 www.autohotkey.com/forum/topic20405.html

另请参阅: Gui DateTime 控件, Format, 内置的日期和时间变量, FileGetTime

## 示例

演示不同的用法.

    TimeString := FormatTime()
    MsgBox "The current time and date (time first) is " TimeString

    TimeString := FormatTime("R")
    MsgBox "The current time and date (date first) is " TimeString

    TimeString := FormatTime(, "Time")
    MsgBox "The current time is " TimeString

    TimeString := FormatTime("T12", "Time")
    MsgBox "The current 24-hour time is " TimeString

    TimeString := FormatTime(, "LongDate")
    MsgBox "The current date (long format) is " TimeString

    TimeString := FormatTime(20050423220133, "dddd MMMM d, yyyy hh:mm:ss tt")
    MsgBox "The specified date and time, when formatted, is " TimeString

    MsgBox FormatTime(200504, "'Month Name': MMMM`n'Day Name': dddd")

    YearWeek := FormatTime(20050101, "YWeek")
    MsgBox "January 1st of 2005 is in the following ISO year and week number: " YearWeek

改变文件的日期-时间戳.

    FileName := FileSelect(3,, "Pick a file")
    if FileName = "" ; 用户没有选取文件.
        return
    FileTime := FileGetTime(FileName)
    FileTime := FormatTime(FileTime)   ; 由于省略了最后一个参数, 所以获取长日期和时间.
    MsgBox "The selected file was last modified at " FileTime

把指定的秒数转换成相应的小时数, 分钟数和秒数(hh:mm:ss 格式).

    MsgBox FormatSeconds(7384)  ; 7384 = 2 小时 + 3 分钟 + 4 秒. 它的结果: 2:03:04

    FormatSeconds(NumberOfSeconds)  ; 把指定的秒数转换成 hh:mm:ss 格式.
    {
        time := 19990101  ; 任意日期的 *午夜*.
        time := DateAdd(time, NumberOfSeconds, "Seconds")
        return NumberOfSeconds//3600 ":" FormatTime(time, "mm:ss")
        /*
        ; 和上面方法不同的是, 这里不支持超过 24 小时的秒数:
        return FormatTime(time, "h:mm:ss")
        */
    }

dftg