public final class DateTimeFormatterBuilder extends Object
这样可以创建一个DateTimeFormatter 。 最终使用此构建器创建所有日期时间格式化程序。
日期时间的基本元素可以全部添加：
最后，可以使用与java.text.SimpleDateFormat SimpleDateFormat大部分兼容的速记模式，参见appendPattern(String) 。 在实践中，这简单地解析模式，并在构建器上调用其他方法。
| Constructor and Description |
|---|
DateTimeFormatterBuilder()
构建构建器的新实例。
|
public static String getLocalizedDateTimePattern(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale)
dateStyle - 日期的FormatStyle
timeStyle - 当时的FormatStyle
chrono - 年表，非空
locale - 区域设置，非空
IllegalArgumentException - 如果dateStyle和timeStyle都为null
public DateTimeFormatterBuilder parseCaseSensitive()
解析可以区分大小写或不敏感 - 默认情况下区分大小写。 该方法允许更改解析的区分大小写设置。
调用此方法可更改构建器的状态，以便所有后续构建器方法调用将在区分大小写模式下解析文本。 有关相反的设置，请参阅parseCaseInsensitive() 。 解析器区分敏感/不敏感的方法可能会在构建器中的任何位置被调用，因此解析器可以在解析之间多次在案例解析模式之间进行交换。
由于默认值区分大小写，因此此方法只能在之前调用#parseCaseInsensitive之前使用。
public DateTimeFormatterBuilder parseCaseInsensitive()
解析可以区分大小写或不敏感 - 默认情况下区分大小写。 该方法允许更改解析的区分大小写设置。
调用此方法会更改构建器的状态，以便所有后续构建器方法调用将在不区分大小写模式下解析文本。 参见parseCaseSensitive()相反的设置。 解析器区分敏感/不敏感的方法可能会在构建器中的任何位置被调用，因此解析器可以在解析之间多次在案例解析模式之间进行交换。
public DateTimeFormatterBuilder parseStrict()
解析可以严格或宽松 - 默认是严格的。 这控制了匹配文本和符号样式的灵活性。
使用该方法时，此方法将此解析更改为严格。 由于strict是默认的，通常只需要调用parseLenient()才能使用 。 该更改将一直有效，直到最终构建的格式化程序结束或直到parseLenient 。
public DateTimeFormatterBuilder parseLenient()
解析可以严格或宽松 - 默认是严格的。 这控制了匹配文本和符号样式的灵活性。 调用此方法的应用程序通常也应该调用parseCaseInsensitive() 。
当使用此方法时，此方法将此解析从该点更改为宽松。 该更改将一直有效，直到最终构建的格式化程序结束或直到parseStrict 。
public DateTimeFormatterBuilder parseDefaulting(TemporalField field, long value)
这将附加一个指令给构建器，以将默认值注入到解析结果中。 这与格式化程序的可选部分特别有用。
例如，考虑一个解析年份的格式化程序，然后是可选的月份，另外可以选择一个月。 使用这样的格式化程序将需要调用代码来检查是否已经解析了完整的日期，年月或仅仅一年。 此方法可用于将月份和日期默认为明智的值，例如月中的第一个，允许调用代码始终获取日期。
格式化时，此方法无效。
在解析过程中，将检查解析器的当前状态。 如果指定的字段没有关联的值，因为在该点没有成功解析，那么将指定的值注入到解析结果中。 注入是立即的，因此字段值对将对格式化程序中的任何后续元素可见。 因此，通常在构建器的末尾调用此方法。
field - 该字段默认的值不为null
value - 默认值为
public DateTimeFormatterBuilder appendValue(TemporalField field)
字段的值将在格式化期间输出。 如果无法获取该值，则抛出异常。
该值将按照整数值的普通格式打印。 只有负数将被签署。 将不添加填充。
可变宽度值的解析器通常表现得很贪婪，需要一位数字，但尽可能接受数字。 这种行为可能受到“相邻值解析”的影响。 详见appendValue(java.time.temporal.TemporalField, int) 。
field - 要追加的字段，不为null
public DateTimeFormatterBuilder appendValue(TemporalField field, int width)
字段的值将在格式化期间输出。 如果无法获取该值，则抛出异常。
该值将在左侧零填充。 如果值的大小意味着它不能在宽度内打印，则抛出异常。 如果该字段的值为负值，则在格式化期间抛出异常。
该方法支持一种称为“相邻值解析”的特殊解析技术。 该技术解决了值，变量或固定宽度后面跟着一个或多个固定长度值的问题。 标准解析器是贪心的，因此它通常会窃取跟随变量width one的固定宽度值解析器所需的数字。
启动“相邻值解析”不需要任何操作。 当调用appendValue时，构建器进入相邻值解析设置模式。 如果立即后续方法调用或调用相同的构建器为固定宽度值，则解析器将保留空间，以便可以解析固定宽度值。
例如，考虑builder.appendValue(YEAR).appendValue(MONTH_OF_YEAR, 2);年份是1到19位数之间的变量宽度解析。 这个月是两位数的固定宽度解析。 因为这些被立即附加到同一个构建器上，所以年解析器将为该月份预留两位数字来解析。 因此，文本“201106”将正确解析为2011年和6个月。如果没有相邻的值解析，那么年份会贪婪地解析所有6位数，并且不会对该月份留下任何东西。
相邻值解析适用于解析器中紧随任何类型的值，变量或固定宽度的每组固定宽度非负值。 调用任何其他追加方法将结束相邻值解析的设置。 因此，在不太可能需要避免相邻值解析行为的情况下，只需将appendValue添加到另一个DateTimeFormatterBuilder ，并将其添加到此构建器。
如果相邻解析处于活动状态，则解析必须与严格和宽松模式中的指定数字数字完全匹配。 此外，不允许使用正号或负号。
field - 要追加的字段，不为null
width - 打印字段的宽度，从1到19
IllegalArgumentException - 如果宽度无效
public DateTimeFormatterBuilder appendValue(TemporalField field, int minWidth, int maxWidth, SignStyle signStyle)
字段的值将在格式化期间输出。 如果无法获取该值，则抛出异常。
该方法可以完全控制数字格式，包括零填充和正负号。
可变宽度值的解析器通常表现得很贪婪，尽可能接受多个数字。 这种行为可能受到“相邻值解析”的影响。 详见appendValue(java.time.temporal.TemporalField, int) 。
在严格解析模式下，解析数字的最小数量为minWidth ，最大为maxWidth 。 在宽大的解析模式中，最小解析数字数为1，最大为19（除了由相邻值解析限制）。
如果此方法以相同的最小和最大宽度调用，并且符号样式为NOT_NEGATIVE则它将委托给appendValue(TemporalField,int) 。 在这种情况下，会出现描述的格式和解析行为。
field - 要追加的字段，不为null
minWidth - 打印字段的最小字段宽度，从1到19
maxWidth - 打印字段的最大字段宽度，从1到19
signStyle - 正/负输出样式，不为空
IllegalArgumentException - 如果宽度无效
public DateTimeFormatterBuilder appendValueReduced(TemporalField field, int width, int maxWidth, int baseValue)
由于诸如年份等字段因年表而异，建议在大多数情况下使用此方法的appendValueReduced(TemporalField, int, int, ChronoLocalDate) date}变体。 此变体适用于简单字段或仅使用ISO年表。
对于格式化， width和maxWidth用于确定要格式化的字符数。 如果它们相等，则格式是固定宽度。 如果字段的值在baseValue范围内，使用width字符，则缩减值将被格式化，否则该值将被截断以适合maxWidth 。 输出最右边的字符以匹配宽度，左填充为零。
为了严格解析， width到maxWidth允许的width maxWidth被解析。 对于宽泛的解析，字符数必须至少为1且小于10.如果解析的位数等于width ，并且值为正，则该字段的值被计算为大于或等于的第一个数字到baseValue具有相同的最低有效字符，否则解析的值是字段值。 这允许为baseValue和width的范围内的值输入减小的值，并且可以为范围之外的值输入绝对值。
例如，基数值为1980 ，宽度为2将具有1980至2079 。 在解析期间，文本"12"将导致值2012 ，因为这是最后两个字符为“12”的范围内的值。 相比之下，解析文本"1915"将导致值1915 。
field - 要追加的字段，不为null
width - 打印和解析字段的字段宽度，从1到10
maxWidth - 打印字段的最大字段宽度，从1到10
baseValue - 有效值范围的基值
IllegalArgumentException - 如果宽度或基数值无效
public DateTimeFormatterBuilder appendValueReduced(TemporalField field, int width, int maxWidth, ChronoLocalDate baseDate)
这通常用于格式化和解析两位数年份。
基准日期用于在解析期间计算完整值。 例如，如果基准日期是1950-01-01，则两位数年份解析的解析值将在1950-01-01到2049-12-31之间。 只有一年才会从日期提取，因此1950-08-25的基准日期也将解析到1950-01-01到2049-12-31之间的范围。 这种行为是必要的，以支持字段，例如周分年或其他日历系统，其中解析值与标准ISO年不一致。
具体行为如下。 解析整套字段，并使用最后的年表确定有效的年表，如果它出现不止一次。 然后将基准日期转换为有效的年表。 然后从时间特定的基准日期提取指定的字段，并使用它来确定下面使用的baseValue 。
对于格式化， width和maxWidth用于确定要格式化的字符数。 如果它们相等，则格式是固定宽度。 如果字段的值在baseValue的范围内，使用width字符，则缩减值将被格式化，否则将截断该值以适应maxWidth 。 输出最右边的字符以匹配宽度，左填充为零。
对于严格解析， width到maxWidth允许的width maxWidth被解析。 对于宽泛的解析，字符数必须至少为1且小于10.如果解析的位数等于width ，并且值为正，则该字段的值被计算为大于或等于的第一个数字到baseValue具有相同的最低有效字符，否则解析的值是字段值。 这允许为baseValue和width的范围内的值输入减小的值，并且可以为范围之外的值输入绝对值。
例如，基值为1980 ，宽度为2将为1980至2079 。 在解析期间，文本"12"将导致值2012 ，因为最后两个字符为“12”的范围内的值。 相比之下，解析文本"1915"将导致值1915 。
field - 要追加的字段，不为null
width - 打印和解析字段的字段宽度，从1到10
maxWidth - 打印字段的最大字段宽度，从1到10
baseDate - 用于计算解析年表中有效值范围的基础值的基准日期，不为null
IllegalArgumentException - 如果宽度或基数值无效
public DateTimeFormatterBuilder appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)
将输出字段的小数值，包括前面的小数点。 不输出上述值。 例如，15的第二分钟值将输出为.25 。
可以控制印刷分数的宽度。 将最小宽度设置为零将不会产生输出。 打印的分数将具有最小宽度和最大宽度之间所需的最小宽度 - 尾随零被省略。 由于最大宽度不会发生舍入 - 数字被简单地丢弃。
在严格模式下解析时，解析数字的数目必须在最小和最大宽度之间。 当在宽松模式下解析时，最小宽度被认为是零，最大值为9。
如果无法获取该值，则抛出异常。 如果值为负，将抛出异常。 如果该字段没有固定的有效值集合，那么将抛出异常。 如果要打印的日期时间中的字段值无效，则无法打印并将抛出异常。
field - 要追加的字段，不为null
minWidth - 不包括小数点的字段的最小宽度，从0到9
maxWidth - 不包括小数点的字段的最大宽度，从1到9
decimalPoint - 是否输出本地化的小数点符号
IllegalArgumentException - 如果该字段具有有效值的变量集或宽度无效
public DateTimeFormatterBuilder appendText(TemporalField field)
字段的文本将在格式化期间输出。 该值必须在该字段的有效范围内。 如果无法获取该值，则抛出异常。 如果该字段没有文本表示，那么将使用该数值。
该值将按照整数值的普通格式打印。 只有负数将被签署。 将不添加填充。
field - 要追加的字段，不为null
public DateTimeFormatterBuilder appendText(TemporalField field, TextStyle textStyle)
字段的文本将在格式化期间输出。 该值必须在该字段的有效范围内。 如果无法获取该值，则抛出异常。 如果该字段没有文本表示，那么将使用该数值。
该值将按照整数值的普通格式打印。 只有负数将被签署。 将不添加填充。
field - 要追加的字段，不为null
textStyle - 要使用的文本样式，不为null
public DateTimeFormatterBuilder appendText(TemporalField field, Map<Long,String> textLookup)
标准文本输出方法使用JDK中的本地化文本。 该方法允许直接指定文本。 提供的映射未由构建器验证，以确保格式化或解析可能，因此无效映射可能会在以后使用时发生错误。
提供文本的地图在格式化和解析方面提供了很大的灵活性。 例如，遗留应用程序可能要求或提供一年中的几个月为“JNY”，“FBY”，“MCH”等。这些不符合本地化月份名称的标准文本集。 使用此方法，可以创建一个映射，定义每个值和文本之间的连接：
Map<Long, String> map = new HashMap<>();
map.put(1, "JNY");
map.put(2, "FBY");
map.put(3, "MCH");
...
builder.appendText(MONTH_OF_YEAR, map);
其他用途可能是用“1st”，“2nd”，“3rd”，或者作为罗马数字“I”，“II”，“III”，“IV”的后缀输出值。
在格式化期间，获取并检查该值在有效范围内。 如果文本不可用于该值，则将其作为数字输出。 解析期间，解析器将与文本和数值的映射匹配。
field - 要追加的字段，不为null
textLookup - 从值到文本的地图
public DateTimeFormatterBuilder appendInstant()
实体具有固定的输出格式。 它们被转换为具有UTC的区域偏移量的日期时间，并使用标准ISO-8601格式进行格式化。 使用这种方法，根据需要格式化nano-of-second输出零，三，六或九位数字。 不使用本地化的十进制格式。
该时刻是使用INSTANT_SECONDS和可选（@code NANO_OF_SECOND）获得的。 INSTANT_SECONDS的值可能在INSTANT_SECONDS的最大范围LocalDateTime 。
resolver style对即时解析没有影响。 “24：00”的结束时间在第二天开始的半夜处理。 “ 23：59：59 ”的跨越时间在一定程度上处理，详见DateTimeFormatter.parsedLeapSecond() 。
该方法的替代方法是将该时间格式化/解析为单个时标值。 这是使用appendValue(INSTANT_SECONDS)实现的。
public DateTimeFormatterBuilder appendInstant(int fractionalDigits)
实体有一个固定的输出格式，虽然这个方法提供了对小数位数的一些控制。 它们被转换为具有UTC的区域偏移量的日期时间，并使用标准ISO-8601格式打印。 不使用本地化的十进制格式。
fractionalDigits参数允许控制fractionalDigits数秒的输出。 指定零将不会输出小数位数。 从1到9将输出越来越多的数字，如果需要，使用零右边填充。 特殊值-1用于输出尽可能多的数字，以避免任何尾随零。
当在严格模式下解析时，解析数字的数量必须与小数位数相匹配。 当在宽松模式下解析时，任意数目的从零到九的小数位都被接受。
该时刻是使用INSTANT_SECONDS和可选（@code NANO_OF_SECOND）获得的。 INSTANT_SECONDS的值可能在INSTANT_SECONDS的最大范围LocalDateTime 。
resolver style对即时解析没有影响。 “24：00”的结束时间在第二天开始的半夜处理。 “ 23：59：59 ”的跨越时间在一定程度上处理，详见DateTimeFormatter.parsedLeapSecond() 。
该方法的替代方法是将该时间格式化/解析为单个时标值。 这是使用appendValue(INSTANT_SECONDS)实现的。
fractionalDigits - 从0到9或-1的格式化的小数第二个数字的数量，以使用必要的数字
public DateTimeFormatterBuilder appendOffsetId()
这附加了一个指令来格式化/解析偏移ID到构建器。 这相当于呼叫appendOffset("HH:MM:ss", "Z") 。
public DateTimeFormatterBuilder appendOffset(String pattern, String noOffsetText)
这附加了一个指令来格式化/解析偏移ID到构建器。
在格式化期间，使用等效于使用TemporalQueries.offset()查询时间的机制获得偏移量。 它将使用下面定义的格式进行打印。 如果无法获得偏移量，则抛出异常，除非格式化程序的部分是可选的。
在解析期间，使用下面定义的格式解析偏移量。 如果无法解析偏移量，则抛出异常，除非格式化程序的部分是可选的。
偏移的格式由模式控制，模式必须是以下之一：
+HH - 小时，忽略分秒 +HHmm - 小时，分钟如果非零，忽略第二个，没有冒号 +HH:mm - 小时，分钟如果非零，忽略第二个，冒号 +HHMM - 小时和分钟，忽略第二，没有冒号 +HH:MM - 小时和分钟，忽略第二个，冒号 +HHMMss - 小时和分钟，第二个如果非零，没有冒号 +HH:MM:ss - 小时和分钟，第二个如果非零，用冒号 +HHMMSS - 小时，分钟和秒，没有冒号 +HH:MM:SS - 小时，分和秒，带冒号 pattern - 要使用的模式，不为空
noOffsetText - 偏移量为零时使用的文本，不为空
public DateTimeFormatterBuilder appendLocalizedOffset(TextStyle style)
这将附加一个本地化区域偏移量到构建器，本地化偏移量的格式由此方法指定的style 控制 ：
full - 具有本地化偏移量文本的格式，例如“GMT”，2位数小时和分钟字段，可选的第二个字段（如果不为零）和冒号。 short - 具有本地化偏移文本的格式，例如“GMT”，小时无前导零，可选的2位分秒，如果非零则为冒号。 在格式化期间，使用等效于使用TemporalQueries.offset()查询时间的机制获得偏移量。 如果无法获得偏移量，则抛出异常，除非格式化程序的部分是可选的。
在解析期间，使用上面定义的格式解析偏移量。 如果无法解析偏移量，则抛出异常，除非格式化程序的部分是可选的。
style - 要使用的格式样式，不为null
IllegalArgumentException - 如果样式既不是
full也不是
short
public DateTimeFormatterBuilder appendZoneId()
这附加了格式化/解析区域ID到构建器的指令。 区域ID以适合ZonedDateTime的严格方式获得。 相比之下， OffsetDateTime没有适合与此方法一起使用的区段ID，请参见appendZoneOrOffsetId() 。
在格式化期间，使用等效于使用TemporalQueries.zoneId()查询时间的机制获取区域 。 它将使用ZoneId.getId()的结果打印。 如果无法获取该区域，则抛出异常，除非格式化程序的部分是可选的。
在解析过程中，文本必须与已知区域或偏移量相匹配。 有两种类型的区域ID，基于偏移量，例如“+01：30”和基于区域的“欧洲/伦敦”。 这些被解析不同。 如果解析以“+”，“ - ”，“UT”，“UTC”或“GMT”开头，那么解析器将期望基于偏移的区域，并且将不匹配基于区域的区域。 偏移ID（例如'+02：30'）可能位于解析开头，或以“UT”，“UTC”或“GMT”为前缀。 偏移ID解析等效于使用参数 “HH：MM：ss”和no offset字符串'0'使用appendOffset(String, String) 。 如果解析以“UT”，“UTC”或“GMT”开头，并且解析器不能匹配以下偏移量ID，则选择ZoneOffset.UTC 。 在所有其他情况下，已知基于区域的区域列表用于查找最长可用匹配项。 如果没有找到匹配项，并且解析以“Z”开始，则选择ZoneOffset.UTC 。 解析器使用case sensitive设置。
例如，以下将解析：
"Europe/London" -- ZoneId.of("Europe/London")
"Z" -- ZoneOffset.UTC
"UT" -- ZoneId.of("UT")
"UTC" -- ZoneId.of("UTC")
"GMT" -- ZoneId.of("GMT")
"+01:30" -- ZoneOffset.of("+01:30")
"UT+01:30" -- ZoneOffset.of("+01:30")
"UTC+01:30" -- ZoneOffset.of("+01:30")
"GMT+01:30" -- ZoneOffset.of("+01:30")
appendZoneRegionId()
public DateTimeFormatterBuilder appendZoneRegionId()
ZoneOffset 。
这附加了格式化/解析区域ID的指令，只有它是基于区域的ID。
在格式化期间，使用等效于使用TemporalQueries.zoneId()查询时间的机制获取区域 。 如果该区域是ZoneOffset或者无法获取，则抛出异常，除非格式化程序的部分是可选的。 如果区域不是偏移，则区域将使用ZoneId.getId()中的区域ID进行打印。
在解析过程中，文本必须与已知区域或偏移量相匹配。 有两种类型的区域ID，基于偏移量，例如“+01：30”和基于区域的“欧洲/伦敦”。 这些被解析不同。 如果解析以“+”，“ - ”，“UT”，“UTC”或“GMT”开头，那么解析器将期望基于偏移的区域，并且将不匹配基于区域的区域。 偏移ID（例如'+02：30'）可能位于解析开头，或以“UT”，“UTC”或“GMT”为前缀。 偏移量ID解析等效于使用参数 “HH：MM：ss”和无偏移字符串'0'使用appendOffset(String, String) 。 如果解析以“UT”，“UTC”或“GMT”开头，并且解析器不能匹配以下偏移ID，则会选择ZoneOffset.UTC 。 在所有其他情况下，已知基于区域的区域列表用于查找最长可用匹配项。 如果没有找到匹配，并且解析以'Z'开始，则选择ZoneOffset.UTC 。 解析器使用case sensitive设置。
例如，以下将解析：
"Europe/London" -- ZoneId.of("Europe/London")
"Z" -- ZoneOffset.UTC
"UT" -- ZoneId.of("UT")
"UTC" -- ZoneId.of("UTC")
"GMT" -- ZoneId.of("GMT")
"+01:30" -- ZoneOffset.of("+01:30")
"UT+01:30" -- ZoneOffset.of("+01:30")
"UTC+01:30" -- ZoneOffset.of("+01:30")
"GMT+01:30" -- ZoneOffset.of("+01:30")
请注意，除了用于获取区域的appendZoneId()之外，该方法与appendZoneId()相同。 还要注意，解析接受偏移量，而格式化则不会产生偏移量。
appendZoneId()
public DateTimeFormatterBuilder appendZoneOrOffsetId()
这附加了一个指令来格式化/解析构建器的最佳可用区域或偏移量ID。 区域ID以宽松的方式获得，首先尝试找到真正的区域ID，例如ZonedDateTime ，然后尝试找到一个偏移量，如OffsetDateTime 。
在格式化期间，使用等效于使用TemporalQueries.zone()查询时间的机制获取区域 。 将使用ZoneId.getId()的结果打印。 如果无法获取该区域，则抛出异常，除非格式化程序的部分是可选的。
在解析过程中，文本必须与已知区域或偏移量相匹配。 有两种类型的区域ID，基于偏移量，例如“+01：30”和基于区域的“欧洲/伦敦”。 这些被解析不同。 如果解析以“+”，“ - ”，“UT”，“UTC”或“GMT”开头，那么解析器将期望基于偏移的区域，并且将不匹配基于区域的区域。 偏移ID（例如'+02：30'）可能位于解析开头，或以“UT”，“UTC”或“GMT”为前缀。 偏移量ID解析等效于使用参数 “HH：MM：ss”和no偏移字符串'0'使用appendOffset(String, String) 。 如果解析以“UT”，“UTC”或“GMT”开头，并且解析器不能匹配以下偏移量ID，则会选择ZoneOffset.UTC 。 在所有其他情况下，已知基于区域的区域列表用于查找最长可用匹配项。 如果没有找到匹配，并且解析以'Z'开始，则选择ZoneOffset.UTC 。 解析器使用case sensitive设置。
例如，以下将解析：
"Europe/London" -- ZoneId.of("Europe/London")
"Z" -- ZoneOffset.UTC
"UT" -- ZoneId.of("UT")
"UTC" -- ZoneId.of("UTC")
"GMT" -- ZoneId.of("GMT")
"+01:30" -- ZoneOffset.of("+01:30")
"UT+01:30" -- ZoneOffset.of("UT+01:30")
"UTC+01:30" -- ZoneOffset.of("UTC+01:30")
"GMT+01:30" -- ZoneOffset.of("GMT+01:30")
请注意，除了用于获取区域的appendZoneId()之外，此方法与appendZoneId()相同。
appendZoneId()
public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle)
这附加了一个指令，以将该区域的文本名称格式化/解析为构建器。
在格式化期间，使用等同于使用TemporalQueries.zoneId()查询时间的机制获得区域 。 如果该区域是ZoneOffset ，则使用ZoneOffset.getId()的结果进行打印 。 如果区域不是偏移量，文本名称将被查找在DateTimeFormatter中设置的区域设置。 如果正在打印的时间对象表示一个瞬间，则文本将适合于夏季或冬季时间文本。 如果查找文本找不到任何合适的重用 ，那么将打印ID 。 如果无法获取该区域，则抛出异常，除非格式化程序的部分是可选的。
在解析期间，文本区域名称，区域ID或偏移量被接受。 许多文字区域名称不是唯一的，例如CST可以用于“中央标准时间”和“中国标准时间”。 在这种情况下，区域ID将由格式的区域信息来确定locale和该区域的标准区域ID，例如，美国/纽约为美国东部区域。 在这种情况下， appendZoneText(TextStyle, Set)可用于指定一组首选的ZoneId。
textStyle - 要使用的文本样式，不为null
public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)
这附加了一个指令，以将该区域的文本名称格式化/解析为构建器。
在格式化期间，使用等效于使用TemporalQueries.zoneId()查询时间的机制获取区域 。 如果该区域是ZoneOffset ，则使用ZoneOffset.getId()的结果进行打印 。 如果区域不是偏移量，则文本名称将被查找在DateTimeFormatter中设置的区域设置。 如果正在打印的时间对象表示一个瞬间，则文本将适合于夏季或冬季时间文本。 如果查找文本找不到任何合适的重用 ，那么将打印ID 。 如果无法获取该区域，则抛出异常，除非格式化程序的部分是可选的。
在解析期间，文本区域名称，区域ID或偏移量被接受。 许多文字区域名称不是唯一的，例如CST可以用于“中央标准时间”和“中国标准时间”。 在这种情况下，区域ID将由来自格式化程序的locale的区域信息和该区域的标准区域ID（例如美国/纽约州美洲东部区域）确定。 这种方法也允许一组优选的ZoneId用于解析被指定。 如果要解析的纹理区域名称不唯一，将使用匹配的首选区域ID。 如果无法解析该区域，则抛出异常，除非格式化程序的部分是可选的。
textStyle - 要使用的文本样式，不为null
preferredZones - 首选区域ID的集合，不为null
public DateTimeFormatterBuilder appendChronologyId()
这附加了一个指令来格式化/解析编制ID到构建器。
在格式化期间，使用等同于使用TemporalQueries.chronology()查询时间的机制获得年表 。 将使用Chronology.getId()的结果打印。 如果不能获得年表，则抛出异常，除非格式化程序的部分是可选的。
在解析期间，年表被解析，必须符合Chronology.getAvailableChronologies()中的一个年表 。 如果不能解析年表，则抛出异常，除非格式化程序的部分是可选的。 解析器使用case sensitive设置。
public DateTimeFormatterBuilder appendChronologyText(TextStyle textStyle)
日历系统名称将在格式输出。 如果无法获得年表，则会抛出异常。 日历系统名称是从年表中获得的。
textStyle - 要使用的文本样式，不为null
public DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)
这将本地化部分附加到构建器，适用于输出日期，时间或日期时间组合。 基于四个项目，本地化部分的格式被懒惰地查找：
dateStyle dateStyle timeStyle timeStyle Locale的DateTimeFormatter Chronology ，选择最好的可用 DateTimeFormatter.withChronology(Chronology) 覆盖 。
在解析期间，如果已经解析了一个年表，那么它将被使用。 否则，使用默认值DateTimeFormatter.withChronology(Chronology) ，其中IsoChronology作为后备。
请注意，此方法提供了与DateFormat相似的DateFormat ，如DateFormat.getDateTimeInstance(int, int) 。
dateStyle - 要使用的日期样式，null表示不需要日期
timeStyle - 使用的时间风格，null表示不需要时间
IllegalArgumentException - 如果日期和时间样式都为空
public DateTimeFormatterBuilder appendLiteral(char literal)
此格式将输出此字符。
literal - 要附加的字面值，不为null
public DateTimeFormatterBuilder appendLiteral(String literal)
此字符串将在格式输出。
如果文字为空，则不会将任何内容添加到格式化程序中。
literal - 要附加的字面值，不为null
public DateTimeFormatterBuilder append(DateTimeFormatter formatter)
此方法与将格式化器的每个组成部分直接附加到此构建器具有相同的效果。
formatter - 要添加的格式化程序，不为null
public DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter)
该方法具有与每个组成部分直接附加到由optionalStart()和optionalEnd()包围的该构建器相同的效果。
如果数据可用于其中包含的所有字段，格式化程序将格式化。 如果字符串匹配，格式化程序将解析，否则返回错误。
formatter - 要添加的格式化程序，不为null
public DateTimeFormatterBuilder appendPattern(String pattern)
所有字母“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
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 week-of-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-am-pm (1-24) number 0
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
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
图案字母的数量决定了格式。 有关模式的用户关注描述，请参阅DateTimeFormatter 。 以下表格定义了图案字母如何映射到构建器。
日期字段 ：输出日期的模式字母。
Pattern Count Equivalent builder methods
------- ----- --------------------------
G 1 appendText(ChronoField.ERA, TextStyle.SHORT)
GG 2 appendText(ChronoField.ERA, TextStyle.SHORT)
GGG 3 appendText(ChronoField.ERA, TextStyle.SHORT)
GGGG 4 appendText(ChronoField.ERA, TextStyle.FULL)
GGGGG 5 appendText(ChronoField.ERA, TextStyle.NARROW)
u 1 appendValue(ChronoField.YEAR, 1, 19, SignStyle.NORMAL);
uu 2 appendValueReduced(ChronoField.YEAR, 2, 2000);
uuu 3 appendValue(ChronoField.YEAR, 3, 19, SignStyle.NORMAL);
u..u 4..n appendValue(ChronoField.YEAR, n, 19, SignStyle.EXCEEDS_PAD);
y 1 appendValue(ChronoField.YEAR_OF_ERA, 1, 19, SignStyle.NORMAL);
yy 2 appendValueReduced(ChronoField.YEAR_OF_ERA, 2, 2000);
yyy 3 appendValue(ChronoField.YEAR_OF_ERA, 3, 19, SignStyle.NORMAL);
y..y 4..n appendValue(ChronoField.YEAR_OF_ERA, n, 19, SignStyle.EXCEEDS_PAD);
Y 1 append special localized WeekFields element for numeric week-based-year
YY 2 append special localized WeekFields element for reduced numeric week-based-year 2 digits;
YYY 3 append special localized WeekFields element for numeric week-based-year (3, 19, SignStyle.NORMAL);
Y..Y 4..n append special localized WeekFields element for numeric week-based-year (n, 19, SignStyle.EXCEEDS_PAD);
Q 1 appendValue(IsoFields.QUARTER_OF_YEAR);
QQ 2 appendValue(IsoFields.QUARTER_OF_YEAR, 2);
QQQ 3 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT)
QQQQ 4 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL)
QQQQQ 5 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW)
q 1 appendValue(IsoFields.QUARTER_OF_YEAR);
qq 2 appendValue(IsoFields.QUARTER_OF_YEAR, 2);
qqq 3 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT_STANDALONE)
qqqq 4 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL_STANDALONE)
qqqqq 5 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW_STANDALONE)
M 1 appendValue(ChronoField.MONTH_OF_YEAR);
MM 2 appendValue(ChronoField.MONTH_OF_YEAR, 2);
MMM 3 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT)
MMMM 4 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL)
MMMMM 5 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW)
L 1 appendValue(ChronoField.MONTH_OF_YEAR);
LL 2 appendValue(ChronoField.MONTH_OF_YEAR, 2);
LLL 3 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT_STANDALONE)
LLLL 4 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL_STANDALONE)
LLLLL 5 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW_STANDALONE)
w 1 append special localized WeekFields element for numeric week-of-year
ww 1 append special localized WeekFields element for numeric week-of-year, zero-padded
W 1 append special localized WeekFields element for numeric week-of-month
d 1 appendValue(ChronoField.DAY_OF_MONTH)
dd 2 appendValue(ChronoField.DAY_OF_MONTH, 2)
D 1 appendValue(ChronoField.DAY_OF_YEAR)
DD 2 appendValue(ChronoField.DAY_OF_YEAR, 2)
DDD 3 appendValue(ChronoField.DAY_OF_YEAR, 3)
F 1 appendValue(ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH)
E 1 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
EE 2 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
EEE 3 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
EEEE 4 appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
EEEEE 5 appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
e 1 append special localized WeekFields element for numeric day-of-week
ee 2 append special localized WeekFields element for numeric day-of-week, zero-padded
eee 3 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT)
eeee 4 appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL)
eeeee 5 appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW)
c 1 append special localized WeekFields element for numeric day-of-week
ccc 3 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT_STANDALONE)
cccc 4 appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL_STANDALONE)
ccccc 5 appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW_STANDALONE)
时间字段 ：输出时间的模式字母。
Pattern Count Equivalent builder methods
------- ----- --------------------------
a 1 appendText(ChronoField.AMPM_OF_DAY, TextStyle.SHORT)
h 1 appendValue(ChronoField.CLOCK_HOUR_OF_AMPM)
hh 2 appendValue(ChronoField.CLOCK_HOUR_OF_AMPM, 2)
H 1 appendValue(ChronoField.HOUR_OF_DAY)
HH 2 appendValue(ChronoField.HOUR_OF_DAY, 2)
k 1 appendValue(ChronoField.CLOCK_HOUR_OF_DAY)
kk 2 appendValue(ChronoField.CLOCK_HOUR_OF_DAY, 2)
K 1 appendValue(ChronoField.HOUR_OF_AMPM)
KK 2 appendValue(ChronoField.HOUR_OF_AMPM, 2)
m 1 appendValue(ChronoField.MINUTE_OF_HOUR)
mm 2 appendValue(ChronoField.MINUTE_OF_HOUR, 2)
s 1 appendValue(ChronoField.SECOND_OF_MINUTE)
ss 2 appendValue(ChronoField.SECOND_OF_MINUTE, 2)
S..S 1..n appendFraction(ChronoField.NANO_OF_SECOND, n, n, false)
A 1 appendValue(ChronoField.MILLI_OF_DAY)
A..A 2..n appendValue(ChronoField.MILLI_OF_DAY, n)
n 1 appendValue(ChronoField.NANO_OF_SECOND)
n..n 2..n appendValue(ChronoField.NANO_OF_SECOND, n)
N 1 appendValue(ChronoField.NANO_OF_DAY)
N..N 2..n appendValue(ChronoField.NANO_OF_DAY, n)
区域ID ：要输出的模式字母ZoneId 。
Pattern Count Equivalent builder methods
------- ----- --------------------------
VV 2 appendZoneId()
z 1 appendZoneText(TextStyle.SHORT)
zz 2 appendZoneText(TextStyle.SHORT)
zzz 3 appendZoneText(TextStyle.SHORT)
zzzz 4 appendZoneText(TextStyle.FULL)
区域偏移 ：要输出的模式字母ZoneOffset 。
Pattern Count Equivalent builder methods
------- ----- --------------------------
O 1 appendLocalizedOffsetPrefixed(TextStyle.SHORT);
OOOO 4 appendLocalizedOffsetPrefixed(TextStyle.FULL);
X 1 appendOffset("+HHmm","Z")
XX 2 appendOffset("+HHMM","Z")
XXX 3 appendOffset("+HH:MM","Z")
XXXX 4 appendOffset("+HHMMss","Z")
XXXXX 5 appendOffset("+HH:MM:ss","Z")
x 1 appendOffset("+HHmm","+00")
xx 2 appendOffset("+HHMM","+0000")
xxx 3 appendOffset("+HH:MM","+00:00")
xxxx 4 appendOffset("+HHMMss","+0000")
xxxxx 5 appendOffset("+HH:MM:ss","+00:00")
Z 1 appendOffset("+HHMM","+0000")
ZZ 2 appendOffset("+HHMM","+0000")
ZZZ 3 appendOffset("+HHMM","+0000")
ZZZZ 4 appendLocalizedOffset(TextStyle.FULL);
ZZZZZ 5 appendOffset("+HH:MM:ss","Z")
修饰符 ：修改模式的其余部分的模式字母：
Pattern Count Equivalent builder methods
------- ----- --------------------------
[ 1 optionalStart()
] 1 optionalEnd()
p..p 1..n padNext(n)
任何未指定的字母序列，无法识别的字母或保留字符都将抛出异常。 未来版本可能会增加一组模式。 建议对要直接输出的所有字符使用单引号，以确保将来的更改不会破坏您的应用程序。
请注意，模式字符串与SimpleDateFormat类似，但不完全相同 。 模式字符串与Unicode Common Locale Data Repository（CLDR / LDML）定义的模式字符串也类似，但不完全相同。 图案字母'X'和'u'与Unicode CLDR / LDML对齐。 相比之下， SimpleDateFormat使用'u'作为星期几的数字。 模式字母'y'和'Y'分解两位数字，多于4位数字不同。 模式字母'n'，'A'，'N'和'p'。 数字类型将拒绝大量数字。
pattern - 要添加的模式，不为null
IllegalArgumentException - 如果模式无效
public DateTimeFormatterBuilder padNext(int padWidth)
这个填充将使用空格填充到固定的宽度。
格式化时，装饰元素将被输出，然后填充到指定的宽度。 如果超出了焊盘宽度，则在格式化期间将抛出异常。
在解析期间，填充和修饰的元素将被解析。 如果解析是宽松的，那么焊盘宽度被视为最大值。 如果解析不区分大小写，则pad字符匹配忽略大小写。 填充被贪婪地解析。 因此，如果装饰元素以pad字符开头，则不会被解析。
padWidth - 垫宽度，1或更大
IllegalArgumentException - 如果垫宽度太小
public DateTimeFormatterBuilder padNext(int padWidth, char padChar)
此填充用于除零填充之外的填充。 应使用appendValue方法实现零填充。
格式化时，装饰元素将被输出，然后填充到指定的宽度。 如果超出了焊盘宽度，则在格式化期间将抛出异常。
在解析期间，填充和修饰的元素将被解析。 如果解析是宽松的，那么焊盘宽度被视为最大值。 如果解析不区分大小写，则pad字符匹配忽略大小写。 填充被贪婪地解析。 因此，如果装饰元素以pad字符开头，则不会被解析。
padWidth - 垫宽度，1或更大
padChar - 垫字符
IllegalArgumentException - 如果垫宽度太小
public DateTimeFormatterBuilder optionalStart()
格式化的输出可以包括可以嵌套的可选部分。 通过调用此方法启动可选部分，并通过调用optionalEnd()或通过结束构建过程结束。
可选部分中的所有元素都被视为可选的。 在格式化期间，只有TemporalAccessor中有关该TemporalAccessor中所有元素的数据可用时，才会输出该部分。 在解析期间，整个部分可能从解析的字符串中丢失。
例如，考虑一个构建器设置为builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2) 。 可选部分自动结束在构建器的末尾。 在格式化期间，只有当它的值可以从日期时间获得时，分钟才会被输出。 在解析期间，无论分钟是否存在，输入将被成功解析。
public DateTimeFormatterBuilder optionalEnd()
格式化的输出可以包括可以嵌套的可选部分。 通过调用optionalStart()启动可选部分，并使用此方法（或构建器的末尾）结束。
调用此方法而不会先前称为optionalStart将抛出异常。 在调用optionalStart之后optionalStart调用此方法对optionalStart程序没有影响，而不是结束（空）可选部分。
可选部分中的所有元素都被视为可选的。 在格式化期间，只有TemporalAccessor中有关该TemporalAccessor中所有元素的数据可用时，才会输出该部分。 在解析期间，整个部分可能从解析的字符串中丢失。
例如，考虑一个构建器设置为builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2).optionalEnd() 。 在格式化期间，只有当它的值可以从日期时间获得时，分钟才会被输出。 在解析期间，无论分钟是否存在，输入将被成功解析。
IllegalStateException - 如果以前没有拨打
optionalStart
public DateTimeFormatter toFormatter()
DateTimeFormatter来完成此构建器。
这将创建一个格式化程序与default FORMAT locale 。 将使用标准的DecimalStyle打印和解析数字。 解析器样式将为SMART 。
调用此方法将在创建格式化程序之前重复调用optionalEnd()来终止任何打开的可选部分。
如果需要，该构建器仍然可以在创建格式化程序后使用，尽管可能已通过调用optionalEnd更改了状态。
public DateTimeFormatter toFormatter(Locale locale)
DateTimeFormatter来完成此构建器。
这将创建一个具有指定区域设置的格式化程序。 将使用标准的DecimalStyle打印和解析数字。 解析器样式将为SMART 。
调用此方法将在创建格式化程序之前重复调用optionalEnd()来结束任何打开的可选部分。
如果需要，此构建器仍然可以在创建格式化程序后使用，尽管状态可能已通过调用更改为optionalEnd 。
locale - 用于格式化的区域设置，不为空
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.