模块 java.base
包 java.time.temporal

接口 TemporalAccessor

所有已知的子接口：
ChronoLocalDate , ChronoLocalDateTime<D> , ChronoZonedDateTime<D> , Era , Temporal
所有已知的实现类：
DayOfWeek , HijrahDate , HijrahEra , Instant , IsoEra , JapaneseDate , JapaneseEra , LocalDate , LocalDateTime , LocalTime , MinguoDate , MinguoEra , Month , MonthDay , OffsetDateTime , OffsetTime , ThaiBuddhistDate , ThaiBuddhistEra , Year , YearMonth , ZonedDateTime , ZoneOffset
public interface TemporalAccessor
框架级接口定义对时间对象的只读访问，例如日期、时间、偏移量或这些的某种组合。

这是日期、时间和偏移量对象的基本接口类型。它由那些可以提供 fields 或 查询 信息的类实现。

大多数日期和时间信息都可以表示为数字。这些是使用 TemporalField 建模的，使用 long 保存的数字来处理大值。年、月和月日是字段的简单示例，但它们还包括即时和偏移量。有关标准字段集，请参阅 ChronoField 。

chronology 和 时区 两条日期/时间信息不能用数字表示。这些可以通过 查询 使用在 TemporalQuery 上定义的静态方法访问。

子接口 Temporal 将此定义扩展到还支持对更完整的时间对象进行调整和操作的子接口。

此接口是框架级接口，不应在应用程序代码中广泛使用。相反，应用程序应该创建并传递具体类型的实例，例如 LocalDate 。这有很多原因，部分原因是该接口的实现可能在 ISO 以外的日历系统中。有关这些问题的更全面讨论，请参阅 ChronoLocalDate 。

实现要求：
此接口对实现的可变性没有任何限制，但强烈建议使用不变性。
自从：
1.8

  • 方法详情

    • isSupported

      boolean isSupported(TemporalField  field)
      检查是否支持指定的字段。

      这将检查是否可以查询指定字段的日期时间。如果为 false，则调用 range 和 get 方法将抛出异常。

      实现要求：
      实现必须检查和处理 ChronoField 中定义的所有字段。如果支持该字段，则必须返回 true，否则必须返回 false。

      如果该字段不是 ChronoField ，则通过调用 TemporalField.isSupportedBy(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。

      实现必须确保在调用此只读方法时不会更改任何可观察状态。

      参数：
      field - 要检查的字段，null 返回 false
      返回：
      如果可以查询该字段的日期时间，则为 true，否则为 false

    • range

      default ValueRange  range(TemporalField  field)
      获取指定字段的有效值范围。

      所有字段都可以表示为一个long整数。此方法返回一个描述该值有效范围的对象。此时间对象的值用于提高返回范围的准确性。如果日期时间无法返回范围，因为不支持该字段或其他原因，将抛出异常。

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

      实现要求：
      实现必须检查和处理 ChronoField 中定义的所有字段。如果支持该字段，则必须返回该字段的范围。如果不受支持，则必须抛出 UnsupportedTemporalTypeException。

      如果该字段不是 ChronoField ，则通过调用 TemporalField.rangeRefinedBy(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。

      实现必须确保在调用此只读方法时不会更改任何可观察状态。

      默认实现的行为必须等效于此代码：

       if (field instanceof ChronoField) {
  if (isSupported(field)) {
   return field.range();
  }
  throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
 }
 return field.rangeRefinedBy(this);
      参数：
      field - 查询范围的字段，不为空
      返回：
      该字段的有效值范围，不为空
      抛出：
      DateTimeException - 如果无法获得该字段的范围
      UnsupportedTemporalTypeException - 如果不支持该字段

    • get

      default int get(TemporalField  field)
      获取指定字段的值作为 int 。

      这将查询指定字段值的日期时间。返回值将始终在该字段的有效值范围内。如果日期时间不能返回值，因为不支持该字段或其他原因，将抛出异常。

      实现要求：
      实现必须检查和处理 ChronoField 中定义的所有字段。如果该字段受支持且具有 int 范围，则必须返回该字段的值。如果不受支持，则必须抛出 UnsupportedTemporalTypeException。

      如果该字段不是 ChronoField ，则通过调用 TemporalField.getFrom(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。

      实现必须确保在调用此只读方法时不会更改任何可观察状态。

      默认实现的行为必须等效于此代码：

       if (range(field).isIntValue()) {
  return range(field).checkValidIntValue(getLong(field), field);
 }
 throw new UnsupportedTemporalTypeException("Invalid field " + field + " + for get() method, use getLong() instead");
      参数：
      field - 要获取的字段，不为空
      返回：
      字段的值，在值的有效范围内
      抛出：
      DateTimeException - 如果无法获取该字段的值或该值超出该字段的有效值范围
      UnsupportedTemporalTypeException - 如果不支持该字段或值的范围超过 int
      ArithmeticException - 如果发生数字溢出

    • getLong

      long getLong(TemporalField  field)
      获取指定字段的值作为 long 。

      这将查询指定字段值的日期时间。返回值可能超出该字段的有效值范围。如果日期时间不能返回值，因为不支持该字段或其他原因，将抛出异常。

      实现要求：
      实现必须检查和处理 ChronoField 中定义的所有字段。如果支持该字段，则必须返回该字段的值。如果不受支持，则必须抛出 UnsupportedTemporalTypeException。

      如果该字段不是 ChronoField ，则通过调用 TemporalField.getFrom(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。

      实现必须确保在调用此只读方法时不会更改任何可观察状态。

      参数：
      field - 要获取的字段，不为空
      返回：
      该字段的值
      抛出：
      DateTimeException - 如果无法获得该字段的值
      UnsupportedTemporalTypeException - 如果不支持该字段
      ArithmeticException - 如果发生数字溢出

    • query

      default <R> R query(TemporalQuery <R> query)
      查询此日期时间。

      这使用指定的查询策略对象查询此日期时间。

      查询是从日期时间中提取信息的关键工具。根据策略设计模式，它们的存在是为了将查询过程外部化，允许不同的方法。示例可能是检查日期是否是闰年 2 月 29 日之前的一天的查询，或者计算距下一个生日还有多少天的查询。

      最常见的查询实现是方法引用，例如 LocalDate::from 和 ZoneId::from 。其他实现在 TemporalQuery 上作为静态方法提供。

      实现要求：
      默认实现的行为必须等效于此代码： 
       if (query == TemporalQueries.zoneId() ||
    query == TemporalQueries.chronology() || query == TemporalQueries.precision()) {
  return null;
 }
 return query.queryFrom(this);
      允许未来版本向 if 语句添加更多查询。

      所有实现此接口并覆盖此方法的类都必须调用 TemporalAccessor.super.query(query) 。如果 JDK 类提供与默认行为等效的行为，则它们可能会避免调用 super，但是非 JDK 类可能不会使用此优化并且必须调用 super 。

      如果实现可以为默认实现的 if 语句中列出的查询之一提供值，则它必须这样做。例如，存储小时和分钟的应用程序定义的 HourMin 类必须重写此方法，如下所示：

       if (query == TemporalQueries.precision()) {
  return MINUTES;
 }
 return TemporalAccessor.super.query(query);

      实现必须确保在调用此只读方法时不会更改任何可观察状态。

      类型参数：
      R - 结果的类型
      参数：
      query - 要调用的查询，不为空
      返回：
      查询结果，可能返回null（由查询定义）
      抛出：
      DateTimeException - 如果无法查询
      ArithmeticException - 如果发生数字溢出