Module java.base
Package java.time.temporal

Interface TemporalField

所有已知的实现类:
ChronoField
public interface TemporalField
日期时间的字段，例如年份或小时。

日期和时间使用将时间线划分为对人类有意义的字段来表示。该接口的实现代表了这些字段。

最常用的单位在ChronoField中定义。其他字段在IsoFields、WeekFields和JulianFields中提供。字段也可以通过实现此接口来由应用程序代码编写。

该字段使用双重分派。客户端代码调用LocalDateTime之类的日期时间上的方法，检查字段是否是ChronoField。如果是，则日期时间必须处理它。否则，方法调用将重新分派到此接口中匹配的方法。

实现要求:
必须小心实现此接口，以确保其他类正常运行。所有可实例化的实现必须是final、不可变和线程安全的。实现应尽可能是Serializable。枚举是一种有效的实现选择。
自 JDK 版本:
1.8

  • Method Details

    • getDisplayName

      default String getDisplayName(Locale locale)
      获取请求区域设置中字段的显示名称。

      如果区域设置中没有显示名称，则必须返回适当的默认值。

      默认实现必须检查区域设置不为null并返回toString()。

      参数:
      locale - 要使用的区域设置，不能为空
      返回:
      区域设置的显示名称或适当的默认值，不能为空

    • getBaseUnit

      TemporalUnit getBaseUnit()
      获取字段的度量单位。

      字段的单位是在范围内变化的周期。例如，在字段“MonthOfYear”中，单位是“月”。另请参见getRangeUnit()。

      返回:
      定义字段基本单位的单位，不能为空

    • getRangeUnit

      TemporalUnit getRangeUnit()
      获取字段绑定的范围。

      字段的范围是字段变化的周期。例如，在字段“MonthOfYear”中，范围是“年”。另请参见getBaseUnit()。

      范围永远不会为null。例如，“Year”字段是“YearOfForever”的简写。因此，它的单位是“年”，范围是“永远”。

      返回:
      定义字段范围的单位，不能为空

    • range

      ValueRange range()
      获取字段的有效值范围。

      所有字段都可以表示为long整数。此方法返回描述该值的有效范围的对象。此方法通常仅适用于ISO-8601日历系统。

      请注意，结果仅描述最小和最大有效值，重要的是不要读取太多内容。例如，范围内可能存在对该字段无效的值。

      返回:
      字段的有效值范围，不能为空

    • isDateBased

      boolean isDateBased()
      检查此字段是否表示日期的组成部分。

      如果字段可以从EPOCH_DAY派生，则字段是基于日期的。请注意，当表示类似于每周分钟的字段时，isDateBased()和isTimeBased()都返回false是有效的。

      返回:
      如果此字段是日期的组成部分，则为true

    • isTimeBased

      boolean isTimeBased()
      检查此字段是否表示时间的组成部分。

      如果字段可以从NANO_OF_DAY派生，则字段是基于时间的。请注意，当表示类似于每周分钟的字段时，isDateBased()和isTimeBased()都返回false是有效的。

      返回:
      如果此字段是时间的组成部分，则为true

    • isSupportedBy

      boolean isSupportedBy(TemporalAccessor temporal)
      检查时间对象是否支持此字段。

      这确定时间访问器是否支持此字段。如果返回false，则无法查询时间对象的此字段。

      使用此方法有两种等效的方法。第一种是直接调用此方法。第二种是使用TemporalAccessor.isSupported(TemporalField)：

         // 这两行代码是等效的，但建议使用第二种方法
   temporal = thisField.isSupportedBy(temporal);
   temporal = temporal.isSupported(thisField);
      建议使用第二种方法isSupported(TemporalField)，因为在代码中更容易阅读。

      实现应使用ChronoField中提供的字段确定它们是否受支持。

      参数:
      temporal - 要查询的时间对象，不能为空
      返回:
      如果可以查询此字段，则为true，否则为false

    • rangeRefinedBy

      ValueRange rangeRefinedBy(TemporalAccessor temporal)
      使用时间对象细化结果获取此字段的有效值范围。

      此方法使用时间对象查找字段的有效值范围。这类似于range()，但此方法使用时间细化结果。例如，如果字段是DAY_OF_MONTH，则range方法不准确，因为一个月有四种可能的长度，28、29、30和31天。使用此方法与日期一起允许范围准确，返回这四个选项中的一个。

      使用此方法有两种等效的方法。第一种是直接调用此方法。第二种是使用TemporalAccessor.range(TemporalField)：

         // 这两行代码是等效的，但建议使用第二种方法
   temporal = thisField.rangeRefinedBy(temporal);
   temporal = temporal.range(thisField);
      建议使用第二种方法range(TemporalField)，因为在代码中更容易阅读。

      实现应使用ChronoField中提供的字段执行任何查询或计算。如果字段不受支持，则必须抛出UnsupportedTemporalTypeException。

      参数:
      temporal - 用于细化结果的时间对象，不能为空
      返回:
      此字段的有效值范围，不能为空
      抛出:
      DateTimeException - 如果无法获取字段的范围
      UnsupportedTemporalTypeException - 如果时间对象不支持该字段

    • getFrom

      long getFrom(TemporalAccessor temporal)
      从指定的时间对象获取此字段的值。

      查询时间对象的此字段的值。

      使用此方法有两种等效的方法。第一种是直接调用此方法。第二种是使用TemporalAccessor.getLong(TemporalField)（或TemporalAccessor.get(TemporalField)）：

         // 这两行代码是等效的，但建议使用第二种方法
   temporal = thisField.getFrom(temporal);
   temporal = temporal.getLong(thisField);
      建议使用第二种方法getLong(TemporalField)，因为在代码中更容易阅读。

      实现应使用ChronoField中提供的字段执行任何查询或计算。如果字段不受支持，则必须抛出UnsupportedTemporalTypeException。

      参数:
      temporal - 要查询的时间对象，不能为空
      返回:
      此字段的值，不能为空
      抛出:
      DateTimeException - 如果无法获取字段的值
      UnsupportedTemporalTypeException - 如果时间对象不支持该字段
      ArithmeticException - 如果发生数值溢出

    • adjustInto

      <R extends Temporal> R adjustInto(R temporal, long newValue)
      返回具有设置此字段值的指定时间对象的副本。

      返回一个基于指定对象的新时间对象，其中此字段的值已更改。例如，在LocalDate上，可以用来设置年、月或日。返回的对象具有与指定对象相同的可观察类型。

      在某些情况下，更改字段的定义不完全。例如，如果目标对象是表示1月31日的日期，则将月份更改为2月将是不明确的。在这种情况下，实现负责解析结果。通常它会选择前一个有效日期，例如在这个例子中是2月的最后一个有效日期。

      有两种等效的使用此方法的方式。第一种是直接调用此方法。第二种是使用Temporal.with(TemporalField, long)：

         // 这两行是等效的，但第二种方法是推荐的
   temporal = thisField.adjustInto(temporal);
   temporal = temporal.with(thisField);
      推荐使用第二种方法with(TemporalField)，因为在代码中更清晰易读。

      实现应该使用ChronoField中可用的字段执行任何查询或计算。如果不支持该字段，则必须抛出UnsupportedTemporalTypeException。

      实现不得更改指定的时间对象。而是必须返回原始对象的调整副本。这为不可变和可变实现提供了等效的安全行为。

      类型参数:
      R - Temporal对象的类型
      参数:
      temporal - 要调整的时间对象，不能为空
      newValue - 字段的新值
      返回:
      调整后的时间对象，不能为空
      抛出:
      DateTimeException - 如果无法设置字段
      UnsupportedTemporalTypeException - 如果时间不支持该字段
      ArithmeticException - 如果发生数值溢出

    • resolve

      default TemporalAccessor resolve(Map<TemporalField,Long> fieldValues, TemporalAccessor partialTemporal, ResolverStyle resolverStyle)
      解析此字段以提供更简单的替代或日期。

      此方法在解析阶段调用。它旨在允许将应用程序定义的字段简化为更标准的字段，例如ChronoField上的字段，或者转换为日期。

      应用程序通常不应直接调用此方法。

      实现要求:
      如果实现表示可以简化或与其他字段组合的字段，则必须实现此方法。

      指定的映射包含解析的当前状态。该映射是可变的，必须进行变异以解析字段和任何相关字段。只有在映射包含此字段时，才会在解析期间调用此方法，因此实现应该假定此字段存在。

      解析字段将包括查看此字段的值，以及可能的其他字段，并更新映射为更简单的值，例如ChronoField，或返回完整的ChronoLocalDate。如果解析成功，代码必须从映射中删除所有已解析的字段，包括此字段。

      部分完成的时间用于允许查询年表和区域设置。一般来说，只需要年表。查询区域设置或年表之外的项目是未定义的，不建议依赖。其他方法的行为，如get、getLong、range和isSupported的结果是不可预测的，结果未定义。

      如果解析应该是可能的，但数据无效，则应使用解析器样式来确定适当的宽容级别，这可能需要抛出DateTimeException或ArithmeticException。如果无法解析，则解析方法必须返回null。

      在解析时间字段时，映射将被更改并返回null。在解析日期字段时，通常会从方法返回日期，并将映射更改以删除已解析的字段。但是，也可以将日期字段解析为其他可以生成日期的ChronoField实例，例如EPOCH_DAY。

      并非所有TemporalAccessor实现都被接受为返回值。调用此方法的实现必须接受ChronoLocalDate、ChronoLocalDateTime、ChronoZonedDateTime和LocalTime。

      默认实现必须返回null。

      参数:
      fieldValues - 字段到值的映射，可以更新，不能为空
      partialTemporal - 部分完成的时间以查询区域设置和年表；查询其他内容是未定义的，不建议，不能为空
      resolverStyle - 请求的解析类型，不能为空
      返回:
      已解析的时间对象；如果解析仅更改了映射，或未发生解析，则返回null
      抛出:
      ArithmeticException - 如果发生数值溢出
      DateTimeException - 如果解析导致错误。在查询时间对象的字段之前，必须先检查是否支持，否则不得抛出此异常

    • toString

      String toString()
      获取字段的描述性名称。

      应该是'BaseOfRange'格式，例如'MonthOfYear'，除非字段的范围为FOREVER，那么只提到基本单位，例如'Year'或'Era'。

      覆盖:
      toString 在类 Object中
      返回:
      字段的名称，不能为空