模块 java.base
包 java.time.temporal

接口 TemporalField

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

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

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

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

实现要求：
必须小心实现此接口以确保其他类正确运行。所有可以实例化的实现都必须是最终的、不可变的和线程安全的。在可能的情况下，实现应该是 Serializable。枚举是有效的实现选择。
自从：
1.8

  • 方法详情

    • getDisplayName

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

      如果locale没有显示名称，则必须返回合适的默认值。

      默认实现必须检查locale不为空并返回 toString() 。

      参数：
      locale - 要使用的locale，不为空
      返回：
      locale的显示名称或合适的默认值，不为空

    • getBaseUnit

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

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

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

    • getRangeUnit

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

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

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

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

    • range

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

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

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

      返回：
      该字段的有效值范围，不为空

    • isDateBased

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

      如果字段可以从 EPOCH_DAY 派生，则它是基于日期的。请注意，isDateBased() 和 isTimeBased() 返回 false 都是有效的，例如在表示像星期几这样的字段时。

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

    • isTimeBased

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

      如果字段可以从 NANO_OF_DAY 派生，则它是基于时间的。请注意，isDateBased() 和 isTimeBased() 返回 false 都是有效的，例如在表示像星期几这样的字段时。

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

    • isSupportedBy

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

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

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

        // these two lines are equivalent, but the second approach is recommended
  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) ：

        // these two lines are equivalent, but the second approach is recommended
  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) ）：

        // these two lines are equivalent, but the second approach is recommended
  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) ：

        // these two lines are equivalent, but the second approach is recommended
  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 上的字段，或简化为日期。

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

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

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

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

      例如，IsoFields 类包含季度和季度字段。该方法在该类中的实现将两个字段加上 YEAR 解析为一个完整的 LocalDate 。 resolve 方法将在返回 LocalDate 之前从map中删除所有三个字段。

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

      如果解析应该是可能的，但数据无效，则解析器样式应该用于确定适当的宽大程度，这可能需要抛出 DateTimeException 或 ArithmeticException 。如果无法解决，则 resolve 方法必须返回 null。

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

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

      默认实现必须返回 null。

      参数：
      fieldValues - 字段到值的映射，可以更新，不为空
      partialTemporal - 查询区域和年表的部分完整时间；查询其他事物未定义且不推荐，不为空
      resolverStyle - 请求的解析类型，不为空
      返回：
      解析的时间对象；如果解析仅更改了map，或者没有解析发生，则为 null
      抛出：
      ArithmeticException - 如果发生数字溢出
      DateTimeException - 如果解析结果出错。不得在未先检查是否支持的情况下通过查询时间字段来抛出此错误

    • toString

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

      应该采用“BaseOfRange”格式，例如“MonthOfYear”，除非该字段的范围为 FOREVER ，此时仅提及基本单位，例如“年”或“纪元”。

      重写：
      toString 在类 Object 中
      返回：
      字段名称，不为空