Module java.base
Package java.time.chrono

Interface ChronoZonedDateTime<D extends ChronoLocalDate>

类型参数:
D - 此日期时间的日期的具体类型
所有超接口:
Comparable<ChronoZonedDateTime<?>>, Temporal, TemporalAccessor
所有已知实现类:
ZonedDateTime
public interface ChronoZonedDateTime<D extends ChronoLocalDate> extends Temporal, Comparable<ChronoZonedDateTime<?>>
具有任意年表的时区日期时间，用于高级全球化用例。

大多数应用程序应将方法签名、字段和变量声明为ZonedDateTime，而不是此接口。

ChronoZonedDateTime是偏移日期时间的抽象表示，其中Chronology chronology或日历系统是可插拔的。日期时间根据由TemporalField表示的字段定义，其中大多数常见实现在ChronoField中定义。年表定义了日历系统的操作方式和标准字段的含义。

何时使用此接口

API的设计鼓励使用ZonedDateTime而不是此接口，即使在应用程序需要处理多个日历系统的情况下也是如此。这一理由在ChronoLocalDate中有详细探讨。

在使用此接口之前，请确保已阅读并理解ChronoLocalDate中的讨论。

实现要求:
必须小心实现此接口，以确保其他类能够正确运行。所有可实例化的实现必须是final、不可变且线程安全的。子类应尽可能实现Serializable。
自:
1.8

  • Method Details

    • timeLineOrder

      static Comparator<ChronoZonedDateTime<?>> timeLineOrder()
      获取比较器，按时间线顺序比较ChronoZonedDateTime，忽略年表。

      此比较器与compareTo(java.time.chrono.ChronoZonedDateTime<?>)中的比较不同，因为它仅比较基础瞬时而不比较年表。这允许基于日期时间在瞬时时间线上的位置比较不同日历系统中的日期。基础比较等同于比较纪元秒和纳秒。

      返回:
      一个比较器，按时间线顺序比较，忽略年表
      另请参阅:

    • from

      static ChronoZonedDateTime<?> from(TemporalAccessor temporal)
      从临时对象获取ChronoZonedDateTime的实例。

      这将基于指定的临时对象创建一个分区日期时间。 TemporalAccessor表示一组任意的日期和时间信息，此工厂将其转换为ChronoZonedDateTime的实例。

      转换从临时对象中提取并组合年表、日期、时间和区域。行为等同于使用Chronology.zonedDateTime(TemporalAccessor)与提取的年表。实现允许执行优化，例如访问等效于相关对象的字段。

      此方法与函数接口TemporalQuery的签名匹配，允许通过方法引用ChronoZonedDateTime::from将其用作查询。

      参数:
      temporal - 要转换的临时对象，非空
      返回:
      日期时间，非空
      抛出:
      DateTimeException - 如果无法转换为ChronoZonedDateTime
      另请参阅:

    • getLong

      default long getLong(TemporalField field)
      从接口复制的描述: TemporalAccessor
      获取指定字段的值为long。

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

      指定者:
      getLong 在接口 TemporalAccessor
      参数:
      field - 要获取的字段，非空
      返回:
      字段的值

    • toLocalDate

      default D toLocalDate()
      获取此日期时间的本地日期部分。

      返回与此日期时间相同年、月和日的本地日期。

      返回:
      此日期时间的日期部分，非空

    • toLocalTime

      default LocalTime toLocalTime()
      获取此日期时间的本地时间部分。

      返回与此日期时间相同小时、分钟、秒和纳秒的本地时间。

      返回:
      此日期时间的时间部分，非空

    • toLocalDateTime

      ChronoLocalDateTime<D> toLocalDateTime()
      获取此日期时间的本地日期时间部分。

      返回与此日期时间相同年、月和日的本地日期。

      返回:
      此日期时间的本地日期时间部分，非空

    • getChronology

      default Chronology getChronology()
      获取此日期时间的年表。

      Chronology表示正在使用的日历系统。年代和其他ChronoField中的字段由年表定义。

      返回:
      年表，非空

    • getOffset

      ZoneOffset getOffset()
      获取区域偏移，例如'+01:00'。

      这是本地日期时间与UTC/Greenwich之间的偏移。

      返回:
      区域偏移，非空

    • getZone

      ZoneId getZone()
      获取区域ID，例如'Europe/Paris'。

      返回用于确定时区规则的存储时区ID。

      返回:
      时区ID，非空

    • withEarlierOffsetAtOverlap

      ChronoZonedDateTime<D> withEarlierOffsetAtOverlap()
      返回更改为本地时间线重叠时两个有效偏移之一的时区偏移的此日期时间的副本。

      此方法仅在本地时间线重叠时才会产生影响，例如在秋季夏令时切换时。在这种情况下，本地日期时间有两个有效偏移。调用此方法将返回具有两个选定偏移中较早的一个的分区日期时间。

      如果在非重叠时调用此方法，则返回this。

      此实例是不可变的，不受此方法调用的影响。

      返回：
      基于此日期时间的ChronoZonedDateTime，具有较早的偏移，非空
      抛出：
      DateTimeException - 如果找不到该区域的规则
      DateTimeException - 如果此日期时间没有有效规则

    • withLaterOffsetAtOverlap

      ChronoZonedDateTime<D> withLaterOffsetAtOverlap()
      返回更改为本地时间线重叠时两个有效偏移之一的时区偏移的此日期时间的副本。

      此方法仅在本地时间线重叠时才会产生影响，例如在秋季夏令时切换时。在这种情况下，本地日期时间有两个有效偏移。调用此方法将返回具有两个选定偏移中较晚的一个的分区日期时间。

      如果在非重叠时调用此方法，则返回this。

      此实例是不可变的，不受此方法调用的影响。

      返回：
      基于此日期时间的ChronoZonedDateTime，具有较晚的偏移，非空
      抛出：
      DateTimeException - 如果找不到该区域的规则
      DateTimeException - 如果此日期时间没有有效规则

    • withZoneSameLocal

      ChronoZonedDateTime<D> withZoneSameLocal(ZoneId zone)
      返回更改为不同时区的此日期时间的副本，如果可能，则保留本地日期时间。

      此方法更改时区并保留本地日期时间。仅当对新区域无效时，才会更改本地日期时间。

      要更改区域并调整本地日期时间，请使用withZoneSameInstant(ZoneId)。

      此实例是不可变的，不受此方法调用的影响。

      参数：
      zone - 要更改为的时区，非空
      返回：
      基于此日期时间的ChronoZonedDateTime，具有请求的区域，非空

    • withZoneSameInstant

      ChronoZonedDateTime<D> withZoneSameInstant(ZoneId zone)
      返回更改为不同时区的此日期时间的副本，保留即时。

      此方法更改时区并保留即时。这通常会导致本地日期时间的更改。

      此方法基于保留相同即时，因此本地时间线中的间隙和重叠对结果没有影响。

      要更改偏移而保持本地时间，请使用withZoneSameLocal(ZoneId)。

      参数：
      zone - 要更改为的时区，非空
      返回：
      基于此日期时间的ChronoZonedDateTime，具有请求的区域，非空
      抛出：
      DateTimeException - 如果结果超出支持的日期范围

    • isSupported

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

      这将检查是否可以在此日期时间上查询指定的字段。如果为false，则调用range、get和with(TemporalField, long)方法将抛出异常。

      支持的字段集由年表定义，通常包括所有ChronoField字段。

      如果字段不是ChronoField，则通过调用TemporalField.isSupportedBy(TemporalAccessor)传递this作为参数来获取此方法的结果。字段是否受支持由字段确定。

      指定者：
      isSupported 在接口 TemporalAccessor
      参数：
      field - 要检查的字段，null返回false
      返回：
      如果可以查询字段，则为true，否则为false

    • isSupported

      default boolean isSupported(TemporalUnit unit)
      检查是否支持指定的单位。

      这将检查是否可以将指定的单位添加到此日期时间或从中减去。如果为false，则调用plus(long, TemporalUnit)和minus方法将抛出异常。

      支持的单位集由年表定义，通常包括所有ChronoUnit单位，但不包括FOREVER。

      如果单位不是ChronoUnit，则通过调用TemporalUnit.isSupportedBy(Temporal)传递this作为参数来获取此方法的结果。单位是否受支持由单位确定。

      指定者：
      isSupported 在接口 Temporal
      参数：
      unit - 要检查的单位，null返回false
      返回：
      如果可以添加/减去单位，则为true，否则为false

    • with

      default ChronoZonedDateTime<D> with(TemporalAdjuster adjuster)
      返回根据指定调整器的规则调整后的与此对象类型相同的对象。

      根据指定调整器的规则调整此日期时间。简单的调整器可能只是设置一个字段，例如年字段。更复杂的调整器可能将日期设置为该月的最后一天。在TemporalAdjusters中提供了一些常见的调整选项。这些包括查找“月末”和“下周三”。调整器负责处理特殊情况，例如月份的变化长度和闰年。

      以下是示例代码，说明了为何以及如何使用此方法：

        date = date.with(Month.JULY);        // 大多数关键类实现TemporalAdjuster
  date = date.with(lastDayOfMonth());  // 从Adjusters进行静态导入
  date = date.with(next(WEDNESDAY));   // 从Adjusters和DayOfWeek进行静态导入
      指定者：
      with 在接口 Temporal
      参数：
      adjuster - 要使用的调整器，非空
      返回：
      具有指定调整的相同类型对象，非空
      抛出：
      DateTimeException - 如果无法进行调整
      ArithmeticException - 如果发生数值溢出

    • with

      ChronoZonedDateTime<D> with(TemporalField field, long newValue)
      返回与此对象类型相同的对象，其中指定字段已更改。

      根据指定字段更改此对象为基础的新对象。例如，在LocalDate上，可以用于设置年、月或日期。返回的对象将具有与此对象相同的可观察类型。

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

      指定者：
      with 在接口 Temporal
      参数：
      field - 要在结果中设置的字段，非空
      newValue - 结果中字段的新值
      返回：
      具有指定字段设置的相同类型对象，非空
      抛出：
      DateTimeException - 如果无法设置字段
      ArithmeticException - 如果发生数值溢出

    • plus

      default ChronoZonedDateTime<D> plus(TemporalAmount amount)
      返回与此对象类型相同的对象，其中添加了一定数量。

      根据指定金额的规则调整此时间，通常是一个Period，但也可以是实现TemporalAmount接口的任何其他类型，例如Duration。

      以下是示例代码，说明了为何以及如何使用此方法：

        date = date.plus(period);                // 添加一个Period实例
  date = date.plus(duration);              // 添加一个Duration实例
  date = date.plus(workingDays(6));        // 示例用户编写的workingDays方法

      请注意，调用plus后跟minus不能保证返回相同的日期时间。

      指定者:
      plus 在接口 Temporal中
      参数:
      amount - 要添加的数量，不能为空
      返回值:
      返回具有指定调整的相同类型的对象，不能为空
      抛出:
      DateTimeException - 如果无法进行添加
      ArithmeticException - 如果发生数值溢出

    • plus

      ChronoZonedDateTime<D> plus(long amountToAdd, TemporalUnit unit)
      返回具有添加指定周期的相同类型的对象。

      此方法返回基于此对象的新对象，其中添加了指定的周期。例如，在LocalDate上，可以用于添加一定数量的年、月或日。返回的对象将具有与此对象相同的可观察类型。

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

      指定者:
      plus 在接口 Temporal中
      参数:
      amountToAdd - 要添加的指定单位的数量，可以为负数
      unit - 要添加的数量的单位，不能为空
      返回值:
      返回具有添加指定周期的相同类型的对象，不能为空
      抛出:
      DateTimeException - 如果无法添加该单位
      ArithmeticException - 如果发生数值溢出

    • minus

      default ChronoZonedDateTime<D> minus(TemporalAmount amount)
      返回具有减去数量的相同类型的对象。

      根据指定数量的规则调整此时间，进行减法。数量通常是一个Period，但也可以是实现TemporalAmount接口的任何其他类型，例如Duration。

      以下是一些示例代码，指示此方法的使用方式和原因：

        date = date.minus(period);               // 减去一个Period实例
  date = date.minus(duration);             // 减去一个Duration实例
  date = date.minus(workingDays(6));       // 示例用户编写的workingDays方法

      请注意，调用plus后跟minus不能保证返回相同的日期时间。

      指定者:
      minus 在接口 Temporal中
      参数:
      amount - 要减去的数量，不能为空
      返回值:
      返回具有指定调整的相同类型的对象，不能为空
      抛出:
      DateTimeException - 如果无法进行减法
      ArithmeticException - 如果发生数值溢出

    • minus

      default ChronoZonedDateTime<D> minus(long amountToSubtract, TemporalUnit unit)
      返回具有减去指定周期的相同类型的对象。

      此方法返回基于此对象的新对象，其中减去了指定的周期。例如，在LocalDate上，可以用于减去一定数量的年、月或日。返回的对象将具有与此对象相同的可观察类型。

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

      指定者:
      minus 在接口 Temporal中
      参数:
      amountToSubtract - 要减去的指定单位的数量，可以为负数
      unit - 要减去的数量的单位，不能为空
      返回值:
      返回具有减去指定周期的相同类型的对象，不能为空
      抛出:
      DateTimeException - 如果无法减去该单位
      ArithmeticException - 如果发生数值溢出

    • query

      default <R> R query(TemporalQuery<R> query)
      使用指定的查询对此日期时间进行查询。

      使用指定的查询策略对象对此日期时间进行查询。 TemporalQuery对象定义要用于获取结果的逻辑。阅读查询的文档以了解此方法的结果。

      此方法的结果是通过在指定的查询上调用TemporalQuery.queryFrom(TemporalAccessor)方法并将this作为参数传递来获得的。

      指定者:
      query 在接口 TemporalAccessor中
      类型参数:
      R - 结果的类型
      参数:
      query - 要调用的查询，不能为空
      返回值:
      查询结果，可能返回null（由查询定义）
      抛出:
      DateTimeException - 如果无法查询（由查询定义）
      ArithmeticException - 如果发生数值溢出（由查询定义）

    • format

      default String format(DateTimeFormatter formatter)
      使用指定的格式化程序格式化此日期时间。

      将此日期时间传递给格式化程序以生成一个字符串。

      默认实现必须遵守以下行为：

        return formatter.format(this);
      参数:
      formatter - 要使用的格式化程序，不能为空
      返回值:
      格式化的日期时间字符串，不能为空
      抛出:
      DateTimeException - 在打印过程中发生错误

    • toInstant

      default Instant toInstant()
      将此日期时间转换为Instant。

      返回一个表示与此日期时间相同时间线上的Instant。计算结合了本地日期时间和偏移量。

      返回值:
      表示相同时刻的Instant，不能为空

    • toEpochSecond

      default long toEpochSecond()
      将此日期时间转换为从1970-01-01T00:00:00Z时代开始的秒数。

      使用本地日期时间和偏移量计算时代秒值，即从1970-01-01T00:00:00Z开始经过的秒数。时代后的时间点为正，之前为负。

      返回值:
      从1970-01-01T00:00:00Z时代开始的秒数

    • compareTo

      default int compareTo(ChronoZonedDateTime<?> other)
      将此日期时间与另一个日期时间进行比较，包括年表。

      比较首先基于时刻，然后基于本地日期时间，然后基于区域ID，最后基于年表。它是“与equals一致”的，由Comparable定义。

      如果所有要比较的日期时间对象都在相同的年表中，则不需要额外的年表阶段。

      此默认实现执行上述定义的比较。

      指定者:
      compareTo 在接口 Comparable<D extends ChronoLocalDate>中
      参数:
      other - 要比较的另一个日期时间，不能为空
      返回值:
      比较器值，即按照时刻、本地日期时间、区域ID和年表的顺序比较此与other值，返回第一个非零结果，否则返回零
      参见:

    • isBefore

      default boolean isBefore(ChronoZonedDateTime<?> other)
      检查此日期时间的时刻是否在指定日期时间之前。

      此方法与compareTo(java.time.chrono.ChronoZonedDateTime<?>)中的比较不同，因为它仅比较日期时间的时刻。这相当于使用dateTime1.toInstant().isBefore(dateTime2.toInstant());。

      此默认实现基于时代秒和纳秒进行比较。

      参数:
      other - 要比较的另一个日期时间，不能为空
      返回值:
      如果此点在指定日期时间之前，则为true

    • isAfter

      default boolean isAfter(ChronoZonedDateTime<?> other)
      检查此日期时间的时刻是否在指定日期时间之后。

      此方法与compareTo(java.time.chrono.ChronoZonedDateTime<?>)中的比较不同，因为它仅比较日期时间的时刻。这相当于使用dateTime1.toInstant().isAfter(dateTime2.toInstant());。

      此默认实现基于纪元秒和纳秒执行比较。

      参数：
      other - 要比较的另一个日期时间，不能为空
      返回：
      如果此日期时间在指定日期时间之后，则返回true

    • isEqual

      default boolean isEqual(ChronoZonedDateTime<?> other)
      检查此日期时间的时刻是否等于指定日期时间的时刻。

      此方法与compareTo(java.time.chrono.ChronoZonedDateTime<?>)和equals(java.lang.Object)中的比较不同，因为它仅比较日期时间的时刻。这相当于使用dateTime1.toInstant().equals(dateTime2.toInstant());。

      此默认实现基于纪元秒和纳秒执行比较。

      参数：
      other - 要比较的另一个日期时间，不能为空
      返回：
      如果时刻等于指定日期时间的时刻，则返回true

    • equals

      boolean equals(Object obj)
      检查此日期时间是否等于另一个日期时间。

      比较基于偏移日期时间和时区。要比较时间线上相同时刻，请使用compareTo(java.time.chrono.ChronoZonedDateTime<?>)。仅比较ChronoZonedDateTime类型的对象，其他类型返回false。

      覆盖：
      equals 在类 Object中
      参数：
      obj - 要检查的对象，null返回false
      返回：
      如果此日期时间等于另一个日期时间，则返回true
      另请参阅：

    • hashCode

      int hashCode()
      此日期时间的哈希码。
      覆盖：
      hashCode 在类 Object中
      返回：
      适当的哈希码
      另请参阅：

    • toString

      String toString()
      将此日期时间输出为String。

      输出将包括完整的分区日期时间。

      覆盖：
      toString 在类 Object中
      返回：
      此日期时间的字符串表示，不能为空