Module java.base

软件包 java.time.format

Class DateTimeFormatter

java.lang.Object

java.time.format.DateTimeFormatter

public final class DateTimeFormatter
extends Object

格式化器用于打印和解析日期时间对象。

该类提供打印和解析的主要应用程序入口点，并提供DateTimeFormatter常见实现：

• 使用预定义的常量，如ISO_LOCAL_DATE
• 使用图案字母，如uuuu-MMM-dd
• 使用本地化样式，如long或medium

更复杂的格式化程序由DateTimeFormatterBuilder提供。

主要的日期时间类提供两种方法 - 一种用于格式化， format(DateTimeFormatter formatter) ，另一种用于解析， parse(CharSequence text, DateTimeFormatter formatter) 。

例如：

  LocalDate date = LocalDate.now();
  String text = date.format(formatter);
  LocalDate parsedDate = LocalDate.parse(text, formatter);
 

除格式之外，可以使用所需的区域设置，年表，ZoneId和DecimalStyle创建格式化程序。

withLocale方法返回一个覆盖区域设置的新格式化程序。 区域设置影响格式化和解析的一些方面。 例如， ofLocalizedDate提供了一个使用特定于语言环境的日期格式的格式化程序。

withChronology方法返回一个覆盖年表的新格式化程序。 如果被覆盖，则在格式化之前将日期时间值转换为年表。 在解析期间，返回日期时间值之前将其转换为年表。

withZone方法返回一个覆盖该区域的新格式化程序。 如果被覆盖，日期时间值将在格式化之前转换为带有请求的ZoneId的ZonedDateTime。 在解析期间，在返回值之前应用ZoneId。

withDecimalStyle方法返回一个新的格式化程序，覆盖DecimalStyle 。 DecimalStyle符号用于格式化和解析。

某些应用程序可能需要使用较旧的java.text.Format类进行格式化。 toFormat()方法返回一个java.text.Format的实现。

预定格式化器

Predefined Formatters Formatter Description Example ofLocalizedDate(dateStyle) Formatter with date style from the locale '2011-12-03' ofLocalizedTime(timeStyle) Formatter with time style from the locale '10:15:30' ofLocalizedDateTime(dateTimeStyle) Formatter with a style for date and time from the locale '3 Jun 2008 11:05:30' ofLocalizedDateTime(dateStyle,timeStyle) Formatter with date and time styles from the locale '3 Jun 2008 11:05' BASIC_ISO_DATE Basic ISO date '20111203' ISO_LOCAL_DATE ISO Local Date '2011-12-03' ISO_OFFSET_DATE ISO Date with offset '2011-12-03+01:00' ISO_DATE ISO Date with or without offset '2011-12-03+01:00'; '2011-12-03' ISO_LOCAL_TIME Time without offset '10:15:30' ISO_OFFSET_TIME Time with offset '10:15:30+01:00' ISO_TIME Time with or without offset '10:15:30+01:00'; '10:15:30' ISO_LOCAL_DATE_TIME ISO Local Date and Time '2011-12-03T10:15:30' ISO_OFFSET_DATE_TIME Date Time with Offset 2011-12-03T10:15:30+01:00' ISO_ZONED_DATE_TIME Zoned Date Time '2011-12-03T10:15:30+01:00[Europe/Paris]' ISO_DATE_TIME Date and time with ZoneId '2011-12-03T10:15:30+01:00[Europe/Paris]' ISO_ORDINAL_DATE Year and day of year '2012-337' ISO_WEEK_DATE Year and Week 2012-W48-6' ISO_INSTANT Date and Time of an Instant '2011-12-03T10:15:30Z' RFC_1123_DATE_TIME RFC 1123 / RFC 822 'Tue, 3 Jun 2008 11:05:30 GMT'

格式和解析模式

模式基于简单的字母和符号序列。 使用模式使用ofPattern(String)和ofPattern(String, Locale)方法创建格式化程序 。 例如， "d MMM uuuu"将格式为2011-12-03，为“2011年12月3日”。 从模式创建的格式化程序可以根据需要多次使用，它是不可变的并且是线程安全的。

例如：

  LocalDate date = LocalDate.now();
  DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
  String text = date.format(formatter);
  LocalDate parsedDate = LocalDate.parse(text, formatter);
 

所有字母“A”至“Z”和“a”至“z”保留为图案字母。 定义了以下图案字母：

  Symbol  Meaning                     Presentation      Examples
  ------  -------                     ------------      -------
   G       era                         text              AD; Anno Domini; A
   u       year                        year              2004; 04
   y       year-of-era                 year              2004; 04
   D       day-of-year                 number            189
   M/L     month-of-year               number/text       7; 07; Jul; July; J
   d       day-of-month                number            10
   g       modified-julian-day         number            2451334

   Q/q     quarter-of-year             number/text       3; 03; Q3; 3rd quarter
   Y       week-based-year             year              1996; 96
   w       week-of-week-based-year     number            27
   W       week-of-month               number            4
   E       day-of-week                 text              Tue; Tuesday; T
   e/c     localized day-of-week       number/text       2; 02; Tue; Tuesday; T
   F       day-of-week-in-month        number            3

   a       am-pm-of-day                text              PM
   h       clock-hour-of-am-pm (1-12)  number            12
   K       hour-of-am-pm (0-11)        number            0
   k       clock-hour-of-day (1-24)    number            24

   H       hour-of-day (0-23)          number            0
   m       minute-of-hour              number            30
   s       second-of-minute            number            55
   S       fraction-of-second          fraction          978
   A       milli-of-day                number            1234
   n       nano-of-second              number            987654321
   N       nano-of-day                 number            1234000000

   V       time-zone ID                zone-id           America/Los_Angeles; Z; -08:30
   v       generic time-zone name      zone-name         Pacific Time; PT
   z       time-zone name              zone-name         Pacific Standard Time; PST
   O       localized zone-offset       offset-O          GMT+8; GMT+08:00; UTC-08:00
   X       zone-offset 'Z' for zero    offset-X          Z; -08; -0830; -08:30; -083015; -08:30:15
   x       zone-offset                 offset-x          +0000; -08; -0830; -08:30; -083015; -08:30:15
   Z       zone-offset                 offset-Z          +0000; -0800; -08:00

   p       pad next                    pad modifier      1

   '       escape for text             delimiter
   ''      single quote                literal           '
   [       optional section start
   ]       optional section end
   #       reserved for future use
   {       reserved for future use
   }       reserved for future use 

模式字母的数量决定了格式。

文本 ：文字样式是根据所使用的图案字母数确定的。 少于4个图案字母将使用short form 。 完全4个图案字母将使用full form 。 完全5个图案字母将使用narrow form 。 图案字母'L'，'c'和'q'指定文本样式的独立形式。

编号 ：如果字母数为1，则使用最小位数输出该值，而不填充。 否则，使用数字计数作为输出字段的宽度，根据需要使用零填充值。 以下模式字母对字母数的约束。 只能指定'c'和'F'的一个字母。 可以指定多达两个'd'，'H'，'h'，'K'，'k'，'m'和's'的字母。 最多可以指定三个字母'D'。

数字/文本 ：如果模式字母的数量为3或更大，请使用上述文本规则。 否则使用上面的数字规则。

分数 ：输出二分之一纳秒的场。 纳秒值有九位数，因此模式字母的计数从1到9.如果小于9，那么纳秒值将被截断，只有最高有效位被输出。

年份 ：字母数确定使用最小字段宽度低于哪个填充。 如果字母数为2，则使用两位数字的reduced 。 对于打印，这将输出最右边的两位数字。 对于解析，这将使用基数值2000解析，导致一年在2000到2099之间的范围内。 如果字母数小于四（但不是两个），则符号只能按照SignStyle.NORMAL输出为负数。 否则，如果超过了垫宽，则输出符号，如SignStyle.EXCEEDS_PAD所示 。

ZoneId ：输出时区ID，如“Europe / Paris”。 如果字母数为2，则输出时区ID。 任何其他字母数字抛出IllegalArgumentException 。

区域名称 ：输出时区ID的显示名称。 如果模式字母为“z”，则输出为夏令时感知区域名称。 如果没有足够的信息来确定是否适用DST，则将使用忽略夏令时的名称。 如果字母数为1，2或3，则输出短名称。 如果字母数为4，则输出全名。 五个或更多的字母抛出IllegalArgumentException 。

如果模式字母为“v”，输出将提供忽略夏令时的区域名称。 如果字母数为1，则输出短名称。 如果字母数为4，则输出全名。 二，三，五个以上的字母抛出IllegalArgumentException 。

偏移X和x ：这将根据模式字母的数量格式化偏移量。 一个字母只输出小时，例如“+01”，除非分钟不为零，在这种情况下也输出分钟，例如“+0130”。 两个字母输出小时和分钟，没有冒号，例如'+0130'。 三个字母输出小时和分钟，冒号如“+01：30”。 四个字母输出小时和分钟，可选第二个，没有冒号，例如'+013015'。 五个字母输出小时和分钟，可选第二个，冒号如“+01：30：15”。 六个或更多的字母抛出IllegalArgumentException 。 当要输出的偏移量为零时，模式字母“X”（大写）将输出“Z”，而模式字母“x”（小写）将输出“+00”，“+0000”或“+00 ：00' 。

偏移量O ：根据模式字母的数量格式化局部偏移量。 一个字母输出局部偏移量的short形式，它是局部偏移文本，例如'GMT'，小时没有前导零，可选的2位数分钟和秒（如果非零），冒号，例如'GMT + 8 ”。 四个字母输出full表单，它是本地化的偏移文本，例如'GMT，具有2位小时和分钟字段，可选的第二个字段（如果非零），冒号，例如'GMT + 08：00'。 任何其他字母数字抛出IllegalArgumentException 。

偏移Z ：根据模式字母的数量格式化偏移量。 一个，两个或三个字母输出小时和分钟，没有冒号，例如'+0130'。 当偏移为零时，输出将为“+0000”。 四个字母输出full形式的局部偏移量，相当于Offset-O的四个字母。 如果偏移为零，输出将为相应的局部偏移文本。 五个字母输出小时，分钟，可选第二个（如果非零），冒号。 如果偏移为零，则输出“Z”。 六个或更多的字母抛出IllegalArgumentException 。

可选部分 ：可选部分标记与调用DateTimeFormatterBuilder.optionalStart()和DateTimeFormatterBuilder.optionalEnd()完全一样。

垫修饰符 ：修改紧随其后的模式以填充空格。 垫宽度由图案字母的数量决定。 这与拨打DateTimeFormatterBuilder.padNext(int)相同。

例如，'ppH'输出在左边填充空格的宽度为2的小时。

任何无法识别的字母都是错误。 除'['，']'，'{'，'}'，'＃'和单引号之外的任何非字母字符都将直接输出。 尽管如此，建议对要直接输出的所有字符使用单引号，以确保将来的更改不会破坏您的应用程序。

解决

解析实现为两阶段操作。 首先，使用格式化程序定义的布局解析文本，产生一个Map的字段值，一个ZoneId和一个Chronology 。 第二，通过验证，组合和简化各种领域，使解析的数据得到解决 。

这个类提供了五种解析方法。 其中四个执行解析和解析阶段。 第五种方法， parseUnresolved(CharSequence, ParsePosition) ，只执行第一阶段，留下结果未解决。 因此，它本质上是一个低级别的操作。

解析阶段由这个类设置的两个参数控制。

ResolverStyle是一个枚举，提供三种不同的方法，严格，聪明和宽松。 智能选项是默认值。 可以使用withResolverStyle(ResolverStyle)设置。

withResolverFields(TemporalField...)参数允许在解析开始之前对要解析的字段进行过滤。 例如，如果格式化程序已经解析了一年，一个月，一个月的日子和一天，那么有两种方法可以解决一个日期：（年+月+月 - 日）和（年+天的年）。 解析器字段允许选择两种方法之一。 如果没有设置解析器字段，则两种方法都必须产生相同的日期。

解决单独的字段以形成完整的日期和时间是一个复杂的过程，其行为分布在多个类中。 它遵循这些步骤：

1. 年表是确定的。 结果的年表是被解析的年表，或者如果没有按时间顺序被解析，那么这个时间顺序是在这个类上设置的，或者如果是null，那么是IsoChronology 。
2. ChronoField日期字段已解决。 这是使用Chronology.resolveDate(Map, ResolverStyle)实现的。 有关现场解析的文档位于Chronology的实现中。
3. ChronoField时间字段已解决。 这在ChronoField记录，并且对于所有年表是相同的。
4. 任何不是ChronoField字段都被处理。 这是使用TemporalField.resolve(Map, TemporalAccessor, ResolverStyle)实现的。 关于现场解析的文件位于TemporalField的实施。
5. ChronoField日期和时间字段被重新解析。 这允许第四步中的字段产生ChronoField值，并将它们处理为日期和时间。
6. 如果至少有一小时可用，则形成A LocalTime 。 这涉及提供分秒，秒和秒的分数的默认值。
7. 任何剩余的未解决的字段与已解决的任何日期和/或时间进行交叉检查。 因此，较早的阶段将解决（年+月+月的日）到一个日期，这个阶段将检查星期几是有效的日期。
8. 如果excess number of days被解析，那么如果有可用的日期，则将其添加到日期。
9. 如果存在第二个字段，但LocalTime未被解析，那么解析器确保毫微秒和微秒的值可以满足ChronoField的合同。 如果丢失，这些将被设置为零。
10. 如果解析了日期和时间，并且存在偏移或区域，则创建字段ChronoField.INSTANT_SECONDS 。 如果偏移量被解析，则偏移量将与LocalDateTime组合以形成瞬间，任何区域被忽略。 如果ZoneId未经偏移，则区分析将与合并LocalDateTime ，形成利用规则瞬间ChronoLocalDateTime.atZone(ZoneId) 。

实现要求：

这个类是不可变的和线程安全的。

从以下版本开始：

1.8

Field Summary

Fields

Modifier and Type	Field	描述
static DateTimeFormatter	BASIC_ISO_DATE	格式化或解析没有偏移量的日期的ISO日期格式化程序，例如“20111203”。
static DateTimeFormatter	ISO_DATE	ISO日期格式化程序格式化或解析具有偏移量的日期（如可用），如“2011-12-03”或“2011-12-03 + 01：00”。
static DateTimeFormatter	ISO_DATE_TIME	类似ISO的日期格式化程序，用于格式化或解析具有偏移量和区域（如果有的话）的日期时间，如“2011-12-03T10：15：30”，“2011-12-03T10：15：30 + 01” ：00'或'2011-12-03T10：15：30 + 01：00 [欧洲/巴黎]'。
static DateTimeFormatter	ISO_INSTANT	ISO即时格式化程序，用于格式化或解析UTC中的即时消息，例如“2011-12-03T10：15：30Z”。
static DateTimeFormatter	ISO_LOCAL_DATE	ISO日期格式化程序格式化或解析没有偏移量的日期，如“2011-12-03”。
static DateTimeFormatter	ISO_LOCAL_DATE_TIME	ISO日期格式化程序格式化或解析没有偏移量的日期时间，例如“2011-12-03T10：15：30”。
static DateTimeFormatter	ISO_LOCAL_TIME	ISO时间格式化程序格式化或解析一个没有偏移量的时间，例如“10：15”或“10：15：30”。
static DateTimeFormatter	ISO_OFFSET_DATE	ISO日期格式化程序格式化或解析具有偏移量的日期，例如“2011-12-03 + 01：00”。
static DateTimeFormatter	ISO_OFFSET_DATE_TIME	ISO日期格式化程序格式化或解析具有偏移量的日期时间，例如“2011-12-03T10：15：30 + 01：00”。
static DateTimeFormatter	ISO_OFFSET_TIME	格式化或解析时间偏移的ISO时间格式化程序，例如“10：15 + 01：00”或“10：15：30 + 01：00”。
static DateTimeFormatter	ISO_ORDINAL_DATE	ISO日期格式化程序格式化或解析没有偏移量的序数日期，例如“2012-337”。
static DateTimeFormatter	ISO_TIME	格式化或解析时间的ISO时间格式化程序，如果可用的偏移量，如“10：15”，“10：15：30”或“10：15：30 + 01：00”。
static DateTimeFormatter	ISO_WEEK_DATE	ISO日期格式化程序，用于格式化或解析不带偏移量的基于周的日期，例如“2012-W48-6”。
static DateTimeFormatter	ISO_ZONED_DATE_TIME	类似ISO的日期格式化程序，用于格式化或解析具有偏移和区域的日期时间，例如“2011-12-03T10：15：30 + 01：00 [Europe / Paris]”。
static DateTimeFormatter	RFC_1123_DATE_TIME	RFC-1123日期格式化程序，如“星期二，2008年6月3日11:05:30 GMT”。

方法摘要

Modifier and Type	方法	描述
String	format(TemporalAccessor temporal)	使用此格式化程序格式化日期时间对象。
void	formatTo(TemporalAccessor temporal, Appendable appendable)	使用此格式化程序将日期时间对象格式化为 Appendable 。
Chronology	getChronology()	获得在格式化期间使用的压倒一记的年表。
DecimalStyle	getDecimalStyle()	获取在格式化期间使用的DecimalStyle。
Locale	getLocale()	获取格式化期间要使用的区域设置。
Set<TemporalField>	getResolverFields()	获取在解析期间使用的解析器字段。
ResolverStyle	getResolverStyle()	获取在解析过程中使用的解析器样式。
ZoneId	getZone()	获取在格式化期间使用的覆盖区域。
static DateTimeFormatter	ofLocalizedDate(FormatStyle dateStyle)	返回ISO年表的区域设置特定日期格式。
static DateTimeFormatter	ofLocalizedDateTime(FormatStyle dateTimeStyle)	返回ISO时代的区域设置特定的日期时间格式化程序。
static DateTimeFormatter	ofLocalizedDateTime(FormatStyle dateStyle, FormatStyle timeStyle)	返回ISO时代的特定日期和时间格式。
static DateTimeFormatter	ofLocalizedTime(FormatStyle timeStyle)	返回ISO时代的区域设置特定时间格式。
static DateTimeFormatter	ofPattern(String pattern)	使用指定的模式创建格式化程序。
static DateTimeFormatter	ofPattern(String pattern, Locale locale)	使用指定的模式和区域设置创建格式化程序。
TemporalAccessor	parse(CharSequence text)	完全解析产生时间对象的文本。
TemporalAccessor	parse(CharSequence text, ParsePosition position)	使用此格式化器解析文本，提供对文本位置的控制。
<T> T	parse(CharSequence text, TemporalQuery<T> query)	完全解析产生指定类型对象的文本。
TemporalAccessor	parseBest(CharSequence text, TemporalQuery<?>... queries)	完全解析产生指定类型之一的对象的文本。
static TemporalQuery<Period>	parsedExcessDays()	一个查询，可以访问已解析的多余天数。
static TemporalQuery<Boolean>	parsedLeapSecond()	提供访问是否解析了跨越秒的查询。
TemporalAccessor	parseUnresolved(CharSequence text, ParsePosition position)	使用此格式化程序解析文本，而无需解析结果，用于高级用例。
Format	toFormat()	将此格式化程序作为 java.text.Format实例返回。
Format	toFormat(TemporalQuery<?> parseQuery)	将此格式化器返回为 java.text.Format实例，将使用指定的查询进行解析。
String	toString()	返回底层格式化程序的描述。
DateTimeFormatter	withChronology(Chronology chrono)	使用新的覆盖年表返回此格式化程序的副本。
DateTimeFormatter	withDecimalStyle(DecimalStyle decimalStyle)	使用新的DecimalStyle返回此格式化程序的副本。
DateTimeFormatter	withLocale(Locale locale)	使用新的语言环境返回此格式化程序的副本。
DateTimeFormatter	withResolverFields(TemporalField... resolverFields)	使用一组新的解析器字段返回此格式化程序的副本。
DateTimeFormatter	withResolverFields(Set<TemporalField> resolverFields)	使用一组新的解析器字段返回此格式化程序的副本。
DateTimeFormatter	withResolverStyle(ResolverStyle resolverStyle)	使用新的解析器样式返回此格式化程序的副本。
DateTimeFormatter	withZone(ZoneId zone)	使用新的覆盖区域返回此格式化程序的副本。

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

字段详细信息

ISO_LOCAL_DATE

public static final DateTimeFormatter ISO_LOCAL_DATE

ISO日期格式化程序格式化或解析没有偏移量的日期，如“2011-12-03”。

这将返回一个不可变形的格式化程序，能够格式化和解析ISO-8601扩展的本地日期格式。 格式包括：

• year的四位数以上。 在0000到9999之间的年份将被预填零，以确保四位数。 超出该范围的年份将有一个前缀的正或负符号。
• 一个破折号
• month-of-year的两位数字。 这被预填充为零以确保两位数字。
• 一个破折号
• day-of-month的两位数字。 这被预填充为零以确保两位数字。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_OFFSET_DATE

public static final DateTimeFormatter ISO_OFFSET_DATE

ISO日期格式化程序格式化或解析具有偏移量的日期，例如“2011-12-03 + 01：00”。

这将返回一个能够格式化和解析ISO-8601扩展偏移日期格式的不可变格式器。 格式包括：

• ISO_LOCAL_DATE
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 解析不区分大小写。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_DATE

public static final DateTimeFormatter ISO_DATE

ISO日期格式化程序格式化或解析具有偏移量的日期（如可用），如“2011-12-03”或“2011-12-03 + 01：00”。

这将返回一个不可变形的格式化程序，能够格式化和解析ISO-8601扩展日期格式。 格式包括：

• ISO_LOCAL_DATE
• 如果偏移不可用，则格式完成。
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 解析不区分大小写。

由于此格式化程序具有可选元素，因此可能需要使用parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)进行解析。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_LOCAL_TIME

public static final DateTimeFormatter ISO_LOCAL_TIME

ISO时间格式化程序格式化或解析一个没有偏移量的时间，例如“10：15”或“10：15：30”。

这将返回一个不可变形的格式化器，能够格式化和解析ISO-8601扩展的本地时间格式。 格式包括：

• hour-of-day的两位数字。 这被预填充为零以确保两位数字。
• 一个冒号
• 两位数字为minute-of-hour 。 这被预填充为零以确保两位数字。
• 如果第二分钟不可用，则格式完成。
• 一个冒号
• 两位数字为second-of-minute 。 这被预填充为零以确保两位数字。
• 如果纳秒是零或不可用，则格式完成。
• 小数点
• 一到九位数为nano-of-second 。 根据需要输出多个数字。

返回的格式化程序没有覆盖年表或区域。 它使用STRICT解析器风格。

ISO_OFFSET_TIME

public static final DateTimeFormatter ISO_OFFSET_TIME

格式化或解析时间偏移的ISO时间格式化程序，例如“10：15 + 01：00”或“10：15：30 + 01：00”。

这将返回能够格式化和解析ISO-8601扩展偏移时间格式的不可变格式器。 格式包括：

• ISO_LOCAL_TIME
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 解析不区分大小写。

返回的格式化程序没有覆盖年表或区域。 它使用STRICT解析器风格。

ISO_TIME

public static final DateTimeFormatter ISO_TIME

格式化或解析时间的ISO时间格式化程序，如果可用的偏移量，如“10：15”，“10：15：30”或“10：15：30 + 01：00”。

这将返回能够格式化和解析ISO-8601扩展偏移时间格式的不可变格式器。 格式包括：

• ISO_LOCAL_TIME
• 如果偏移不可用，则格式完成。
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 解析不区分大小写。

由于此格式化程序具有可选元素，因此可能需要使用parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)进行解析。

返回的格式化程序没有覆盖年表或区域。 它使用STRICT解析器风格。

ISO_LOCAL_DATE_TIME

public static final DateTimeFormatter ISO_LOCAL_DATE_TIME

ISO日期格式化程序格式化或解析没有偏移量的日期时间，例如“2011-12-03T10：15：30”。

这将返回一个不可变形的格式化器，能够格式化和解析ISO-8601扩展偏移日期时间格式。 格式包括：

• ISO_LOCAL_DATE
• 字母“T”。 解析不区分大小写。
• ISO_LOCAL_TIME

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_OFFSET_DATE_TIME

public static final DateTimeFormatter ISO_OFFSET_DATE_TIME

ISO日期格式化程序格式化或解析具有偏移量的日期时间，例如“2011-12-03T10：15：30 + 01：00”。

这将返回一个不可变形的格式化器，能够格式化和解析ISO-8601扩展偏移日期时间格式。 格式包括：

• ISO_LOCAL_DATE_TIME
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 偏移解析是宽松的，这允许分钟和秒是可选的。 解析不区分大小写。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_ZONED_DATE_TIME

public static final DateTimeFormatter ISO_ZONED_DATE_TIME

类似ISO的日期格式化程序，用于格式化或解析具有偏移和区域的日期时间，例如“2011-12-03T10：15：30 + 01：00 [Europe / Paris]”。

这将返回一个不可变的格式化程序，能够格式化和解析扩展ISO-8601扩展偏移日期时间格式的格式来添加时区。 方括号中的部分不属于ISO-8601标准。 格式包括：

• ISO_OFFSET_DATE_TIME
• 如果区域ID不可用或是ZoneOffset则格式已完成。
• 一个开放的方括号'['。
• zone ID 。 这不是ISO-8601标准的一部分。 解析区分大小写。
• 一个近方括号']'。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_DATE_TIME

public static final DateTimeFormatter ISO_DATE_TIME

类似ISO的日期格式化程序，用于格式化或解析具有偏移量和区域（如果有的话）的日期时间，如“2011-12-03T10：15：30”，“2011-12-03T10：15：30 + 01” ：00'或'2011-12-03T10：15：30 + 01：00 [欧洲/巴黎]'。

这将返回一个不可变形的格式化程序，能够格式化和解析ISO-8601扩展本地或偏移日期时间格式，以及指定时区的扩展非ISO格式。 格式包括：

• ISO_LOCAL_DATE_TIME
• 如果偏移量不可用于格式化或解析，则格式完成。
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。
• 如果区域ID不可用或是ZoneOffset则格式已完成。
• 一个开放的方括号'['。
• zone ID 。 这不是ISO-8601标准的一部分。 解析区分大小写。
• 一个近方括号']'。

由于此格式化程序具有可选元素，因此可能需要使用parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)进行解析。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_ORDINAL_DATE

public static final DateTimeFormatter ISO_ORDINAL_DATE

ISO日期格式化程序格式化或解析没有偏移量的序数日期，例如“2012-337”。

这将返回一个不可变形格式化器，能够格式化和解析ISO-8601扩展序数日期格式。 格式包括：

• year的四位数以上。 在0000到9999之间的年份将被预填零，以确保四位数。 超出该范围的年份将有一个前缀的正或负符号。
• 一个破折号
• 三位数字为day-of-year 。 这被预填充为零以确保三位数字。
• 如果偏移量不可用于格式化或解析，则格式完成。
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 解析不区分大小写。

由于此格式化程序具有可选元素，因此可能需要使用parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)进行解析。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_WEEK_DATE

public static final DateTimeFormatter ISO_WEEK_DATE

ISO日期格式化程序，用于格式化或解析不带偏移量的基于周的日期，例如“2012-W48-6”。

这将返回一个不可变的格式化程序，能够格式化和解析ISO-8601延伸的基于周的日期格式。 格式包括：

• week-based-year四位数以上。 在0000到9999之间的年份将被预填零，以确保四位数。 超出该范围的年份将有一个前缀的正或负符号。
• 一个破折号
• 字母“W”。 解析不区分大小写。
• week-of-week-based-year的两位数字。 这被预填充为零以确保三位数字。
• 一个破折号
• 一位数字为day-of-week 。 价值从星期一（1）到星期日（7）。
• 如果偏移量不可用于格式化或解析，则格式完成。
• offset ID 。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 解析不区分大小写。

由于此格式化程序具有可选元素，因此可能需要使用parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)进行解析。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

ISO_INSTANT

public static final DateTimeFormatter ISO_INSTANT

ISO即时格式化程序，用于格式化或解析UTC中的即时消息，例如“2011-12-03T10：15：30Z”。

这将返回能够格式化和解析ISO-8601即时格式的不可变格式化程序。 格式化时，总是输出第二分钟。 根据需要，毫微秒输出零，三，六或九位数字。 解析时，至少需要秒字段的时间。 解析从0到9的小数秒。 不使用本地化的十进制格式。

这是一个特殊情况格式化程序，旨在允许Instant的人类可读形式。 Instant课程旨在仅代表一个时间点，内部存储从1970-01-01Z固定时期的纳秒值。 因此， Instant不能格式化为日期或时间，而不提供某种形式的时区。 该格式化程序允许Instant格式化，通过使用ZoneOffset.UTC提供合适的转换。

格式包括：

• ISO_OFFSET_DATE_TIME其中即时转换为ChronoField.INSTANT_SECONDS和ChronoField.NANO_OF_SECOND，使用UTC偏移量。 解析不区分大小写。

返回的格式化程序没有覆盖年表或区域。 它使用STRICT解析器样式。

BASIC_ISO_DATE

public static final DateTimeFormatter BASIC_ISO_DATE

格式化或解析没有偏移量的日期的ISO日期格式化程序，例如“20111203”。

这将返回一个不可变形的格式化程序，能够格式化和解析ISO-8601基本本地日期格式。 格式包括：

• year的四位数字。 只支持在0000到9999的范围内。
• month-of-year的两位数字。 这被预填充为零以确保两位数字。
• day-of-month的两位数字。 这被预填充为零以确保两位数字。
• 如果偏移量不可用于格式化或解析，则格式完成。
• offset ID没有冒号。 如果偏移量有秒，那么即使这不是ISO-8601标准的一部分，它们将被处理。 偏移解析是宽松的，这允许分钟和秒是可选的。 解析不区分大小写。

由于此格式化程序具有可选元素，因此可能需要使用parseBest(java.lang.CharSequence, java.time.temporal.TemporalQuery<?>...)进行解析。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用STRICT解析器样式。

RFC_1123_DATE_TIME

public static final DateTimeFormatter RFC_1123_DATE_TIME

RFC-1123日期格式化程序，如“星期二，2008年6月3日11:05:30 GMT”。

这返回一个不可变的格式化器，能够格式化和解析大部分的RFC-1123格式。 RFC-1123更新RFC-822将年份从两位数更改为四位。 该实施需要四位数的年份。 这种实施也不会处理北美或军区的名称，只有'GMT'和偏移量。

格式包括：

• 如果星期几不可用于格式化或解析，然后跳到月份。
• 三个字母day-of-week英文
• 一个逗号
• 一个空间
• day-of-month的一位或两位数字。
• 一个空间
• 三个字母month-of-year英文。
• 一个空间
• year的四位数字。 只支持在0000到9999的范围内。
• 一个空间
• hour-of-day的两位数字。 这被预填充为零以确保两位数字。
• 一个冒号
• 两位数字为minute-of-hour 。 这被预填充为零以确保两位数字。
• 如果第二分钟不可用，则跳转到下一个空格。
• 一个冒号
• second-of-minute的两位数字。 这被预填充为零以确保两位数字。
• 一个空间
• offset ID没有冒号或秒钟。 零偏移使用“GMT”。 北美地区名称和军区名称不予处理。

解析不区分大小写。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用SMART解析器样式。

方法详细信息

ofPattern

public static DateTimeFormatter ofPattern(String pattern)

使用指定的模式创建格式化程序。

该方法将基于类文档中描述的简单的pattern of letters and symbols创建一个格式化程序。 例如， d MMM uuuu将格式为2011-12-03，为“2011年12月3日”。

格式化程序将使用default FORMAT locale 。 这可以使用withLocale(Locale)在返回的格式化器上更改或者使用此方法的ofPattern(String, Locale)变体。

返回的格式化程序没有覆盖年表或区域。 它使用SMART解析器风格。

参数

pattern - 要使用的模式，不为空

结果

格式化程序基于模式，不为空

异常

IllegalArgumentException - 如果模式无效

另请参见：

DateTimeFormatterBuilder.appendPattern(String)

ofPattern

public static DateTimeFormatter ofPattern(String pattern,
                                          Locale locale)

使用指定的模式和区域设置创建格式化程序。

该方法将基于类文档中所述的简单的pattern of letters and symbols创建一个格式化程序。 例如， d MMM uuuu将格式为2011-12-03，为“2011年12月3日”。

格式化程序将使用指定的区域设置。 这可以使用返回的格式化程序上的withLocale(Locale)进行更改

返回的格式化程序没有覆盖年表或区域。 它使用SMART解析器风格。

参数

pattern - 使用的模式，不为空

locale - 要使用的语言环境，不为空

结果

格式化程序基于模式，不为空

异常

IllegalArgumentException - 如果模式无效

另请参见：

DateTimeFormatterBuilder.appendPattern(String)

ofLocalizedDate

public static DateTimeFormatter ofLocalizedDate(FormatStyle dateStyle)

返回ISO年表的区域设置特定日期格式。

这将返回格式化程序，以格式化或解析日期。 所使用的确切格式模式因地区而异。

区域设置是从格式化程序确定的。 该方法直接返回的格式化程序将使用default FORMAT locale 。 可以使用withLocale(Locale)对该方法的结果进行控制。

请注意，本地化模式被懒惰地查找。 这个DateTimeFormatter拥有所需的风格和语言环境，查找需要的模式。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用SMART解析器样式。

参数

dateStyle - 获取格式化程序样式，不为null

结果

日期格式化程序，不为null

ofLocalizedTime

public static DateTimeFormatter ofLocalizedTime(FormatStyle timeStyle)

返回ISO时代的区域设置特定时间格式。

这将返回一个格式化程序，用于格式化或解析一个时间。 所使用的确切格式模式因地区而异。

区域设置是从格式化程序确定的。 该方法直接返回的格式化程序将使用default FORMAT locale 。 该方法的结果可以使用withLocale(Locale)控制本地区域。

请注意，本地化模式被懒惰地查找。 这个DateTimeFormatter拥有所需的风格和语言环境，查找需要的模式。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用SMART解析器样式。 FULL和LONG样式通常需要时区。 使用这些样式进行格式化时， ZoneId必须使用ZonedDateTime或withZone(java.time.ZoneId) 。

参数

timeStyle - 获取格式化程序样式，不为null

结果

时间格式化，不为空

ofLocalizedDateTime

public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateTimeStyle)

返回ISO时代的区域设置特定的日期时间格式化程序。

这将返回格式化程序，以格式化或解析日期时间。 所使用的确切格式模式因地区而异。

区域设置是从格式化程序确定的。 通过此方法直接返回的格式化程序将使用default FORMAT locale 。 可以使用withLocale(Locale)对该方法的结果进行控制。

请注意，本地化模式被懒惰地查找。 这个DateTimeFormatter拥有所需的风格和语言环境，查找需要的模式。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用SMART解析器样式。 FULL和LONG样式通常需要时区。 使用这些样式格式化时， ZoneId必须使用ZonedDateTime或withZone(java.time.ZoneId) 。

参数

dateTimeStyle - 格式化器样式获取，不为null

结果

日期时间格式化程序，不为空

ofLocalizedDateTime

public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateStyle,
                                                    FormatStyle timeStyle)

返回ISO时代的特定日期和时间格式。

这将返回格式化程序，以格式化或解析日期时间。 所使用的确切格式模式因地区而异。

区域设置是从格式化程序确定的。 通过这种方法直接返回的格式化程序将使用default FORMAT locale 。 可以使用withLocale(Locale)对该方法的结果进行控制。

请注意，本地化模式被懒惰地查找。 这个DateTimeFormatter拥有所需的风格和语言环境，查找需要的模式。

返回的格式化程序具有ISO设置的时间顺序，以确保其他日历系统中的日期正确转换。 它没有覆盖区域，并使用SMART解析器样式。 FULL和LONG样式通常需要时区。 使用这些样式进行格式化时， ZoneId必须使用ZonedDateTime或withZone(java.time.ZoneId) 。

参数

dateStyle - 获取的日期格式化程序样式，不为null

timeStyle - 获取时间格式化器样式，不为null

结果

日期，时间或日期时间格式化程序，不为空

parsedExcessDays

public static final TemporalQuery<Period> parsedExcessDays()

一个查询，可以访问已解析的多余天数。

这将返回一个单例query ，它可以从解析中访问附加信息。 查询始终返回一个非空期，返回零期，而不是null。

有两种情况，即该查询可能返回非零期。

• 如果ResolverStyle是LENIENT并且没有日期的时间被解析，则解析的完整结果由LocalTime和过多的Period天数组成。
• 如果ResolverStyle为SMART和其中时间是24:00:00，一时间不注日期的解析，则解析的完整结果由的LocalTime的00:00:00和过量Period一天。

在这两种情况下，如果完整的ChronoLocalDateTime或Instant被解析，则多余的天数将添加到日期部分。 因此，此查询将返回零期。

SMART行为处理常见的“结束”24:00的值。 在LENIENT模式下处理也产生相同的结果：

  Text to parse        Parsed object                         Excess days
  "2012-12-03T00:00"   LocalDateTime.of(2012, 12, 3, 0, 0)   ZERO
  "2012-12-03T24:00"   LocalDateTime.of(2012, 12, 4, 0, 0)   ZERO
  "00:00"              LocalTime.of(0, 0)                    ZERO
  "24:00"              LocalTime.of(0, 0)                    Period.ofDays(1) 

查询可以使用如下：

  TemporalAccessor parsed = formatter.parse(str);
  LocalTime time = parsed.query(LocalTime::from);
  Period extraDays = parsed.query(DateTimeFormatter.parsedExcessDays()); 

结果

一个查询，可以访问已解析的多余天数

parsedLeapSecond

public static final TemporalQuery<Boolean> parsedLeapSecond()

提供访问是否解析了跨越秒的查询。

这将返回一个单数query ，它可以从解析中访问附加信息。 查询总是返回一个非空的布尔值，如果解析看到一个闰秒，则返回true，否则返回false。

即时解析处理“23：59：60”的特殊“闰秒”时间。 在UTC时区的“23：59：60”发生跳跃秒，但在不同时区的其他本地时间。 为了避免这种潜在的歧义，闰秒的处理限制为DateTimeFormatterBuilder.appendInstant() ，因为该方法总是使用UTC区域偏移解析瞬间。

如果接收到'23：59：60'的时间，则应用简单的转换，用59替换第60分钟。该查询可以用于解析结果，以确定闰秒调整是否为制作。 查询将返回true如果它调整了删除闰秒，而false如果没有。 请注意，应用跨平台的平滑机制，如UTC-SLS，是应用程序的责任，如下所示：

  TemporalAccessor parsed = formatter.parse(str);
  Instant instant = parsed.query(Instant::from);
  if (parsed.query(DateTimeFormatter.parsedLeapSecond())) {
    // validate leap-second is correct and apply correct smoothing
  } 

结果

一个提供访问是否解析了闰秒的查询

getLocale

public Locale getLocale()

获取格式化期间要使用的区域设置。

这用于查找需要特定本地化的格式化程序的任何部分，例如文本或本地化模式。

结果

这个格式化程序的区域设置不为空

withLocale

public DateTimeFormatter withLocale(Locale locale)

使用新的语言环境返回此格式化程序的副本。

这用于查找需要特定本地化的格式化程序的任何部分，例如文本或本地化模式。

此实例是不可变的，不受此方法调用的影响。

参数

locale - 新的区域设置，不为null

结果

一个基于格式化程序的格式化程序，具有所请求的区域设置，不为null

getDecimalStyle

public DecimalStyle getDecimalStyle()

获取在格式化期间使用的DecimalStyle。

结果

这个格式化程序的区域设置不为空

withDecimalStyle

public DateTimeFormatter withDecimalStyle(DecimalStyle decimalStyle)

使用新的DecimalStyle返回此格式化程序的副本。

此实例是不可变的，不受此方法调用的影响。

参数

decimalStyle - 新的DecimalStyle，不为null

结果

一个格式化程序基于该格式化程序与请求的DecimalStyle，不为null

getChronology

public Chronology getChronology()

获得在格式化期间使用的压倒一记的年表。

这将返回覆盖年表，用于转换日期。 默认情况下，格式化程序没有覆盖时间顺序，返回null。 有关覆盖的详细信息，请参阅withChronology(Chronology) 。

结果

这个格式化器的覆盖年表，如果没有覆盖，则为null

withChronology

public DateTimeFormatter withChronology(Chronology chrono)

使用新的覆盖年表返回此格式化程序的副本。

这会返回一个格式化器，具有与该格式化程序相似的状态，但是覆盖时间顺序集。 默认情况下，格式化程序没有覆盖时间顺序，返回null。

如果添加了覆盖，则格式化或解析的任何日期都将受到影响。

格式化时，如果时间对象包含日期，那么它将被转换为覆盖年表中的日期。 是否包含日期是通过查询EPOCH_DAY字段来确定的。 任何时间或区域将保留不变，除非被覆盖。

如果时间对象不包含日期，但包含一个或多个ChronoField日期字段，然后DateTimeException被抛出。 在所有其他情况下，覆盖年表被添加到时间，替换任何以前的年表，但不更改日期/时间。

解析时有两种不同的情况需要考虑。 如果一个年表从文本中直接解析出来，也许是因为使用了DateTimeFormatterBuilder.appendChronologyId() ，那么这个覆盖年表没有任何效果。 如果没有分区被解析，那么这个覆盖年表将用于根据年表的日期解析规则将ChronoField值解释为日期。

此实例是不可变的，不受此方法调用的影响。

参数

chrono - 新的年表，如果不覆盖，则为null

结果

一个基于该格式化器的格式化程序，具有请求的覆盖时间顺序，不为null

getZone

public ZoneId getZone()

获取在格式化期间使用的覆盖区域。

这将返回覆盖区域，用于转换时刻。 默认情况下，格式化程序没有覆盖区域，返回null。 有关覆盖的更多详细信息，请参阅withZone(ZoneId) 。

结果

该格式化程序的覆盖区域为null，如果不覆盖则为null

withZone

public DateTimeFormatter withZone(ZoneId zone)

使用新的覆盖区域返回此格式化程序的副本。

这将返回一个格式化程序，具有与该格式化程序类似的状态，但是覆盖区域设置。 默认情况下，格式化程序没有覆盖区域，返回null。

如果添加了覆盖，则格式化或解析的任何即时将受到影响。

格式化时，如果时间对象包含一个瞬间，则将使用覆盖区域将其转换为分区的日期时间。 时间是否是瞬间是通过查询INSTANT_SECONDS字段来确定的。 如果输入具有时间顺序，那么它将被保留，除非被覆盖。 如果输入没有时间顺序，例如Instant ，那么将使用ISO年表。

如果时间对象不包含一个时刻，但是包含一个偏移量，则进行额外的检查。 如果归一化覆盖区域是与时间偏移量不同的偏移量，则抛出DateTimeException 。 在所有其他情况下，将覆盖区域添加到时间，替换任何先前的区域，但不更改日期/时间。

解析时有两种不同的情况需要考虑。 如果一个区域直接从文本中解析出来，也许是因为使用了DateTimeFormatterBuilder.appendZoneId() ，那么这个覆盖区域就没有效果。 如果没有分区被解析，那么这个覆盖区域将包含在解析结果中，可以用于构建时间和日期时间。

此实例是不可变的，不受此方法调用的影响。

参数

zone - 新的覆盖区域，如果不覆盖，则为null

结果

一个格式化程序基于该格式化程序与请求的覆盖区域，不为null

getResolverStyle

public ResolverStyle getResolverStyle()

获取在解析过程中使用的解析器样式。

这将返回解析器样式，当字段解析为日期和时间时，在解析的第二阶段使用。 默认情况下，格式化程序具有SMART解析器样式。 详见withResolverStyle(ResolverStyle) 。

结果

这个格式化程序的解析器样式，不为null

withResolverStyle

public DateTimeFormatter withResolverStyle(ResolverStyle resolverStyle)

使用新的解析器样式返回此格式化程序的副本。

这会返回一个格式化程序，与格式化程序具有类似的状态，但是会使用解析器样式集。 默认情况下，格式化程序具有SMART解析器样式。

更改解析器样式只能在解析过程中产生效果。 解析文本字符串分两个阶段。 阶段1是根据添加到构建器的字段的基本文本解析。 阶段2将解析的字段值对解析为日期和/或时间对象。 解析器样式用于控制阶段2，解决方式的发生。 有关可用选项的更多信息，请参阅ResolverStyle 。

此实例是不可变的，不受此方法调用的影响。

参数

resolverStyle - 新的解析器样式，不为空

结果

一个基于格式化器的格式化程序，具有请求的解析器样式，不为空

getResolverFields

public Set<TemporalField> getResolverFields()

获取在解析期间使用的解析器字段。

这将返回解析器字段，在字段解析为日期和时间时在解析的第二阶段使用。 默认情况下，格式化程序没有解析器字段，因此返回null。 详见withResolverFields(Set) 。

结果

这个格式化程序的不可变解析器字段集合，如果没有字段则为null

withResolverFields

public DateTimeFormatter withResolverFields(TemporalField... resolverFields)

使用一组新的解析器字段返回此格式化程序的副本。

这将返回一个格式化程序，与格式化程序具有相似的状态，但解析器字段设置。 默认情况下，格式化程序没有解析器字段。

在解析过程中，更改解析器字段仅具有效果。 解析文本字符串分两个阶段。 阶段1是根据添加到构建器的字段的基本文本解析。 阶段2将解析的字段值对解析为日期和/或时间对象。 解析器字段用于过滤阶段1和阶段2之间的字段值对。

这可以用于在日期或时间可能被解决的两种或更多种方式之间进行选择。 例如，如果格式化程序由年，月，日，月和日组成，则有两种方法来解决日期。 使用参数YEAR和DAY_OF_YEAR调用此方法将确保使用年份和日期解决日期，有效地意味着在解决阶段忽略月份和日期。

以类似的方式，该方法可以用于忽略否则将被交叉检查的次级字段。 例如，如果格式化程序由年份，月份，月份和星期几组成，则只有一种方法可以解决日期，但是每周的解析值将被交叉检查反对解决日期。 调用此方法与参数YEAR ， MONTH_OF_YEAR和DAY_OF_MONTH将确保日期是正确解决，但没有任何交叉检查的某一天的一周。

在实现方面，该方法的行为如下。 分析阶段的结果可以被认为是一个字段到值的映射。 此方法的行为是使该映射在阶段1和阶段2之间进行过滤，除去除了指定为该方法的参数之外的所有字段。

此实例是不可变的，不受此方法调用的影响。

参数

resolverFields - 新的解析器字段集合，如果没有字段，则为null

结果

一个基于格式化器的格式化程序，具有请求的解析器样式，不为空

withResolverFields

public DateTimeFormatter withResolverFields(Set<TemporalField> resolverFields)

使用一组新的解析器字段返回此格式化程序的副本。

这将返回一个格式化程序，与格式化程序具有相似的状态，但解析器字段设置。 默认情况下，格式化程序没有解析器字段。

在解析过程中，更改解析器字段仅具有效果。 解析文本字符串分两个阶段。 阶段1是根据添加到构建器的字段的基本文本解析。 阶段2将解析的字段值对解析为日期和/或时间对象。 解析器字段用于过滤阶段1和阶段2之间的字段值对。

这可以用于在日期或时间可能被解决的两种或更多种方式之间进行选择。 例如，如果格式化程序由年，月，日，月和日组成，则有两种方法来解决日期。 使用参数YEAR和DAY_OF_YEAR调用此方法将确保使用年份和日期来解决日期，有效地意味着在解决阶段忽略月份和日期。

以类似的方式，该方法可以用于忽略否则将被交叉检查的次级字段。 例如，如果格式化程序由年份，月份，月份和星期几组成，则只有一种方法可以解决日期，但是每周的解析值将被交叉检查反对解决日期。 调用此方法与参数YEAR ， MONTH_OF_YEAR和DAY_OF_MONTH将确保日期是正确解决，但没有任何交叉检查的某一天的一周。

在实现方面，该方法的行为如下。 分析阶段的结果可以被认为是一个字段到值的映射。 此方法的行为是使该映射在阶段1和阶段2之间进行过滤，除去除了指定为该方法的参数之外的所有字段。

此实例是不可变的，不受此方法调用的影响。

参数

resolverFields - 新的解析器字段集合，如果没有字段，则为null

结果

一个基于格式化器的格式化程序，具有请求的解析器样式，不为空

format

public String format(TemporalAccessor temporal)

使用此格式化程序格式化日期时间对象。

这将使用格式化程序的规则将日期时间格式化为String。

参数

temporal - 要格式化的时间对象，不为null

结果

格式化的字符串，不为null

异常

DateTimeException - 如果在格式化期间发生错误

formatTo

public void formatTo(TemporalAccessor temporal,
                     Appendable appendable)

使用此格式化程序将日期时间对象格式化为Appendable 。

这将格式化的日期时间输出到指定的目的地。 Appendable是受所有键字符输出类别，包括实现一个通用接口StringBuffer ， StringBuilder ， PrintStream和Writer 。

虽然Appendable方法抛出一个IOException ，这个方法没有。 相反，任何IOException都包含在运行时异常中。

参数

temporal - 要格式化的时间对象，不为空

appendable - 可附加格式化，不为空

异常

DateTimeException - 如果在格式化期间发生错误

parse

public TemporalAccessor parse(CharSequence text)

完全解析产生时间对象的文本。

这解析整个文本，产生一个时间对象。 通常使用parse(CharSequence, TemporalQuery)更有用。 该方法的结果为TemporalAccessor ，已经解决，应用基本的验证检查，以确保有效的日期时间。

如果解析完成，而不读取文本的整个长度，或者在解析或合并期间发生问题，则抛出异常。

参数

text - 要解析的文本，不为空

结果

解析的时间对象，不为null

异常

DateTimeParseException - 如果无法解析请求的结果

parse

public TemporalAccessor parse(CharSequence text,
                              ParsePosition position)

使用此格式化器解析文本，提供对文本位置的控制。

这样解析文本，而不需要解析从字符串的开头开始，或者在结尾处完成。 该方法的结果为TemporalAccessor ，已经解决，应用基本的验证检查，以确保有效的日期时间。

文本将从指定的开始ParsePosition解析。 文本的整个长度不需要解析， ParsePosition将在解析结束时用索引进行更新。

该方法的操作与使用ParsePosition在java.text.Format上的类似方法略有不同。 该类将使用ParsePosition上的错误索引返回错误。 相比之下，如果发生错误，此方法将抛出一个DateTimeParseException ，异常包含错误索引。 由于在此API中解析和解析日期/时间的复杂性增加，因此行为变化是必要的。

如果格式化程序用不同的值解析相同的字段多次，结果将是一个错误。

参数

text - 要解析的文本，不为null

position - 解析的位置，更新长度解析和任何错误的索引，不为空

结果

解析的时间对象，不为null

异常

DateTimeParseException - 如果无法解析请求的结果

IndexOutOfBoundsException - 如果位置无效

parse

public <T> T parse(CharSequence text,
                   TemporalQuery<T> query)

完全解析产生指定类型对象的文本。

大多数应用程序应该使用此方法进行解析。 它解析整个文本以产生所需的日期时间。 该查询通常是对from(TemporalAccessor)方法的方法引用。 例如：

  LocalDateTime dt = parser.parse(str, LocalDateTime::from); 

如果解析完成，而不读取文本的整个长度，或者在解析或合并期间发生问题，则抛出异常。

参数类型

T - 解析日期时间的类型

参数

text - 要解析的文本，不为空

query - 定义要解析的类型的查询，不为null

结果

解析的日期时间，不为null

异常

DateTimeParseException - 如果无法解析请求的结果

parseBest

public TemporalAccessor parseBest(CharSequence text,
                                  TemporalQuery<?>... queries)

完全解析产生指定类型之一的对象的文本。

当解析器可以处理可选元素时，此解析方法便于使用。 例如，'uuuu-MM-dd HH.mm [VV]'的模式可以完全解析为ZonedDateTime ，或部分解析为LocalDateTime 。 必须按顺序指定查询，从最佳匹配的全解析选项开始，以最差匹配的最小分析选项结束。 该查询通常是对from(TemporalAccessor)方法的方法引用。

结果与成功解析的第一种类型相关联。 通常，应用程序将使用instanceof来检查结果。 例如：

  TemporalAccessor dt = parser.parseBest(str, ZonedDateTime::from, LocalDateTime::from);
  if (dt instanceof ZonedDateTime) {
   ...
  } else {
   ...
  } 

如果解析完成，而不读取文本的整个长度，或者在解析或合并期间发生问题，则抛出异常。

参数

text - 要解析的文本，不为空

queries - 定义要尝试解析的类型的查询必须实现 TemporalAccessor ，不为空

结果

解析的日期时间，不为null

异常

IllegalArgumentException - 如果指定少于2种类型

DateTimeParseException - 如果无法解析请求的结果

parseUnresolved

public TemporalAccessor parseUnresolved(CharSequence text,
                                        ParsePosition position)

使用此格式化程序解析文本，而无需解析结果，用于高级用例。

解析实现为两阶段操作。 首先，使用格式化程序定义的布局来解析文本，产生一个Map字段的值，一个ZoneId和一个Chronology 。 第二，通过验证，组合和简化各种领域，使解析的数据得到解决 。 该方法执行解析阶段，但不执行解析阶段。

该方法的结果为TemporalAccessor ，表示输入中所见的数据。 价值观不验证，因此解析“2012-00-65”的日期字符串将导致三个字段的时间 - “2012”年份，“0”月份和“65”的月份。

文本将从指定的起始ParsePosition解析。 文本的整个长度不需要解析， ParsePosition将在解析结束时使用索引进行更新。

使用ParsePosition的错误索引字段而不是DateTimeParseException返回错误。 返回的错误索引将被设置为指示错误的索引。 使用结果之前，来电者必须检查错误。

如果格式化程序用不同的值解析相同的字段多次，结果将是一个错误。

此方法适用于在解析期间需要访问内部状态的高级用例。 典型的应用代码应该使用parse(CharSequence, TemporalQuery)或目标类型的解析方法。

参数

text - 要解析的文本，不为空

position - 解析的位置，更新长度解析和任何错误的索引，不为空

结果

解析文本，如果解析导致错误，则为null

异常

DateTimeException - 如果在解析期间发生某些问题

IndexOutOfBoundsException - 如果位置无效

toFormat

public Format toFormat()

将此格式化程序作为java.text.Format实例返回。

返回的Format实例将格式化任何TemporalAccessor并解析到解析的TemporalAccessor 。

例外将遵循Format的定义，有关详细信息，请参阅这些方法IllegalArgumentException在格式化期间和ParseException或解析期间为空。 格式不支持返回格式字符串的属性。

结果

这个格式化程序作为一个经典的格式实例，不为null

toFormat

public Format toFormat(TemporalQuery<?> parseQuery)

将此格式化程序作为java.text.Format实例返回，使用指定的查询进行解析。

返回的Format实例将格式化任何TemporalAccessor并解析到指定的类型。 该类型必须是parse(java.lang.CharSequence)支持的类型 。

例外将遵循Format的定义，有关详细信息，请参阅这些方法IllegalArgumentException在格式化期间和ParseException或解析期间为空。 格式不支持返回格式字符串的属性。

参数

parseQuery - 查询定义要解析的类型，不为null

结果

这个格式化程序作为一个经典的格式实例，不为null

toString

public String toString()

返回底层格式化程序的描述。

重写：

toString在 Object

结果

a description of this formatter, not null