模块  java.base
软件包  java.time.temporal

Interface TemporalField

  • 所有已知实现类:
    ChronoField

    public interface TemporalField
    日期时间字段,例如月份或小时。

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

    最常用的单位在ChronoField中定义。 此外字段在供给IsoFieldsWeekFieldsJulianFields 通过实现此接口,还可以通过应用程序代码编写字段。

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

    实现要求:
    必须小心实现此接口,以确保其他类正常运行。 可以实例化的所有实现必须是最终的,不可变的和线程安全的。 在可能的情况下,实施应该是Serializable 枚举是有效的实现选择。
    从以下版本开始:
    1.8
    • 方法详细信息

      • getDisplayName

        default String getDisplayName​(Locale locale)
        获取请求的语言环境中字段的显示名称。

        如果区域设置没有显示名称,则必须返回合适的默认值。

        默认实现必须检查语言环境是否为null并返回toString()

        参数
        locale - 要使用的语言环境,不为null
        结果
        语言环境的显示名称或合适的默认值,而不是null
      • getBaseUnit

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

        该字段的单位是在该范围内变化的周期。 例如,在“MonthOfYear”字段中,单位为“Months”。 另见getRangeUnit()

        结果
        定义字段基本单位的单位,不为空
      • getRangeUnit

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

        该字段的范围是字段在其中变化的周期。 例如,在“MonthOfYear”字段中,范围为“年”。 另见getBaseUnit()

        范围永远不会为空。 例如,'Year'字段是'YearOfForever'的简写。 因此它有一个'年'单位和一系列'永远'。

        结果
        定义字段范围的单位,不为空
      • range

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

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

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

        结果
        字段的有效值范围,不为null
      • isDateBased

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

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

        结果
        如果此字段是日期的组成部分,则为true
      • isTimeBased

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

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

        结果
        如果此字段是时间的组成部分,则为true
      • 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 - 要查询的时态对象,而不是null
        结果
        如果可以为此字段查询日期时间,则返回true,否则返回false
      • rangeRefinedBy

        ValueRange rangeRefinedBy​(TemporalAccessor temporal)
        使用temporal对象获取此字段的有效值范围以优化结果。

        这使用temporal对象来查找字段的有效值范围。 这类似于range() ,但是此方法使用temporal来细化结果。 例如,如果该字段为DAY_OF_MONTHrange方法不准确,因为有四个可能的月份长度, range和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) ,因为在代码中读取要清楚range(TemporalField)

        实现应使用ChronoField提供的字段执行任何查询或计算。 如果不支持该字段,则必须抛出UnsupportedTemporalTypeException

        参数
        temporal - 用于细化结果的时态对象,不为null
        结果
        此字段的有效值范围,不为null
        异常
        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) ,因为在代码中读取要清楚getLong(TemporalField)

        实现应使用ChronoField提供的字段执行任何查询或计算。 如果不支持该字段,则必须抛出UnsupportedTemporalTypeException

        参数
        temporal - 要查询的时态对象,而不是null
        结果
        此字段的值,不为null
        异常
        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) ,因为在代码中读取要清楚with(TemporalField)

        实现应使用ChronoField提供的字段执行任何查询或计算。 如果不支持该字段,则必须抛出UnsupportedTemporalTypeException

        实现不得更改指定的时态对象。 相反,必须返回原始的调整副本。 这为不可变和可变实现提供了等效的安全行为。

        参数类型
        R - 临时对象的类型
        参数
        temporal - 要调整的时态对象,而不是null
        newValue - 该字段的新值
        结果
        调整后的时态对象,不为空
        异常
        DateTimeException - 如果无法设置字段
        UnsupportedTemporalTypeException - 如果时间不支持该字段
        ArithmeticException - 如果发生数字溢出
      • resolve

        default TemporalAccessor resolve​(Map<TemporalField,​Long> fieldValues,
                                         TemporalAccessor partialTemporal,
                                         ResolverStyle resolverStyle)
        解析此字段以提供更简单的替代或日期。

        在解析的解析阶段调用此方法。 它旨在允许将应用程序定义的字段简化为更多标准字段,例如ChronoField上的ChronoField或日期。

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

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

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

        解析字段将包括查看此字段的值以及可能的其他字段,并使用更简单的值更新地图,例如ChronoField ,或返回完整的ChronoLocalDate 如果解析成功,则代码必须删除从地图中解析的所有字段,包括此字段。

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

        部分完整的时间用于允许查询年表和区域。 一般来说,只需要年表。 查询区域或年表以外的项目是未定义的,不得依赖。 的其他方法,如行为getgetLongrangeisSupported是不可预测的,结果不确定。

        如果解决方案应该可行,但数据无效,则应使用解析器样式来确定适当的宽大程度,这可能需要抛出DateTimeExceptionArithmeticException 如果无法解析,则resolve方法必须返回null。

        解析时间字段时,将更改映射并返回null。 解析日期字段时,通常会从方法返回日期,并更改地图以删除已解析的字段。 然而,它也将是可接受的日期字段被解析成其他ChronoField实例,可以产生一个日期,如EPOCH_DAY

        并非所有TemporalAccessor实现都被接受为返回值。 调用此方法的实现必须接受ChronoLocalDateChronoLocalDateTimeChronoZonedDateTimeLocalTime

        默认实现必须返回null。

        参数
        fieldValues - 值的字段映射,可以更新,而不是null
        partialTemporal - 区域和年表查询的部分完整时间; 查询其他内容是未定义的,不推荐,不是null
        resolverStyle - 请求的解析类型,不为null
        结果
        已解决的时态对象; 如果解析仅更改了映射,或者没有解决,则返回null
        异常
        ArithmeticException - 如果发生数字溢出
        DateTimeException - 如果解析导致错误。 这不能通过查询时间上的字段而不首先检查它是否受支持而抛出
      • toString

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

        应该采用'BaseOfRange'格式,例如'MonthOfYear',除非该字段的范围为FOREVER ,仅提及基本单位,例如'Year'或'Era'。

        重写:
        toString在类 Object
        结果
        字段的名称,不为null