java.lang.Object

java.time.format.DateTimeFormatterBuilder

public final class DateTimeFormatterBuilder extends Object

用于创建日期时间格式化程序的构建器。

这允许创建一个DateTimeFormatter。所有日期时间格式化程序最终都是使用此构建器创建的。

可以添加日期时间的基本元素：

Value - 数值
Fraction - 包括小数点的分数值。始终在输出分数时使用此选项，以确保正确解析分数
Text - 值的文本等效物
OffsetId/Offset - 区偏移
ZoneId - 时区 id
ZoneText - 时区的名称
ChronologyId - 年表 id
ChronologyText - 年表的名称
Literal - 文本文字
Nested and Optional - 格式可以嵌套或设为可选

此外，任何元素都可以通过填充进行装饰，可以是空格或任何其他字符。

最后，可以使用简写模式，与java.text.SimpleDateFormat SimpleDateFormat大部分兼容，参见appendPattern(String)。实际上，这只是解析模式并在构建器上调用其他方法。

实现要求：: 此类是可变构建器，旨在从单个线程中使用。
自：: 1.8

Constructor Summary

Constructors

Constructor

Description

DateTimeFormatterBuilder()

构造构建器的新实例。
Method Summary

Modifier and Type

Method

Description

DateTimeFormatterBuilder

append(DateTimeFormatter formatter)

将格式化程序的所有元素附加到构建器。

DateTimeFormatterBuilder

appendChronologyId()

将年表 ID，例如 'ISO' 或 '泰国佛历'，附加到格式化程序。

DateTimeFormatterBuilder

appendChronologyText(TextStyle textStyle)

将年表名称附加到格式化程序。

DateTimeFormatterBuilder

appendDayPeriodText(TextStyle style)

将日期时间段文本附加到格式化程序。

DateTimeFormatterBuilder

appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)

将日期时间字段的分数值附加到格式化程序。

DateTimeFormatterBuilder

appendGenericZoneText(TextStyle textStyle)

将通用时区名称，例如 '太平洋时间'，附加到格式化程序。

DateTimeFormatterBuilder

appendGenericZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)

将通用时区名称，例如 '太平洋时间'，附加到格式化程序。

DateTimeFormatterBuilder

appendInstant()

使用ISO-8601附加一个瞬时时间到格式化程序，以三位一组格式化小数位数。

DateTimeFormatterBuilder

appendInstant(int fractionalDigits)

使用ISO-8601附加一个瞬时时间到格式化程序，控制小数位数。

DateTimeFormatterBuilder

appendLiteral(char literal)

将字符文字附加到格式化程序。

DateTimeFormatterBuilder

appendLiteral(String literal)

将字符串文字附加到格式化程序。

DateTimeFormatterBuilder

appendLocalized(String requestedTemplate)

使用请求的模板将本地化模式附加到格式化程序。

DateTimeFormatterBuilder

appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)

将本地化日期时间模式附加到格式化程序。

DateTimeFormatterBuilder

appendLocalizedOffset(TextStyle style)

将本地化区偏移，例如 'GMT+01:00'，附加到格式化程序。

DateTimeFormatterBuilder

appendOffset(String pattern, String noOffsetText)

将区偏移，例如 '+01:00'，附加到格式化程序。

DateTimeFormatterBuilder

appendOffsetId()

将区偏移，例如 '+01:00'，附加到格式化程序。

DateTimeFormatterBuilder

appendOptional(DateTimeFormatter formatter)

将可选格式化程序附加到构建器，可选择格式化/解析。

DateTimeFormatterBuilder

appendPattern(String pattern)

将由指定模式定义的元素附加到构建器。

DateTimeFormatterBuilder

appendText(TemporalField field)

使用全文本样式将日期时间字段的文本附加到格式化程序。

DateTimeFormatterBuilder

appendText(TemporalField field, TextStyle textStyle)

将日期时间字段的文本附加到格式化程序。

DateTimeFormatterBuilder

appendText(TemporalField field, Map<Long,String> textLookup)

使用指定映射提供文本的方式将日期时间字段的文本附加到格式化程序。

DateTimeFormatterBuilder

appendValue(TemporalField field)

使用正常输出样式将日期时间字段的值附加到格式化程序。

DateTimeFormatterBuilder

appendValue(TemporalField field, int width)

使用固定宽度、零填充方法将日期时间字段的值附加到格式化程序。

DateTimeFormatterBuilder

appendValue(TemporalField field, int minWidth, int maxWidth, SignStyle signStyle)

提供完全控制格式的方式将日期时间字段的值附加到格式化程序。

DateTimeFormatterBuilder

appendValueReduced(TemporalField field, int width, int maxWidth, int baseValue)

将日期时间字段的简化值附加到格式化程序。

DateTimeFormatterBuilder

appendValueReduced(TemporalField field, int width, int maxWidth, ChronoLocalDate baseDate)

将日期时间字段的简化值附加到格式化程序。

DateTimeFormatterBuilder

appendZoneId()

将时区 ID，例如 '欧洲/巴黎' 或 '+02:00'，附加到格式化程序。

DateTimeFormatterBuilder

appendZoneOrOffsetId()

将时区 ID，例如 '欧洲/巴黎' 或 '+02:00'，附加到格式化程序，使用最佳可用的区域 ID。

DateTimeFormatterBuilder

appendZoneRegionId()

将时区区域 ID，例如 '欧洲/巴黎'，附加到格式化程序，如果是ZoneOffset，则拒绝区域 ID。

DateTimeFormatterBuilder

appendZoneText(TextStyle textStyle)

将时区名称，例如 '英国夏令时间'，附加到格式化程序。

DateTimeFormatterBuilder

appendZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)

将时区名称，例如 '英国夏令时间'，附加到格式化程序。

static String

getLocalizedDateTimePattern(String requestedTemplate, Chronology chrono, Locale locale)

返回区域和年表的请求模板的格式化模式。

static String

getLocalizedDateTimePattern(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale)

获取区域和年表的日期和时间样式的格式化模式。

DateTimeFormatterBuilder

optionalEnd()

结束可选部分。

DateTimeFormatterBuilder

optionalStart()

标记可选部分的开始。

DateTimeFormatterBuilder

padNext(int padWidth)

导致下一个添加的打印机/解析器使用空格填充到固定宽度。

DateTimeFormatterBuilder

padNext(int padWidth, char padChar)

导致下一个添加的打印机/解析器使用固定宽度填充。

DateTimeFormatterBuilder

parseCaseInsensitive()

更改解析样式为在格式化程序的其余部分中不区分大小写。

DateTimeFormatterBuilder

parseCaseSensitive()

更改解析样式为在格式化程序的其余部分中区分大小写。

DateTimeFormatterBuilder

parseDefaulting(TemporalField field, long value)

为字段添加默认值以供解析时使用。

DateTimeFormatterBuilder

parseLenient()

更改解析样式为在格式化程序的其余部分中宽松。

DateTimeFormatterBuilder

parseStrict()

更改解析样式为在格式化程序的其余部分中严格。

DateTimeFormatter

toFormatter()

通过使用默认区域设置创建DateTimeFormatter来完成此构建器。

DateTimeFormatter

toFormatter(Locale locale)

通过使用指定的区域设置创建DateTimeFormatter来完成此构建器。

Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- DateTimeFormatterBuilder
  
  public DateTimeFormatterBuilder()
  
  构造构建器的新实例。
Method Details
- getLocalizedDateTimePattern
  
  public static String getLocalizedDateTimePattern(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale)
  
  获取区域和年表的日期和时间样式的格式化模式。使用区域和年表来查找请求的日期样式和/或时间样式的区域特定格式。
  如果区域包含"rg"（区域覆盖）Unicode扩展，则格式化模式将被适当地覆盖，以适合该区域。
  
  参数：
  
  dateStyle - 日期的FormatStyle，仅用于时间模式
  
  timeStyle - 时间的FormatStyle，仅用于日期模式
  
  chrono - 年表，非空
  
  locale - 区域，非空
  
  返回：
  
  区域和年表特定的格式化模式
  
  抛出：
  
  IllegalArgumentException - 如果日期样式和时间样式都为null
- getLocalizedDateTimePattern
  
  public static String getLocalizedDateTimePattern(String requestedTemplate, Chronology chrono, Locale locale)
  
  获取区域和年表的请求模板的格式化模式。使用区域和年表来查找请求模板的区域特定格式。
  如果区域包含"rg"（区域覆盖）Unicode扩展，则格式化模式将被适当地覆盖，以适合该区域。
  
  有关requestedTemplate参数的详细信息，请参阅appendLocalized(String)。
  参数：
  
  requestedTemplate - 请求的模板，非null
  
  chrono - 年表，非空
  
  locale - 区域，非空
  
  返回：
  
  区域和年表特定的格式化模式
  
  抛出：
  
  IllegalArgumentException - 如果requestedTemplate不匹配appendLocalized(String)中描述的正则表达式语法。
  
  DateTimeException - 如果无法找到requestedTemplate的本地化模式的匹配项
  
  自：
  
  19
  
  参见：
  
  appendLocalized(String)
- parseCaseSensitive
  
  public DateTimeFormatterBuilder parseCaseSensitive()
  
  更改解析样式为在格式化程序的其余部分中区分大小写。
  解析可以是区分大小写或不区分大小写 - 默认情况下是区分大小写的。此方法允许更改解析的区分大小写设置。
  
  调用此方法会更改构建器的状态，使得所有后续的构建器方法调用将在区分大小写模式下解析文本。有关相反设置，请参见parseCaseInsensitive()。解析区分大小写/不区分大小写的方法可以在构建器的任何点调用，因此解析器可以在解析过程中多次在区分大小写模式之间切换。
  
  由于默认是区分大小写的，因此应在之前调用#parseCaseInsensitive后才应使用此方法。
  
  返回：
  
  this，用于链接，非null
- parseCaseInsensitive
  
  public DateTimeFormatterBuilder parseCaseInsensitive()
  
  更改解析样式为在格式化程序的其余部分中不区分大小写。
  解析可以是区分大小写或不区分大小写 - 默认情况下是区分大小写的。此方法允许更改解析的区分大小写设置。
  
  调用此方法会更改构建器的状态，使得所有后续的构建器方法调用将在不区分大小写模式下解析文本。有关相反设置，请参见parseCaseSensitive()。解析区分大小写/不区分大小写的方法可以在构建器的任何点调用，因此解析器可以在解析过程中多次在区分大小写模式之间切换。
  
  返回：
  
  this，用于链接，非null
- parseStrict
  
  public DateTimeFormatterBuilder parseStrict()
  
  更改解析样式为在格式化程序的其余部分中严格。
  解析可以是严格或宽松 - 默认情况下是严格的。这控制匹配文本和符号样式的灵活程度。
  
  使用时，此方法会从此点开始更改解析为严格。由于默认是严格的，因此通常只需要在调用parseLenient()之后才需要此方法。更改将保持有效，直到最终构建的格式化程序结束或调用parseLenient为止。
  
  返回：
  
  this，用于链接，非null
- parseLenient
  
  public DateTimeFormatterBuilder parseLenient()
  
  将解析样式更改为在格式化程序的其余部分中为宽松模式。请注意，区分大小写是单独设置的。
  解析可以是严格的或宽松的 - 默认情况下是严格的。这控制匹配文本和符号样式的灵活程度。调用此方法的应用程序通常还应调用parseCaseInsensitive()。
  
  使用时，此方法会从此处开始将解析更改为宽松模式。更改将持续到最终构建的格式化程序结束，或者直到调用parseStrict为止。
  
  返回：
  
  this，用于链接，不为null
- parseDefaulting
  
  public DateTimeFormatterBuilder parseDefaulting(TemporalField field, long value)
  
  为字段附加默认值以供解析使用。
  这向构建器附加了一条指令，将默认值注入解析结果中。这在与格式化程序的可选部分一起使用时特别有用。
  
  例如，考虑一个解析年份，后跟可选月份，再后跟可选日期的格式化程序。使用这样的格式化程序将要求调用代码检查是否已解析了完整日期、年月或只是年份。此方法可用于将月份和日期默认为合理值，例如月份的第一天，从而使调用代码始终能够获得日期。
  
  在格式化期间，此方法不起作用。
  
  在解析期间，会检查解析的当前状态。如果指定的字段没有关联值，因为在那一点上尚未成功解析它，则指定的值将被注入到解析结果中。注入是即时的，因此字段-值对将对格式化程序中的任何后续元素可见。因此，通常在构建器的末尾调用此方法。
  
  参数：
  
  field - 要默认值的字段，不为null
  
  value - 要将字段默认为的值
  
  返回：
  
  this，用于链接，不为null
- appendValue
  
  public DateTimeFormatterBuilder appendValue(TemporalField field)
  
  将日期时间字段的值附加到格式化程序，使用普通的输出样式。
  在格式化期间，字段的值将被输出。如果无法获取该值，则将抛出异常。
  
  该值将按照整数值的正常格式进行打印。只有负数将被签名。不会添加填充。
  
  对于诸如此类的可变宽度值的解析器通常会贪婪地行事，需要一个数字，但接受尽可能多的数字。此行为可能会受到“相邻值解析”的影响。有关详细信息，请参见appendValue(java.time.temporal.TemporalField, int)。
  
  参数：
  
  field - 要附加的字段，不为null
  
  返回：
  
  this，用于链接，不为null
- appendValue
  
  public DateTimeFormatterBuilder appendValue(TemporalField field, int width)
  
  将日期时间字段的值附加到格式化程序，使用固定宽度、零填充的方法。
  在格式化期间，字段的值将被输出。如果无法获取该值，则将抛出异常。
  
  该值将在左侧进行零填充。如果值的大小意味着无法在宽度内打印，则会抛出异常。如果字段的值为负，则在格式化期间将抛出异常。
  
  此方法支持一种称为“相邻值解析”的特殊解析技术。此技术解决了一个问题，即一个值，可变宽度或固定宽度，后面跟着一个或多个固定长度值。标准解析器是贪婪的，因此通常会窃取固定宽度值解析器所需的数字，这些解析器跟在可变宽度值解析器之后。
  
  不需要采取任何措施来启动“相邻值解析”。当调用appendValue时，构建器将进入相邻值解析设置模式。如果紧随其后的方法调用或同一构建器上的方法调用是为了固定宽度值，则解析器将保留空间，以便可以解析固定宽度值。
  
  例如，考虑builder.appendValue(YEAR).appendValue(MONTH_OF_YEAR, 2); 年份是一个1到19位数字之间的可变宽度解析。月份是一个2位数字的固定宽度解析。因为它们是立即相继附加到同一个构建器上的，年份解析器将为月份解析保留两位数字。因此，文本“201106”将正确解析为2011年和6月。如果没有相邻值解析，年份将贪婪地解析所有六位数字，不留任何内容给月份。
  
  相邻值解析适用于解析器中每组固定宽度非负值，这些值紧随任何类型的值，无论是变宽度还是固定宽度。调用任何其他附加方法将结束相邻值解析的设置。因此，如果您需要避免相邻值解析行为，只需将appendValue添加到另一个DateTimeFormatterBuilder中，并将其添加到此构建器中。
  
  如果激活了相邻解析，则在严格和宽松模式下，解析必须完全匹配指定数量的数字。此外，不允许有正负号。
  
  参数：
  
  field - 要附加的字段，不为null
  
  width - 打印字段的宽度，从1到19
  
  返回：
  
  this，用于链接，不为null
  
  抛出：
  
  IllegalArgumentException - 如果宽度无效
- appendValue
  
  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 - 正/负输出样式，不为null
  
  返回：
  
  this，用于链接，不为null
  
  抛出：
  
  IllegalArgumentException - 如果宽度无效
- appendValueReduced
  
  public DateTimeFormatterBuilder appendValueReduced(TemporalField field, int width, int maxWidth, int baseValue)
  
  将日期时间字段的减少值附加到格式化程序。
  由于诸如年份之类的字段因年表而异，建议在大多数情况下使用appendValueReduced(java.time.temporal.TemporalField, int, int, ChronoLocalDate)此方法的日期}变体。此变体适用于简单字段或仅使用ISO年表的情况。
  
  对于格式化，将使用width和maxWidth来确定要格式化的字符数。如果它们相等，则格式是固定宽度的。如果字段的值在使用width字符的baseValue范围内，则将格式化减少的值，否则将截断值以适应maxWidth。右侧的字符将输出以匹配宽度，左侧填充为零。
  
  对于严格解析，将解析允许的字符数为width到maxWidth。对于宽松解析，字符数必须至少为1，但不超过10。如果解析的数字数量等于width且值为正，则字段值将被计算为大于或等于具有相同最低有效字符的baseValue的第一个数字，否则解析的值为字段值。这允许在基值和宽度范围内输入减少的值，并且绝对值可以用于超出范围的值。
  
  例如，基值为1980，宽度为2将具有从1980到2079的有效值。在解析期间，文本"12"将导致值2012，因为这是在最后两个字符为“12”的范围内的值。相比之下，解析文本"1915"将导致值1915。
  
  参数：
  
  field - 要附加的字段，不为null
  
  width - 要打印和解析的字段宽度，从1到10
  
  maxWidth - 要打印字段的最大宽度，从1到10
  
  baseValue - 有效值范围的基本值
  
  返回：
  
  this，用于链接，不为null
  
  抛出：
  
  IllegalArgumentException - 如果宽度或基本值无效
- appendValueReduced
  
  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用于确定要格式化的字符数。如果它们相等，则格式是固定宽度的。如果字段的值在使用width字符的baseValue范围内，则将格式化减少的值，否则将截断值以适应maxWidth。右侧字符将输出以匹配宽度，左侧填充为零。
  
  对于严格解析，允许由width到maxWidth允许的字符数进行解析。对于宽松解析，解析的数字字符数必须至少为1且小于10。如果解析的数字位数等于width且值为正，则字段值将计算为大于或等于具有相同最低有效字符的baseValue的第一个数字，否则解析的值为字段值。这允许在基准值和宽度范围内输入减少的值，并且可以为范围外的值输入绝对值。
  
  例如，基准值为1980，宽度为2将具有从1980到2079的有效值。在解析期间，文本"12"将导致值2012，因为这是范围内的值，最后两个字符为"12"。相比之下，解析文本"1915"将导致值1915。
  
  参数:
  
  field - 要附加的字段，不能为空
  
  width - 打印和解析字段的字段宽度，从1到10
  
  maxWidth - 打印字段的最大字段宽度，从1到10
  
  baseDate - 用于计算解析年表中有效值范围的基准日期，不能为空
  
  返回:
  
  this，用于链接，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果宽度或基准值无效
- appendFraction
  
  public DateTimeFormatterBuilder appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)
  
  将日期时间字段的分数值附加到格式化程序中。
  字段的分数值将被输出，包括前导小数点。前面的值不会被输出。例如，15秒将被输出为.25。
  
  可以控制打印分数的宽度。将最小宽度设置为零将导致不生成任何输出。打印的分数将在最小宽度和最大宽度之间必要的最小宽度 - 尾随零将被省略。由于最大宽度，不会发生四舍五入 - 数字将被简单地丢弃。
  
  在严格模式下解析时，解析的数字位数必须在最小宽度和最大宽度之间。在严格模式下，如果最小宽度和最大宽度相等且没有小数点，则解析器将参与相邻值解析，请参见appendValue(java.time.temporal.TemporalField, int)。在宽松模式下解析时，最小宽度被视为零，最大宽度为九。
  
  如果无法获取值，则将抛出异常。如果值为负数，则将抛出异常。如果字段没有固定的有效值集，则将抛出异常。如果要打印的日期时间中的字段值超出有效值范围，则将抛出异常。
  
  参数:
  
  field - 要附加的字段，不能为空
  
  minWidth - 不包括小数点的字段的最小宽度，从0到9
  
  maxWidth - 不包括小数点的字段的最大宽度，从1到9
  
  decimalPoint - 是否输出本地化的小数点符号
  
  返回:
  
  this，用于链接，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果字段具有可变的有效值集或任一宽度无效
- appendText
  
  public DateTimeFormatterBuilder appendText(TemporalField field)
  
  使用全文本样式将日期时间字段的文本附加到格式化程序中。
  在格式化期间将输出字段的文本。该值必须在字段的有效范围内。如果无法获取值，则将抛出异常。如果字段没有文本表示，则将使用数值值。
  
  该值将按照整数值的正常格式打印。只有负数将被签名。不会添加填充。
  
  参数:
  
  field - 要附加的字段，不能为空
  
  返回:
  
  this，用于链接，不能为空
- appendText
  
  public DateTimeFormatterBuilder appendText(TemporalField field, TextStyle textStyle)
  
  将日期时间字段的文本附加到格式化程序中。
  在格式化期间将输出字段的文本。该值必须在字段的有效范围内。如果无法获取值，则将抛出异常。如果字段没有文本表示，则将使用数值值。
  
  该值将按照整数值的正常格式打印。只有负数将被签名。不会添加填充。
  
  参数:
  
  field - 要附加的字段，不能为空
  
  textStyle - 要使用的文本样式，不能为空
  
  返回:
  
  this，用于链接，不能为空
- appendText
  
  public DateTimeFormatterBuilder appendText(TemporalField field, Map<Long,String> textLookup)
  使用指定的映射将日期时间字段的文本附加到格式化程序中。
  标准文本输出方法使用JDK中的本地化文本。此方法允许直接指定该文本。生成的映射不会被构建器验证以确保格式化或解析是可能的，因此无效的映射可能会在后续使用中引发错误。
  
  提供文本映射在格式化和解析方面提供了相当大的灵活性。例如，传统应用程序可能需要或提供年份的月份为"JNY"、"FBY"、"MCH"等。这些不匹配本地化月份名称的标准文本集。使用此方法，可以创建一个定义每个值与文本之间连接的映射：
  
  Map<Long, String> map = new HashMap<>(); map.put(1L, "JNY"); map.put(2L, "FBY"); map.put(3L, "MCH"); ... builder.appendText(MONTH_OF_YEAR, map);
  
  其他用途可能是以后缀形式输出值，例如"1st"、"2nd"、"3rd"，或者作为罗马数字"I"、"II"、"III"、"IV"。
  
  在格式化期间，将获取值并检查其是否在有效范围内。如果值的文本不可用，则将其作为数字输出。在解析期间，解析器将与文本和数字值的映射进行匹配。
  参数:
  
  field - 要附加的字段，不能为空
  
  textLookup - 从值到文本的映射
  
  返回:
  
  this，用于链接，不能为空
- appendInstant
  
  public DateTimeFormatterBuilder appendInstant()
  
  使用ISO-8601将瞬时值附加到格式化程序中，以三位一组格式化小数位。
  瞬时值具有固定的输出格式。它们将转换为具有UTC区偏移的日期时间，并使用标准的ISO-8601格式进行格式化。使用此方法，格式化纳秒输出零、三、六或九位数字。不使用本地化的小数样式。
  
  将使用INSTANT_SECONDS和可选的NANO_OF_SECOND来获取瞬时值。 INSTANT_SECONDS的值可能超出LocalDateTime的最大范围。
  
  解析样式对瞬时解析没有影响。'24:00'的结束时间将被处理为紧随其后的第二天的午夜。'23:59:59'的闰秒时间将在一定程度上处理，详细信息请参见DateTimeFormatter.parsedLeapSecond()。
  
  在格式化时，瞬时值将始终以'Z'作为后缀表示UTC。在解析时，将使用appendOffsetId()的行为来解析偏移量，必要时将瞬时值转换为UTC。
  
  此方法的替代方法是将瞬时值格式化/解析为单个时代秒值。这可以通过使用appendValue(INSTANT_SECONDS)来实现。
  
  返回:
  
  this，用于链接，不能为空
- appendInstant
  
  public DateTimeFormatterBuilder appendInstant(int fractionalDigits)
  
  追加使用ISO-8601格式的即时时间到格式化程序，可以控制小数位数。
  即时时间具有固定的输出格式，尽管此方法可以控制小数位数。它们被转换为带有UTC区偏移的日期时间，并使用标准的ISO-8601格式进行打印。不使用本地化的小数样式。
  
  fractionalDigits参数允许控制输出的小数秒数。指定为零将导致不输出小数位。从1到9将输出逐渐增加的数字，必要时使用零进行右填充。特殊值-1用于输出足够避免任何尾随零的数字。
  
  在严格模式下解析时，解析的数字位数必须与小数位数匹配。在宽松模式下解析时，接受从零到九个小数位数的任意数量。
  
  即时时间是使用INSTANT_SECONDS和可选的NANO_OF_SECOND获得的。 INSTANT_SECONDS的值可能超出LocalDateTime的最大范围。
  
  解析样式对即时时间解析没有影响。'24:00'的结束时间被处理为第二天开始的午夜。'23:59:60'的闰秒时间在一定程度上被处理，详细信息请参见DateTimeFormatter.parsedLeapSecond()。
  appendValue(INSTANT_SECONDS)来实现。
  
  参数:
  
  fractionalDigits - 要格式化的小数秒位数，从0到9，或-1表示使用必要的位数
  
  返回:
  
  this，用于链接，不为null
  
  抛出:
  
  IllegalArgumentException - 如果小数位数无效
- appendOffsetId
  
  public DateTimeFormatterBuilder appendOffsetId()
  
  追加区偏移，例如'+01:00'，到格式化程序。 appendOffset("+HH:mm:ss", "Z")。有关格式化和解析的详细信息，请参见 appendOffset(String, String)。
  
  返回:
  
  this，用于链接，不为null
- appendOffset
  
  public DateTimeFormatterBuilder appendOffset(String pattern, String noOffsetText)
  追加区偏移，例如'+01:00'，到格式化程序。 TemporalQueries.offset()的时间查询机制获得的。它将使用下面定义的格式进行打印。如果无法获取偏移，则会抛出异常，除非格式化程序的部分是可选的。
  
  +HH - 仅小时，忽略分钟和秒
  
  +HHmm - 小时，如果非零则带有分钟，忽略秒，无冒号
  
  +HH:mm - 小时，如果非零则带有分钟，忽略秒，有冒号
  
  +HHMM - 小时和分钟，忽略秒，无冒号
  
  +HH:MM - 小时和分钟，忽略秒，有冒号
  
  +HHMMss - 小时和分钟，如果非零则带有秒，无冒号
  
  +HH:MM:ss - 小时和分钟，如果非零则带有秒，有冒号
  
  +HHMMSS - 小时，分钟和秒，无冒号
  
  +HH:MM:SS - 小时，分钟和秒，有冒号
  
  +HHmmss - 小时，如果非零则带有分钟或带有分钟和秒，无冒号
  
  +HH:mm:ss - 小时，如果非零则带有分钟或带有分钟和秒，有冒号
  
  +H - 仅小时，忽略分钟和秒
  
  +Hmm - 小时，如果非零则带有分钟，忽略秒，无冒号
  
  +H:mm - 小时，如果非零则带有分钟，忽略秒，有冒号
  
  +HMM - 小时和分钟，忽略秒，无冒号
  
  +H:MM - 小时和分钟，忽略秒，有冒号
  
  +HMMss - 小时和分钟，如果非零则带有秒，无冒号
  
  +H:MM:ss - 小时和分钟，如果非零则带有秒，有冒号
  
  +HMMSS - 小时，分钟和秒，无冒号
  
  +H:MM:SS - 小时，分钟和秒，有冒号
  
  +Hmmss - 小时，如果非零则带有分钟或带有分钟和秒，无冒号
  
  +H:mm:ss - 小时，如果非零则带有分钟或带有分钟和秒，有冒号
  
  包含"HH"的模式将格式化和解析两位小时，必要时进行零填充。包含"H"的模式将不进行零填充格式化，并解析一位或两位数字。在宽松模式下，解析器将贪婪地解析尽可能多的数字。 "无偏移"文本控制在输出的偏移字段的总量为零时打印的文本。示例值可以是'Z'，'+00:00'，'UTC'或'GMT'。对于解析UTC，接受三种格式 - "无偏移"文本，以及模式定义的零的加号和减号版本。
  参数:
  
  pattern - 要使用的模式，不为null
  
  noOffsetText - 偏移为零时要使用的文本，不为null
  
  返回:
  
  this，用于链接，不为null
  
  抛出:
  
  IllegalArgumentException - 如果模式无效
- appendLocalizedOffset
  
  public DateTimeFormatterBuilder appendLocalizedOffset(TextStyle style)
  追加本地化的区偏移，例如'GMT+01:00'，到格式化程序。 style控制：
  
  full - 格式化为本地化的偏移文本，例如'GMT，2位小时和分钟字段，如果非零则可选的秒字段，以及冒号。
  
  short - 格式化为本地化的偏移文本，例如'GMT，没有前导零的小时，可选的2位分钟和秒（如果非零），以及冒号。
  
  TemporalQueries.offset()的时间查询机制获得的。如果无法获取偏移，则会抛出异常，除非格式化程序的部分是可选的。
  参数:
  
  style - 要使用的格式样式，不为null
  
  返回:
  
  this，用于链接，不为null
  
  抛出:
  
  IllegalArgumentException - 如果样式既不是full也不是short
- appendZoneId
  
  public DateTimeFormatterBuilder appendZoneId()
  追加时区ID，例如'Europe/Paris'或'+02:00'，到格式化程序。 ZonedDateTime使用的严格方式获得的。相比之下， OffsetDateTime没有适合此方法使用的时区ID，请参见 appendZoneOrOffsetId()。
  TemporalQueries.zoneId()的时间查询机制获得的。它将使用 ZoneId.getId()的结果进行打印。如果无法获取时区，则会抛出异常，除非格式化程序的部分是可选的。
  appendOffset(String, String)使用参数'HH:MM:ss'和无偏移字符串'0'。如果解析以'UT'，'UTC'或'GMT'开头，并且解析器无法匹配后面的偏移ID，则选择 ZoneOffset.UTC。在所有其他情况下，将使用已知的基于区域的时区列表来找到最长的可用匹配项。如果找不到匹配项，并且解析以'Z'开头，则选择 ZoneOffset.UTC。解析器使用不区分大小写设置。
  
  "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")
  返回:
  
  this，用于链接，不为null
  
  参见:
  
  appendZoneRegionId()
- appendZoneRegionId
  
  public DateTimeFormatterBuilder appendZoneRegionId()
  将时区区域ID（例如'Europe/Paris'）附加到格式化程序，如果它是ZoneOffset，则拒绝区域ID。
  仅当它是基于区域的ID时，才向构建器附加一个指令以格式化/解析区域ID。
  
  在格式化期间，使用等效于使用TemporalQueries.zoneId()查询时间的机制来获取区域。如果区域是ZoneOffset或无法获取，则会抛出异常，除非格式化程序的部分是可选的。如果区域不是偏移量，则将使用来自ZoneId.getId()的区域ID打印。
  
  在解析期间，文本必须匹配已知的区域或偏移量。有两种类型的区域ID，基于偏移量的，例如'+01:30'和基于区域的，例如'Europe/London'。这些被解析的方式不同。如果解析以'+', '-', 'UT', 'UTC'或'GMT'开头，则解析器期望基于偏移量的区域，并且不会匹配基于区域的区域。偏移ID，例如'+02:30'，可以在解析的开头，或者在'UT'，'UTC'或'GMT'之前加上前缀。偏移ID解析等效于使用appendOffset(String, String)，使用参数'HH:MM:ss'和无偏移字符串'0'。如果解析以'UT'，'UTC'或'GMT'开头，并且解析器无法匹配后面的偏移ID，则选择ZoneOffset.UTC。在所有其他情况下，将使用已知基于区域的区域列表来找到最长的可用匹配项。如果找不到匹配项，并且解析以'Z'开头，则选择ZoneOffset.UTC。解析器使用区分大小写设置。
  
  例如，以下内容将被解析：
  
  "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()相同，只是获取区域的机制不同。还请注意，解析接受偏移量，而格式化永远不会产生偏移量。
  返回：
  
  this，用于链接，不为null
  
  参见：
  
  appendZoneId()
- appendZoneOrOffsetId
  
  public DateTimeFormatterBuilder appendZoneOrOffsetId()
  将时区ID（例如'Europe/Paris'或'+02:00'）附加到格式化程序，使用最佳可用的区域ID。
  这向构建器附加一个指令，以格式化/解析最佳可用的区域或偏移ID。区域ID以一种宽松的方式获取，首先尝试找到真实的区域ID，例如在ZonedDateTime上，然后尝试找到偏移量，例如在OffsetDateTime上。
  
  在格式化期间，使用等效于使用TemporalQueries.zone()查询时间的机制来获取区域。它将使用ZoneId.getId()的结果进行打印。如果无法获取区域，则会抛出异常，除非格式化程序的部分是可选的。
  
  在解析期间，文本必须匹配已知的区域或偏移量。有两种类型的区域ID，基于偏移量的，例如'+01:30'和基于区域的，例如'Europe/London'。这些被解析的方式不同。如果解析以'+', '-', 'UT', 'UTC'或'GMT'开头，则解析器期望基于偏移量的区域，并且不会匹配基于区域的区域。偏移ID，例如'+02:30'，可以在解析的开头，或者在'UT'，'UTC'或'GMT'之前加上前缀。偏移ID解析等效于使用appendOffset(String, String)，使用参数'HH:MM:ss'和无偏移字符串'0'。如果解析以'UT'，'UTC'或'GMT'开头，并且解析器无法匹配后面的偏移ID，则选择ZoneOffset.UTC。在所有其他情况下，将使用已知基于区域的区域列表来找到最长的可用匹配项。如果找不到匹配项，并且解析以'Z'开头，则选择ZoneOffset.UTC。解析器使用区分大小写设置。
  
  例如，以下内容将被解析：
  
  "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()相同，只是获取区域的机制不同。
  返回：
  
  this，用于链接，不为null
  
  参见：
  
  appendZoneId()
- appendZoneText
  
  public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle)
  
  将时区名称（例如'British Summer Time'）附加到格式化程序。
  这向构建器附加一个指令，以格式化/解析区域的文本名称。
  
  在格式化期间，使用等效于使用TemporalQueries.zoneId()查询时间的机制来获取区域。如果区域是ZoneOffset，它将使用ZoneOffset.getId()的结果进行打印。如果区域不是偏移量，则将为在DateTimeFormatter中设置的区域查找文本名称。如果被打印的时间对象表示一个瞬时，或者是一个不在夏令时间隙或重叠中的本地日期时间，则文本将是适当的夏季或冬季时间文本。如果查找文本没有找到任何合适的结果，则将打印ID。如果无法获取区域，则会抛出异常，除非格式化程序的部分是可选的。
  
  在解析期间，接受文本区域名称、区域ID或偏移量。许多文本区域名称不是唯一的，例如CST可能既是"Central Standard Time"也是"China Standard Time"。在这种情况下，区域ID将由格式化程序的locale的区域信息和该地区的标准区域ID确定，例如，对于美国东部区域，使用America/New_York。在这种情况下，可以使用appendZoneText(TextStyle, Set)来指定一组首选的ZoneId。
  
  参数：
  
  textStyle - 要使用的文本样式，不为null
  
  返回：
  
  this，用于链接，不为null
- appendZoneText
  
  public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)
  
  将时区名称（例如'British Summer Time'）附加到格式化程序。
  这向构建器附加一个指令，以格式化/解析区域的文本名称。
  
  在格式化期间，使用等效于使用TemporalQueries.zoneId()查询时间的机制来获取区域。如果区域是ZoneOffset，它将使用ZoneOffset.getId()的结果进行打印。如果区域不是偏移量，则将为在DateTimeFormatter中设置的区域查找文本名称。如果被打印的时间对象表示一个瞬时，或者是一个不在夏令时间隙或重叠中的本地日期时间，则文本将是适当的夏季或冬季时间文本。如果查找文本没有找到任何合适的结果，则将打印ID。如果无法获取区域，则会抛出异常，除非格式化程序的部分是可选的。
  
  在解析期间，接受文本区域名称、区域ID或偏移量。许多文本区域名称不是唯一的，例如CST可能既是"Central Standard Time"也是"China Standard Time"。在这种情况下，区域ID将由格式化程序的locale的区域信息和该地区的标准区域ID确定，例如，对于美国东部区域，使用America/New_York。此方法还允许指定一组首选的ZoneId用于解析。如果被解析的文本区域名称不是唯一的，则将使用匹配的首选区域ID。
  
  如果无法解析区域，则会抛出异常，除非格式化程序的部分是可选的。
  
  参数：
  
  textStyle - 要使用的文本样式，不为null
  
  preferredZones - 首选区域ID的集合，不为null
  
  返回：
  
  this，用于链接，不为null
- appendGenericZoneText
  
  public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle)
  
  将通用时区名称（例如'太平洋时间'）附加到格式化程序。
  将一条指令附加到构建器，以格式化/解析时区的通用文本名称。通用名称在整个年份内保持不变，忽略任何夏令时更改。例如，'太平洋时间'是通用名称，而'太平洋标准时间'和'太平洋夏令时间'是具体名称，请参见appendZoneText(TextStyle)。
  
  在格式化期间，使用等效于使用TemporalQueries.zoneId()查询时间对象的机制来获取时区。如果时区是ZoneOffset，则将使用ZoneOffset.getId()的结果进行打印。如果时区不是偏移量，则将为在DateTimeFormatter中设置的区域设置查找文本名称。如果查找文本未找到任何合适的结果，则将打印ID。如果无法获取时区，则会抛出异常，除非格式化程序的部分是可选的。
  
  在解析期间，可以接受文本时区名称、时区ID或偏移量。许多文本时区名称不是唯一的，例如CST可能是“中部标准时间”和“中国标准时间”。在这种情况下，将通过格式化程序的locale和该区域的标准时区ID来确定时区ID，例如，美国东部区域的America/New_York。在这种情况下，可以使用appendGenericZoneText(TextStyle, Set)来指定一组首选的ZoneId。
  
  参数:
  
  textStyle - 要使用的文本样式，不能为空
  
  返回:
  
  用于链接的this，不能为空
  
  自版本:
  
  9
- appendGenericZoneText
  
  public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)
  
  将通用时区名称（例如'太平洋时间'）附加到格式化程序。
  将一条指令附加到构建器，以格式化/解析时区的通用文本名称。通用名称在整个年份内保持不变，忽略任何夏令时更改。例如，'太平洋时间'是通用名称，而'太平洋标准时间'和'太平洋夏令时间'是具体名称，请参见appendZoneText(TextStyle)。
  
  此方法还允许为解析指定一组首选的ZoneId。如果正在解析的文本时区名称不是唯一的，则将使用匹配的首选时区ID。
  
  有关格式化和解析的详细信息，请参见appendGenericZoneText(TextStyle)。
  
  参数:
  
  textStyle - 要使用的文本样式，不能为空
  
  preferredZones - 要使用的首选时区ID集合，不能为空
  
  返回:
  
  用于链接的this，不能为空
  
  自版本:
  
  9
- appendChronologyId
  
  public DateTimeFormatterBuilder appendChronologyId()
  
  将年表ID（例如'ISO'或'泰国佛历'）附加到格式化程序。
  将一条指令附加到构建器，以格式化/解析年表ID。
  
  在格式化期间，使用等效于使用TemporalQueries.chronology()查询时间对象的机制来获取年表。将使用Chronology.getId()的结果进行打印。如果无法获取年表，则会抛出异常，除非格式化程序的部分是可选的。
  
  在解析期间，将解析年表，并且必须与Chronology.getAvailableChronologies()中的年表之一匹配。如果无法解析年表，则会抛出异常，除非格式化程序的部分是可选的。解析器使用不区分大小写设置。
  
  返回:
  
  用于链接的this，不能为空
- appendChronologyText
  
  public DateTimeFormatterBuilder appendChronologyText(TextStyle textStyle)
  
  将年表名称附加到格式化程序。
  在格式化期间将输出日历系统名称。如果无法获取年表，则会抛出异常。
  
  参数:
  
  textStyle - 要使用的文本样式，不能为空
  
  返回:
  
  用于链接的this，不能为空
- appendLocalized
  
  public DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)
  将本地化的日期时间模式附加到格式化程序。
  将一个本地化部分附加到构建器，适用于输出日期、时间或日期时间组合。本地化部分的格式是基于四个项目进行延迟查找的：
  
  指定给此方法的dateStyle
  
  指定给此方法的timeStyle
  
  DateTimeFormatter的Locale
  
  Chronology，选择最佳可用的
  
  在格式化期间，从正在格式化的时间对象中获取年表，可能已被DateTimeFormatter.withChronology(Chronology)覆盖。使用FULL和LONG样式通常需要时区。在使用这些样式进行格式化时，必须有一个ZoneId可用，可以通过使用ZonedDateTime或DateTimeFormatter.withZone(java.time.ZoneId)来获得。
  在解析期间，如果已经解析了年表，则将使用它。否则将使用DateTimeFormatter.withChronology(Chronology)中的默认值，以IsoChronology作为后备。
  
  请注意，此方法提供了类似于DateFormat上的方法（例如DateFormat.getDateTimeInstance(int, int)）的功能。
  参数:
  
  dateStyle - 要使用的日期样式，null表示不需要日期
  
  timeStyle - 要使用的时间样式，null表示不需要时间
  
  返回:
  
  用于链接的this，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果日期和时间样式都为null
- appendLocalized
  
  public DateTimeFormatterBuilder appendLocalized(String requestedTemplate)
  使用请求的模板将本地化模式附加到格式化程序。
  将一个本地化部分附加到构建器，适用于输出日期、时间或日期时间组合。本地化部分的格式是基于三个项目进行延迟查找的：
  
  指定给此方法的requestedTemplate
  
  DateTimeFormatter的Locale
  
  DateTimeFormatter的Chronology，除非被覆盖
  
  在格式化期间，从正在格式化的时间对象中获取年表，可能已被DateTimeFormatter.withChronology(Chronology)覆盖。
  在解析期间，如果已经解析了年表，则将使用它。否则将使用DateTimeFormatter.withChronology(Chronology)中的默认值，以IsoChronology作为后备。
  
  请求的模板是一系列典型模式符号，按照从最大日期或时间单位到最小日期或时间单位的规范顺序排列，可以用以下正则表达式表示：
  
  "G{0,5}" + // 时代 "y*" + // 年 "Q{0,5}" + // 季度 "M{0,5}" + // 月 "w*" + // 基于年份的周 "E{0,5}" + // 星期几 "d{0,2}" + // 日期 "B{0,5}" + // 一天的时段/上午下午 "[hHjC]{0,2}" + // 一天的小时/上午下午（参考LDML中的'j'和'C'） "m{0,2}" + // 小时的分钟 "s{0,2}" + // 分钟的秒 "[vz]{0,4}" // 时区
  
  所有模式符号都是可选的，每个模式符号代表一个字段，例如，'M'代表月份字段。模式符号的数量遵循与格式化和解析的模式部分中相同的表示，例如，“数字”或“文本”。请求模板中的其他模式符号是无效的。
  请求模板与可用本地化格式中最接近的模板的映射由 Unicode LDML规范定义。例如，从请求模板yMMM创建的格式化程序将在US locale中将日期'2020-06-16'格式化为'Jun 2020'。
  参数:
  
  requestedTemplate - 要使用的请求模板，不能为空
  
  返回:
  
  用于链接的this，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果requestedTemplate无效
  
  自版本:
  
  19
  
  外部规范
  
  Unicode Locale Data Markup Language (LDML)
  
  参见:
  
  appendPattern(String)
- appendLiteral
  
  public DateTimeFormatterBuilder appendLiteral(char literal)
  
  将字符文字附加到格式化程序。
  在格式化期间将输出此字符。
  
  参数:
  
  literal - 要附加的文字，不能为空
  
  返回:
  
  用于链接的this，不能为空
- appendLiteral
  
  public DateTimeFormatterBuilder appendLiteral(String literal)
  
  将字符串文字附加到格式化程序。
  在格式化期间将输出此字符串。
  
  如果文字为空，则不会添加到格式化程序中。
  
  参数:
  
  literal - 要附加的文字，不能为空
  
  返回:
  
  用于链接的this，不能为空
- appendDayPeriodText
  
  public DateTimeFormatterBuilder appendDayPeriodText(TextStyle style)
  
  将白天时段文本附加到格式化程序。
  将一条指令附加到构建器，以格式化/解析白天时段的文本名称。白天时段在LDML的“白天时段”元素中定义。
  
  在格式化期间，白天时段从HOUR_OF_DAY获取，并且如果存在，则从MINUTE_OF_HOUR获取。它将被映射到LDML中定义的白天时段类型，例如“morning1”，然后将被翻译为文本。映射到白天时段类型及其翻译都取决于格式化程序中的区域设置。
  
  在解析期间，文本将首先被解析为白天时段类型。然后，解析的白天时段与其他字段组合以在解析阶段生成LocalTime。如果存在HOUR_OF_AMPM字段，则将其与白天时段组合以考虑任何MINUTE_OF_HOUR值生成HOUR_OF_DAY。如果存在HOUR_OF_DAY，则根据白天时段验证它，考虑任何MINUTE_OF_HOUR值。如果存在白天时段但没有HOUR_OF_DAY、MINUTE_OF_HOUR、SECOND_OF_MINUTE和NANO_OF_SECOND，则将白天时段的中点设置为SMART和LENIENT模式下的时间。例如，如果解析的白天时段类型是“night1”，并且在格式化程序区域设置中为其定义的时段是从21:00到06:00，则结果是01:30的LocalTime。如果解析后的时间与白天时段冲突，则在STRICT和SMART模式下会抛出DateTimeException。在LENIENT模式下，不会抛出异常，并且解析的白天时段将被忽略。
  
  “midnight”类型允许“00:00”作为一天的开始和“24:00”作为一天的结束，只要它们与解析的小时字段有效。
  参数:
  
  style - 要使用的文本样式，不能为空
  
  返回:
  
  this，用于链接，不能为空
  
  自版本:
  
  16
  
  外部规范
  
  Unicode Locale Data Markup Language (LDML)
- append
  
  public DateTimeFormatterBuilder append(DateTimeFormatter formatter)
  
  将格式化程序的所有元素附加到构建器。
  此方法的效果与直接将格式化程序的各组成部分附加到此构建器相同。
  
  参数:
  
  formatter - 要添加的格式化程序，不能为空
  
  返回:
  
  this，用于链接，不能为空
- appendOptional
  
  public DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter)
  
  将一个格式化程序附加到构建器，可选择格式化/解析。
  此方法的效果与直接将各组成部分附加到此构建器并用optionalStart()和optionalEnd()括起来相同。
  
  如果数据可用于格式化程序中包含的所有字段，则格式化程序将进行格式化。如果字符串匹配，则格式化程序将进行解析，否则不会返回错误。
  
  参数:
  
  formatter - 要添加的格式化程序，不能为空
  
  返回:
  
  this，用于链接，不能为空
- appendPattern
  
  public DateTimeFormatterBuilder appendPattern(String pattern)
  将由指定模式定义的元素附加到构建器。
  所有字母'A'到'Z'和'a'到'z'都被保留为模式字母。字符'#'、'{'和'}'被保留供将来使用。字符'['和']'表示可选模式。以下模式字母已定义：
  
  符号含义显示方式示例 ------ ------- ------------ ------- G 纪元文本公元; Anno Domini; A u 年份年份 2004; 04 y 纪元年份年份 2004; 04 D 年的第几天数字 189 M/L 月份数字/文本 7; 07; 七月; July; J d 月份中的第几天数字 10 g 修正儒略日数字 2451334 Q/q 年的季度数字/文本 3; 03; Q3; 第三季度 Y 基于周的年份年份 1996; 96 w 基于周的年份中的周数数字 27 W 月份中的周数数字 4 E 星期中的第几天文本星期二; Tuesday; T e/c 本地化的星期几数字/文本 2; 02; 星期二; Tuesday; T F 月份中的第几个星期几数字 3 a 上午/下午文本下午 B 一天中的时段文本早上 h 上午/下午的时钟小时（1-12）数字 12 K 上午/下午的小时（0-11）数字 0 k 一天中的时钟小时（1-24）数字 24 H 一天中的小时（0-23）数字 0 m 小时中的分钟数字 30 s 分钟中的秒数数字 55 S 秒的小数部分小数 978 A 一天中的毫秒数数字 1234 n 秒的纳秒部分数字 987654321 N 一天中的纳秒数数字 1234000000 V 时区 ID 时区 ID America/Los_Angeles; Z; -08:30 v 通用时区名称时区名称 PT, Pacific Time z 时区名称时区名称 Pacific Standard Time; PST O 本地化的时区偏移偏移-O GMT+8; GMT+08:00; UTC-08:00; X 时区偏移 'Z' 为零偏移-X Z; -08; -0830; -08:30; -083015; -08:30:15 x 时区偏移偏移-x +0000; -08; -0830; -08:30; -083015; -08:30:15 Z 时区偏移偏移-Z +0000; -0800; -08:00 p 下一个填充符号填充修饰符 1 ' 文本转义符号分隔符 '' 单引号文本 ' [ 可选部分开始 ] 可选部分结束 # 保留供将来使用 { 保留供将来使用 } 保留供将来使用
  
  模式字母的数量决定格式。请参阅DateTimeFormatter以获取面向用户的模式描述。以下表格定义了模式字母如何映射到构建器。
  
  日期字段：输出日期的模式字母。
  
  模式数量等效的构建器方法 ------- ----- -------------------------- 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, 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, 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 2 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, 3, SignStyle.NOT_NEGATIVE) DDD 3 appendValue(ChronoField.DAY_OF_YEAR, 3) F 1 appendValue(ChronoField.ALIGNED_WEEK_OF_MONTH) g..g 1..n appendValue(JulianFields.MODIFIED_JULIAN_DAY, n, 19, SignStyle.NORMAL) 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)
  
  时间字段：输出时间的模式字母。
  
  模式数量等效的构建器方法 ------- ----- -------------------------- 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..A 1..n appendValue(ChronoField.MILLI_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE) n..n 1..n appendValue(ChronoField.NANO_OF_SECOND, n, 19, SignStyle.NOT_NEGATIVE) N..N 1..n appendValue(ChronoField.NANO_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE)
  
  白天时段：输出白天时段的模式字母。
  
  模式数量等效的构建器方法 ------- ----- -------------------------- B 1 appendDayPeriodText(TextStyle.SHORT) BBBB 4 appendDayPeriodText(TextStyle.FULL) BBBBB 5 appendDayPeriodText(TextStyle.NARROW)
  
  时区 ID：输出ZoneId的模式字母。
  
  模式数量等效的构建器方法 ------- ----- -------------------------- VV 2 appendZoneId() v 1 appendGenericZoneText(TextStyle.SHORT) vvvv 4 appendGenericZoneText(TextStyle.FULL) z 1 appendZoneText(TextStyle.SHORT) zz 2 appendZoneText(TextStyle.SHORT) zzz 3 appendZoneText(TextStyle.SHORT) zzzz 4 appendZoneText(TextStyle.FULL)
  
  时区偏移：输出ZoneOffset的模式字母。
  
  模式数量等效的构建器方法 ------- ----- -------------------------- O 1 appendLocalizedOffset(TextStyle.SHORT) OOOO 4 appendLocalizedOffset(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")
  
  修饰符：修改模式其余部分的模式字母：
  
  模式数量等效的构建器方法 ------- ----- -------------------------- [ 1 optionalStart() ] 1 optionalEnd() p..p 1..n padNext(n)
  
  任何未在上述指定的字母序列、未识别的字母或保留字符都将引发异常。未来版本可能会添加到模式集。建议在要直接输出的所有字符周围使用单引号，以确保未来更改不会破坏您的应用程序。
  
  请注意，模式字符串与SimpleDateFormat类似，但并非完全相同。模式字符串也与Unicode通用区域数据存储库（CLDR/LDML）定义的模式类似，但并非完全相同。模式字符'X'和'u'与Unicode CLDR/LDML对齐。相比之下，SimpleDateFormat使用'u'表示数字星期几。模式字符'y'和'Y'以不同方式解析两位数和超过4位数的年份。添加了模式字符'n'、'A'、'N'和'p'。数字类型将拒绝大数字。
  参数:
  
  pattern - 要添加的模式，不能为空
  
  返回:
  
  this，用于链接，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果模式无效
- padNext
  
  public DateTimeFormatterBuilder padNext(int padWidth)
  
  导致下一个添加的打印机/解析器使用空格填充到固定宽度。
  此填充将使用空格填充到固定宽度。
  
  在格式化期间，装饰的元素将被输出，然后填充到指定的宽度。如果超出填充宽度，将在格式化期间抛出异常。
  
  在解析期间，将解析填充和装饰的元素。如果解析是宽松的，则填充宽度将被视为最大值。填充将被贪婪地解析。因此，如果装饰的元素以填充字符开头，则不会被解析。
  
  参数:
  
  padWidth - 填充宽度，必须大于等于1
  
  返回:
  
  this，用于链接，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果填充宽度太小
- padNext
  
  public DateTimeFormatterBuilder padNext(int padWidth, char padChar)
  
  导致下一个添加的打印机/解析器填充到固定宽度。
  此填充用于除零填充之外的其他填充。应使用appendValue方法来实现零填充。
  
  在格式化期间，装饰的元素将被输出，然后填充到指定的宽度。如果超出填充宽度，将在格式化期间抛出异常。
  
  在解析期间，将解析填充和装饰的元素。如果解析是宽松的，则填充宽度将被视为最大值。如果解析是不区分大小写的，则填充字符将被忽略大小写匹配。填充将被贪婪地解析。因此，如果装饰的元素以填充字符开头，则不会被解析。
  
  参数:
  
  padWidth - 填充宽度，必须大于等于1
  
  padChar - 填充字符
  
  返回:
  
  this，用于链接，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果填充宽度太小
- optionalStart
  
  public DateTimeFormatterBuilder optionalStart()
  
  标记可选部分的开始。
  格式化的输出可以包括可选部分，这些部分可以是嵌套的。通过调用此方法开始可选部分，并通过调用optionalEnd()或结束构建过程来结束可选部分。
  
  可选部分中的所有元素都被视为可选的。在格式化期间，只有在TemporalAccessor中所有元素的数据可用时，才会输出该部分。在解析期间，整个部分可能在解析的字符串中缺失。
  
  例如，考虑一个设置为builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2)的构建器。可选部分将在构建器的末尾自动结束。在格式化期间，只有当可以从日期时间中获取分钟值时，分钟才会被输出。在解析期间，无论分钟是否存在，输入都将成功解析。
  
  返回:
  
  this，用于链接，不能为空
- optionalEnd
  
  public DateTimeFormatterBuilder optionalEnd()
  
  结束可选部分。
  格式化的输出可以包括可选部分，这些部分可以是嵌套的。通过调用optionalStart()开始可选部分，并使用此方法（或在构建器的末尾）结束可选部分。
  
  在没有先前调用optionalStart的情况下调用此方法将抛出异常。在调用optionalStart后立即调用此方法对格式化程序没有其他影响，除了结束（空）可选部分。
  
  可选部分中的所有元素都被视为可选的。在格式化期间，只有在TemporalAccessor中所有元素的数据可用时，才会输出该部分。在解析期间，整个部分可能在解析的字符串中缺失。
  
  例如，考虑一个设置为builder.appendValue(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2).optionalEnd()的构建器。在格式化期间，只有当可以从日期时间中获取分钟值时，分钟才会被输出。在解析期间，无论分钟是否存在，输入都将成功解析。
  
  返回:
  
  this，用于链接，不能为空
  
  抛出:
  
  IllegalStateException - 如果之前没有调用optionalStart
- toFormatter
  
  public DateTimeFormatter toFormatter()
  
  通过使用默认区域设置创建DateTimeFormatter来完成此构建器。
  这将使用默认FORMAT区域设置创建一个格式化程序。数字将使用标准的DecimalStyle进行打印和解析。解析样式将是SMART。
  
  调用此方法将通过重复调用optionalEnd()来结束任何打开的可选部分，然后创建格式化程序。
  
  如果需要，可以在创建格式化程序后继续使用此构建器，尽管通过调用optionalEnd可能已更改状态。
  
  返回:
  
  创建的格式化程序，不能为空
- toFormatter
  
  public DateTimeFormatter toFormatter(Locale locale)
  
  通过使用指定的区域设置创建DateTimeFormatter来完成此构建器。
  这将使用指定的区域设置创建一个格式化程序。数字将使用标准的DecimalStyle进行打印和解析。解析样式将是SMART。
  
  调用此方法将通过重复调用optionalEnd()来结束任何打开的可选部分，然后创建格式化程序。
  
  如果需要，可以在创建格式化程序后继续使用此构建器，尽管通过调用optionalEnd可能已更改状态。
  
  参数:
  
  locale - 用于格式化的区域设置，不能为空
  
  返回:
  
  创建的格式化程序，不能为空

Class DateTimeFormatterBuilder

Constructor Summary

Method Summary

Methods declared in class java.lang.Object

Constructor Details

DateTimeFormatterBuilder

Method Details

getLocalizedDateTimePattern

getLocalizedDateTimePattern

parseCaseSensitive

parseCaseInsensitive

parseStrict

parseLenient

parseDefaulting

appendValue

appendValue

appendValue

appendValueReduced

appendValueReduced

appendFraction

appendText

appendText

appendText

appendInstant

appendInstant

appendOffsetId

appendOffset

appendLocalizedOffset

appendZoneId

appendZoneRegionId

appendZoneOrOffsetId

appendZoneText

appendZoneText

appendGenericZoneText

appendGenericZoneText

appendChronologyId

appendChronologyText

appendLocalized

appendLocalized

appendLiteral

appendLiteral

appendDayPeriodText

append

appendOptional

appendPattern

padNext

padNext

optionalStart

optionalEnd

toFormatter

toFormatter