模块 java.base
包 java.time.chrono

接口 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 中的讨论。

实现要求：
必须小心实现此接口以确保其他类正确运行。所有可以实例化的实现都必须是最终的、不可变的和线程安全的。只要有可能，子类就应该是可序列化的。
自从：
1.8

  • 方法详情

    • 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/格林威治时间的偏移量。

      返回：
      区域偏移量，不为空

    • getZone

      ZoneId  getZone()
      获取区域 ID，例如“欧洲/巴黎”。

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

      返回：
      区域 ID，不为空

    • withEarlierOffsetAtOverlap

      ChronoZonedDateTime <D > withEarlierOffsetAtOverlap()
      返回此日期时间的副本，将区域偏移量更改为本地时间线重叠处两个有效偏移量中较早的一个。

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

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

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

      返回：
      a 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 方法将抛出异常。

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

      如果单位不是 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);    // most key classes implement TemporalAdjuster
 date = date.with(lastDayOfMonth()); // static import from Adjusters
 date = date.with(next(WEDNESDAY));  // static import from Adjusters and 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);        // add a Period instance
 date = date.plus(duration);       // add a Duration instance
 date = date.plus(workingDays(6));    // example user-written workingDays method

      请注意，调用 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);        // subtract a Period instance
 date = date.minus(duration);       // subtract a Duration instance
 date = date.minus(workingDays(6));    // example user-written workingDays method

      请注意，调用 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 表示时间线上与此日期时间相同的点。该计算结合了 本地日期时间 和 offset 。

      返回：
      一个 Instant 表示同一时刻，不为空

    • toEpochSecond

      default long toEpochSecond()
      将此日期时间转换为从 1970-01-01T00:00:00Z 纪元算起的秒数。

      这使用 本地日期时间 和 offset 计算纪元秒值，即从 1970-01-01T00:00:00Z 开始经过的秒数。时代之后的时间线上的瞬间是正的，更早的是负的。

      返回：
      从 1970-01-01T00:00:00Z 开始的秒数

    • compareTo

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

      比较首先基于瞬间，然后基于本地日期时间，然后基于区域 ID，然后基于年表。正如 Comparable 所定义的那样，它“与等于一致”。

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

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

      指定者：
      compareTo 在接口 Comparable<D extends ChronoLocalDate> 中
      参数：
      other - 要比较的另一个日期时间，不为空
      返回：
      比较值，小于则为负，大于则为正

    • isBefore

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

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

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

      参数：
      other - 要比较的另一个日期时间，不为空
      返回：
      如果这一点在指定的日期时间之前，则为真

    • isAfter

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

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

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

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

    • isEqual

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

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

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

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

    • equals

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

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

      重写：
      equals 在类 Object 中
      参数：
      obj - 要检查的对象，null 返回 false
      返回：
      如果这等于另一个日期时间，则为真
      参见：

    • hashCode

      int hashCode()
      此日期时间的哈希码。
      重写：
      hashCode 在类 Object 中
      返回：
      合适的哈希码
      参见：

    • toString

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

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

      重写：
      toString 在类 Object 中
      返回：
      此日期时间的字符串表示形式，不为空