Module java.base
Package java.time.temporal

Interface 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
框架级接口，定义对时间对象（如日期、时间、偏移或这些组合）的只读访问。

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

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

日期/时间信息中有两个无法用数字表示的部分，即年表和时区。可以通过在TemporalQuery上定义的静态方法使用查询来访问这些信息。

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

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

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

  • Method Details

    • 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 - 如果发生数值溢出