鸿蒙OS Calendar

Calendar

java.lang.Object

|—java.util.Calendar

public abstract class Calendar
extends Object
implements Serializable, Cloneable, Comparable<Calendar>

Calendar 类是一个抽象类，它提供了在特定时刻和一组日历字段（例如 YEAR、MONTH、DAY_OF_MONTH、HOUR 等）之间进行转换的方法，以及用于操作日历字段（例如获取日期）的方法 下周的。 时间的瞬间可以用毫秒值表示，该值是从 1970 年 1 月 1 日 00:00:00.000 GMT（格里高利）纪元的偏移量。

该类还提供了用于在包外实现具体日历系统的附加字段和方法。 这些字段和方法被定义为受保护的。

与其他对语言环境敏感的类一样，Calendar 提供了一个类方法 getInstance，用于获取这种类型的普遍有用的对象。 Calendar 的 getInstance 方法返回一个 Calendar 对象，其日历字段已用当前日期和时间初始化：

     Calendar rightNow = Calendar.getInstance(); 

Calendar 对象可以生成实现特定语言和日历样式的日期时间格式所需的所有日历字段值（例如，Japanese-Gregorian、Japanese-Traditional）。 日历定义了某些日历字段返回的值的范围，以及它们的含义。 例如，日历系统的第一个月对于所有日历都有值 MONTH == JANUARY。 其他值由具体子类定义，例如 ERA。

获取和设置日历字段值

可以通过调用 set 方法来设置日历字段值。 在需要计算其时间值（距纪元的毫秒数）或日历字段的值之前，不会解释日历中设置的任何字段值。 调用 get、getTimeInMillis、getTime、add 和 roll 涉及到这样的计算。

Leniency

Calendar 有两种解释日历字段的模式，宽松和非宽松。当日历处于宽松模式时，它接受的日历字段值范围比它产生的范围更广。当 Calendar 重新计算日历字段值以通过 get() 返回时，所有日历字段都被规范化。例如，宽松的 GregorianCalendar 将 MONTH == JANUARY, DAY_OF_MONTH == 32 解释为 2 月 1 日。

当日历处于非宽松模式时，如果其日历字段中存在任何不一致，它将引发异常。例如，GregorianCalendar 总是产生介于 1 和月份长度之间的 DAY_OF_MONTH 值。如果设置了任何超出范围的字段值，非宽松的 GregorianCalendar 在计算其时间或日历字段值时会引发异常。

第一周日历使用两个参数定义特定于语言环境的一周七天：一周的第一天和第一周的最少天数（从 1 到 7）。这些数字是在构造日历时从语言环境资源数据中获取的。它们也可以通过设置它们的值的方法明确指定。

在设置或获取 WEEK_OF_MONTH 或 WEEK_OF_YEAR 字段时，Calendar 必须确定月份或年份的第一周作为参考点。一个月或一年的第一周定义为从 getFirstDayOfWeek() 开始并至少包含该月或该年的 getMinimalDaysInFirstWeek() 天的最早 7 天时间段。周数 …, -1, 0 在第一周之前；第 2 周、第 3 周、… 跟随它。请注意，get() 返回的标准化编号可能不同。例如，一个特定的日历子类可以将一年中第 1 周的前一周指定为上一年的第 n 周。

日历字段解析 从日历字段计算日期和时间时，可能存在计算信息不足（例如只有年月，没有月日），或者可能存在不一致的信息（例如，7 月 15 日，星期二， 1996（公历）——1996 年 7 月 15 日实际上是星期一）。 Calendar 将通过以下方式解析日历字段值以确定日期和时间。

如果日历字段值有任何冲突，日历会优先考虑最近设置的日历字段。以下是日历字段的默认组合。将使用由最近设置的单个字段确定的最近组合。

对于日期字段：

 YEAR + MONTH + DAY_OF_MONTH
 YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
 YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
 YEAR + DAY_OF_YEAR
 YEAR + DAY_OF_WEEK + WEEK_OF_YEAR 

对于一天中的时间字段：

 HOUR_OF_DAY AM_PM + HOUR 

如果有任何日历字段的值尚未在所选字段组合中设置，日历将使用其默认值。 每个字段的默认值可能因具体的日历系统而异。 例如，在 GregorianCalendar 中，字段的默认值与 Epoch 的开始相同：即 YEAR = 1970、MONTH = JANUARY、DAY_OF_MONTH = 1 等。

注意：某些奇异时间的解释可能存在一定的歧义，通过以下方式解决：

1. 23:59 是一天的最后一分钟，00:00 是第二天的第一分钟。 因此，1999 年 12 月 31 日 23:59 < 2000 年 1 月 1 日 00:00 < 2000 年 1 月 1 日 00:01。
2. 虽然历史上不准确，但午夜也属于“am”，中午属于“pm”，所以同一天，12:00 am（午夜）< 12:01 am，12:00 pm（中午）< 12 :01 下午

日期或时间格式字符串不是日历定义的一部分，因为用户必须在运行时修改或覆盖这些字符串。使用 DateFormat 格式化日期。

字段操作 可以使用三种方法更改日历字段：set()、add() 和 roll()。

set(f, value) 将日历字段 f 更改为值。此外，它设置一个内部成员变量来指示日历字段 f 已更改。尽管日历字段 f 立即更改，但在下一次调用 get()、getTime()、getTimeInMillis()、add() 或 roll() 之前，不会重新计算日历的时间值（以毫秒为单位）。因此，多次调用 set() 不会触发多次不必要的计算。作为使用 set() 更改日历字段的结果，其他日历字段也可能更改，具体取决于日历字段、日历字段值和日历系统。此外，在重新计算日历字段后，get(f) 不一定会返回调用 set 方法设置的值。具体由具体的日历类决定。

示例：考虑最初设置为 1999 年 8 月 31 日的 GregorianCalendar。调用 set(Calendar.MONTH, Calendar.SEPTEMBER) 将日期设置为 1999 年 9 月 31 日。这是一个临时内部表示，如果 getTime() 则解析为 1999 年 10 月 1 日然后被调用。但是，在调用 getTime() 之前调用 set(Calendar.DAY_OF_MONTH, 30) 会将日期设置为 1999 年 9 月 30 日，因为在 set() 本身之后不会发生重新计算。

add(f, delta) 将 delta 添加到字段 f。这相当于调用 set(f, get(f) + delta) 并进行两次调整：

添加规则 1。调用后字段 f 的值减去调用前字段 f 的值是 delta，以字段 f 中发生的任何溢出为模。当字段值超出其范围时会发生溢出，因此，下一个较大的字段会递增或递减，并且字段值会调整回其范围内。

增加规则2。如果一个较小的字段期望是不变的，但是由于字段f改变后它的最小值或最大值发生变化或其他约束，例如时区偏移量变化，它不可能等于它的先前值，然后将其值调整为尽可能接近其预期值。较小的字段表示较小的时间单位。 HOUR 是比 DAY_OF_MONTH 小的字段。不对预期不会保持不变的较小字段进行任何调整。日历系统确定哪些字段预计是不变的。

此外，与 set() 不同，add() 强制立即重新计算日历的毫秒数和所有字段。

示例：考虑最初设置为 1999 年 8 月 31 日的 GregorianCalendar。调用 add(Calendar.MONTH, 13) 将日历设置为 2000 年 9 月 30 日。添加规则 1 将 MONTH 字段设置为九月，因为在八月添加 13 个月会给出九月 下一年。 由于 DAY_OF_MONTH 在 GregorianCalendar 中不能为 9 月的 31，因此添加规则 2 将 DAY_OF_MONTH 设置为 30，这是最接近的可能值。 虽然它是一个较小的字段，但 DAY_OF_WEEK 不会被规则 2 调整，因为它预计会随着 GregorianCalendar 中月份的变化而变化。

roll(f, delta) 将 delta 添加到字段 f 而不更改更大的字段。 这相当于调用 add(f, delta) 并进行以下调整：

滚动规则。 调用后较大的字段保持不变。 较大的字段表示较大的时间单位。 DAY_OF_MONTH 是比 HOUR 更大的字段。

使用模式。 为了激发 add() 和 roll() 的行为，考虑一个带有月、日和年的递增和递减按钮的用户界面组件，以及一个底层的 GregorianCalendar。 如果界面显示为 1999 年 1 月 31 日，用户按下月份增量按钮，应该显示什么？ 如果底层实现使用 set()，它可能显示为 1999 年 3 月 3 日。更好的结果是 1999 年 2 月 28 日。此外，如果用户再次按下月份增量按钮，它应该显示为 1999 年 3 月 31 日，而不是 3 月 28 日 , 1999。通过保存原始日期并使用 add() 或 roll()，根据是否应该影响更大的字段，用户界面可以像大多数用户直观预期的那样运行。

嵌套类摘要

字段摘要

构造函数摘要

方法总结

字段详细信息

ALL_STYLES

public static final int ALL_STYLES

getDisplayNames 的样式说明符，指示所有样式中的名称，例如“January”和“Jan”。

AM

public static final int AM

AM_PM 字段的值，指示一天中从午夜到正午之前的时段。

AM_PM

public static final int AM_PM

get 和 set 的字段编号，指示 HOUR 是在中午之前还是之后。 例如，在晚上 10:04:15.250，AM_PM 是 PM。

APRIL

public static final int APRIL

MONTH 字段的值，指示公历和儒略历中一年中的第四个月。

AUGUST

public static final int AUGUST

MONTH 字段的值，指示公历和儒略历中一年中的第 8 个月。

DATE

public static final int DATE

get 和 set 的字段编号，指示月份中的哪一天。 这是 DAY_OF_MONTH 的同义词。 该月的第一天的值为 1。

DAY_OF_MONTH

public static final int DAY_OF_MONTH

get 和 set 的字段编号，指示月份中的哪一天。 这是 DATE 的同义词。 该月的第一天的值为 1。

DAY_OF_WEEK

public static final int DAY_OF_WEEK

get 和 set 的字段编号，指示星期几。 此字段采用 SUNDAY、MONDAY、TUESDAY、WEDNESDAY、THURSDAY、FRIDAY 和 SATURDAY 值。

DAY_OF_WEEK_IN_MONTH

public static final int DAY_OF_WEEK_IN_MONTH

get 和 set 的字段编号，指示当前月份中星期几的序号。 与 DAY_OF_WEEK 字段一起，它唯一地指定一个月内的一天。 与 WEEK_OF_MONTH 和 WEEK_OF_YEAR 不同，该字段的值不依赖于 getFirstDayOfWeek() 或 getMinimalDaysInFirstWeek()。 DAY_OF_MONTH 1 到 7 始终对应 DAY_OF_WEEK_IN_MONTH 1； 8 到 14 对应于 DAY_OF_WEEK_IN_MONTH 2，依此类推。 DAY_OF_WEEK_IN_MONTH 0 表示 DAY_OF_WEEK_IN_MONTH 1 之前的一周。负值从月底开始倒数，因此一个月的最后一个星期日指定为 DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1。 因为负值向后计数，所以它们在月份内的对齐方式通常与正值不同。 例如，如果一个月有 31 天，DAY_OF_WEEK_IN_MONTH -1 将与 DAY_OF_WEEK_IN_MONTH 5 和 4 结束重叠。

DAY_OF_YEAR

public static final int DAY_OF_YEAR

get 和 set 的字段编号，表示当前年份中的天数。 一年的第一天的值为 1。

DECEMBER

public static final int DECEMBER

MONTH 字段的值，指示公历和儒略历中一年中的第十二个月。

DST_OFFSET

public static final int DST_OFFSET

get 和 set 的字段编号，以毫秒为单位指示夏令时偏移量。

如果 TimeZone 实现子类支持历史夏令时时间表更改，则此字段反映此日历的时区的正确夏令时偏移值。

ERA

public static final int ERA

用于表示时代的 get 和 set 字段编号，例如儒略历中的 AD 或 BC。 这是一个特定于日历的值。

FEBRUARY

public static final int FEBRUARY

MONTH 字段的值，指示公历和儒略历中一年中的第二个月。

FIELD_COUNT

public static final int FIELD_COUNT

get 和 set 识别的不同字段的数量。 字段编号范围为 0..FIELD_COUNT-1。

FRIDAY

public static final int FRIDAY

表示星期五的 DAY_OF_WEEK 字段的值。

HOUR

public static final int HOUR

get 和 set 的字段编号，指示上午或下午的时间。 HOUR 用于 12 小时制 (0 – 11)。 中午和午夜用 0 表示，而不是用 12 表示。例如，在晚上 10:04:15.250，HOUR 是 10。

HOUR_OF_DAY

public static final int HOUR_OF_DAY

get 和 set 的字段编号，指示一天中的小时。 HOUR_OF_DAY 用于 24 小时制。 例如，在晚上 10:04:15.250，HOUR_OF_DAY 是 22。

JANUARY

public static final int JANUARY

MONTH 字段的值，指示公历和儒略历中一年中的第一个月。

JULY

public static final int JULY

MONTH 字段的值，指示公历和儒略历中一年中的第七个月。

JUNE

public static final int JUNE

MONTH 字段的值，指示公历和儒略历中一年中的第 6 个月。

LONG

public static final int LONG

getDisplayName 和 getDisplayNames 的样式说明符，等效于 LONG_FORMAT。

LONG_FORMAT

public static final int LONG_FORMAT

getDisplayName 和 getDisplayNames 的样式说明符，指示用于格式的长名称。

LONG_STANDALONE

public static final int LONG_STANDALONE

getDisplayName 和 getDisplayNames 的样式说明符，指示独立使用的长名称，例如作为日历标题的月份名称。

MARCH

public static final int MARCH

MONTH 字段的值，指示公历和儒略历中一年中的第三个月。

MAY

public static final int MAY

MONTH 字段的值，指示公历和儒略历中一年中的第五个月。

MILLISECOND

public static final int MILLISECOND

get 和 set 的字段编号，指示秒内的毫秒。 例如，在晚上 10:04:15.250，MILLISECOND 是 250。

MINUTE

public static final int MINUTE

get 和 set 的字段编号，指示一小时内的分钟。 例如，在晚上 10:04:15.250，MINUTE 为 4。

MONDAY

public static final int MONDAY

DAY_OF_WEEK 字段的值表示星期一。

MONTH

public static final int MONTH

get 和 set 的字段编号，指示月份。 这是特定于日历的值。 公历和儒略历中的第一个月是 JANUARY，即 0； 最后一个取决于一年中的月数。

NARROW_FORMAT

public static final int NARROW_FORMAT

getDisplayName 和 getDisplayNames 的样式说明符，指示用于格式的窄名称。 窄名称通常是单个字符串，例如星期一的“M”。

NARROW_STANDALONE

public static final int NARROW_STANDALONE

getDisplayName 和 getDisplayNames 的样式说明符分别指示窄名称。 窄名称通常是单个字符串，例如星期一的“M”。

NOVEMBER

public static final int NOVEMBER

MONTH 字段的值，指示公历和儒略历中一年中的第十一个月。

OCTOBER

public static final int OCTOBER

MONTH 字段的值，指示公历和儒略历中一年中的第十个月。

PM

public static final int PM

AM_PM 字段的值，指示一天中从中午到午夜之前的时段。

SATURDAY

public static final int SATURDAY

表示星期六的 DAY_OF_WEEK 字段的值。

SECOND

public static final int SECOND

get 和 set 的字段编号，指示一分钟内的秒数。 例如，在晚上 10:04:15.250，SECOND 是 15。

SEPTEMBER

public static final int SEPTEMBER

MONTH 字段的值，指示公历和儒略历中一年中的第 9 个月。

SHORT

public static final int SHORT

getDisplayName 和 getDisplayNames 的样式说明符，等效于 SHORT_FORMAT。

SHORT_FORMAT

public static final int SHORT_FORMAT

getDisplayName 和 getDisplayNames 的样式说明符，指示用于格式的短名称。

SHORT_STANDALONE

public static final int SHORT_STANDALONE

getDisplayName 和 getDisplayNames 的样式说明符，指示独立使用的短名称，例如作为日历标题的月份缩写。

SUNDAY

public static final int SUNDAY

表示星期日的 DAY_OF_WEEK 字段的值。

THURSDAY

public static final int THURSDAY

表示星期四的 DAY_OF_WEEK 字段的值。

TUESDAY

public static final int TUESDAY

表示星期二的 DAY_OF_WEEK 字段的值。

UNDECIMBER

public static final int UNDECIMBER

MONTH 字段的值表示一年中的第十三个月。 尽管 GregorianCalendar 不使用此值，但农历使用。

WEDNESDAY

public static final int WEDNESDAY

表示星期三的 DAY_OF_WEEK 字段的值。

WEEK_OF_MONTH

public static final int WEEK_OF_MONTH

get 和 set 的字段编号，指示当前月份中的周数。 该月的第一周，由 getFirstDayOfWeek() 和 getMinimalDaysInFirstWeek() 定义，值为 1。子类定义该月第一周前几天的 WEEK_OF_MONTH 值。

WEEK_OF_YEAR

public static final int WEEK_OF_YEAR

get 和 set 的字段编号，表示当前年份中的周数。 一年中的第一周，由 getFirstDayOfWeek() 和 getMinimalDaysInFirstWeek() 定义，值为 1。子类定义一年中第一周前几天的 WEEK_OF_YEAR 值。

YEAR

public static final int YEAR

get 和 set 的字段编号，指示年份。 这是一个特定于日历的值； 请参阅子类文档。

ZONE_OFFSET

public static final int ZONE_OFFSET

get 和 set 的字段编号，指示与 GMT 的原始偏移量（以毫秒为单位）。

如果 TimeZone 实现子类支持历史 GMT 偏移更改，则此字段反映此日历的时区的正确 GMT 偏移值。

areFieldsSet

protected boolean areFieldsSet

如果 fields[] 与当前设置的时间同步，则为true。 如果为 false，则下一次获取字段值的尝试将强制从当前时间值重新计算所有字段。

fields

protected int[] fields

此日历当前设置时间的日历字段值。 这是一个 FIELD_COUNT 整数数组，索引值为 ERA 到 DST_OFFSET。

isSet

protected boolean[] isSet

指示是否设置了日历的指定日历字段的标志。 新对象没有设置字段。 在第一次调用生成字段的方法之后，它们都保持设置。 这是一个 FIELD_COUNT 布尔数组，索引值 ERA 到 DST_OFFSET。

isTimeSet

protected boolean isTimeSet

如果时间值有效，则为true。 通过更改字段 [] 的项目使时间无效。

time

protected long time

此日历的当前设置时间，以 1970 年 1 月 1 日 0:00:00 GMT 之后的毫秒数表示。

构造函数详细信息

Calendar

protected Calendar()

构造一个具有默认时区和默认 FORMAT 语言环境的日历。

Calendar

protected Calendar(TimeZone zone, Locale aLocale)

构造具有指定时区和语言环境的日历。

参数：

方法详情

getInstance

public static Calendar getInstance()

获取使用默认时区和语言环境的日历。 返回的日历基于具有默认 Locale.Category#FORMAT 区域设置的默认时区中的当前时间。

返回:

日历。

getInstance

public static Calendar getInstance(TimeZone zone)

获取使用指定时区和默认语言环境的日历。 返回的日历基于给定时区的当前时间，具有默认的 Locale.Category#FORMAT 语言环境。

参数：

返回:

日历。

getInstance

public static Calendar getInstance(Locale aLocale)

获取使用默认时区和指定区域设置的日历。 返回的日历基于具有给定区域设置的默认时区中的当前时间。

参数：

返回:

日历。

getInstance

public static Calendar getInstance(TimeZone zone, Locale aLocale)

获取具有指定时区和语言环境的日历。 返回的日历基于具有给定语言环境的给定时区中的当前时间。

参数：

返回:

日历。

getAvailableLocales

public static Locale[] getAvailableLocales()

返回此类的 getInstance 方法可以为其返回本地化实例的所有语言环境的数组。 返回的数组必须至少包含一个等于 Locale.US 的 Locale 实例。

返回:

本地化 Calendar 实例可用的语言环境数组。

computeTime

protected abstract void computeTime()

将 [fields] 中的当前日历字段值转换为毫秒时间值 time。

computeFields

protected abstract void computeFields()

将当前毫秒时间值 time 转换为 [fields] 中的日历字段值。 这允许您将日历字段值与为日历设置的新时间同步。 时间不先重新计算； 要重新计算时间，然后是字段，请调用 complete() 方法。

getTime

public final Date getTime()

返回一个 Date 对象，表示此日历的时间值（从 Epoch 开始的毫秒偏移量）。

返回:

表示时间值的日期。

setTime

public final void setTime(Date date)

使用给定的日期设置此日历的时间。

注意：使用 Date(Long.MAX_VALUE) 或 Date(Long.MIN_VALUE) 调用 setTime() 可能会从 get() 中产生不正确的字段值。

参数：

getTimeInMillis

public long getTimeInMillis()

返回此日历的时间值（以毫秒为单位）。

返回:

当前时间，从纪元开始的 UTC 毫秒。

setTimeInMillis

public void setTimeInMillis(long millis)

根据给定的 long 值设置此日历的当前时间。

参数：

get

public int get(int field)

返回给定日历字段的值。 在宽松模式下，所有日历字段都被规范化。 在非宽松模式下，所有日历字段都经过验证，如果任何日历字段的值超出范围，此方法将引发异常。 规范化和验证由 complete() 方法处理，该过程取决于日历系统。

参数：

返回:

给定日历字段的值。

Throws:

internalGet

protected final int internalGet(int field)

返回给定日历字段的值。 此方法不涉及字段值的规范化或验证。

参数：

返回:

给定日历字段的值。

set

public void set(int field, int value)

将给定的日历字段设置为给定的值。 无论宽大模式如何，此方法都不会解释该值。

参数：

Throws:

set

public final void set(int year, int month, int date)

设置日历字段 YEAR、MONTH 和 DAY_OF_MONTH 的值。 保留其他日历字段的先前值。 如果不需要，请先调用 clear()。

参数：

set

public final void set(int year, int month, int date, int hourOfDay, int minute)

设置日历字段 YEAR、MONTH、DAY_OF_MONTH、HOUR_OF_DAY 和 MINUTE 的值。 保留其他字段的先前值。 如果不需要，请先调用 clear()。

参数：

set

public final void set(int year, int month, int date, int hourOfDay, int minute, int second)

设置字段 YEAR、MONTH、DAY_OF_MONTH、HOUR_OF_DAY、MINUTE 和 SECOND 的值。 保留其他字段的先前值。 如果不需要，请先调用 clear()。

参数：

clear

public final void clear()

设置此日历未定义的所有日历字段值和时间值（从纪元开始的毫秒偏移量）。 这意味着 isSet() 将为所有日历字段返回 false，并且日期和时间计算会将这些字段视为从未设置过的字段。 日历实现类可以使用其特定的默认字段值进行日期/时间计算。 例如，如果 YEAR 字段值未定义，则 GregorianCalendar 使用 1970。

clear

public final void clear(int field)

设置此日历未定义的给定日历字段值和时间值（从纪元开始的毫秒偏移量）。 这意味着 isSet(field) 将返回 false，并且日期和时间计算会将字段视为从未设置过。 日历实现类可以使用字段的特定默认值进行日期和时间计算。

HOUR_OF_DAY、HOUR 和 AM_PM 字段是独立处理的，并应用一天中时间的解析规则。 清除其中一个字段不会重置此日历的小时值。 使用 set(Calendar.HOUR_OF_DAY, 0) 重置小时值。

参数：

isSet

public final boolean isSet(int field)

确定给定的日历字段是否设置了值，包括该值已由 get 方法调用触发的内部字段计算设置的情况。

参数：

返回:

如果给定的日历字段设置了值，则为 true； 否则为false。

getDisplayName

public String getDisplayName(int field, int style, Locale locale)

返回给定样式和语言环境中日历字段值的字符串表示形式。 如果没有字符串表示适用，则返回 null。 如果字符串表示适用于给定的日历字段，则此方法调用 Calendar#get(int) 以获取日历字段值。

例如，如果这个 Calendar 是一个 GregorianCalendar 并且它的日期是 2005-01-01，那么 MONTH 字段的字符串表示形式将是英语语言环境中长格式的“January”或短格式的“Jan”。 但是，对于 DAY_OF_MONTH 字段没有可用的字符串表示形式，并且此方法将返回 null。

默认实现支持 DateFormatSymbols 在给定语言环境中具有名称的日历字段。

参数：

返回:

给定样式中给定字段的字符串表示形式，如果没有字符串表示形式适用，则返回 null。

Throws:

getDisplayNames

public MapString,Integer getDisplayNames(int field, int style, Locale locale)

返回一个 Map，其中包含给定样式和语言环境中日历字段的所有名称及其对应的字段值。例如，如果此 Calendar 是 GregorianCalendar，则返回的地图将包含“Jan”到 JANUARY、“Feb”到 FEBRUARY 等，以英语语言环境中的简写形式。

由于使用单个字符，窄名称可能不是唯一的，例如“S”代表星期日和星期六。在这种情况下，返回的 Map 中不包含窄名称。

可以考虑其他日历字段的值以确定一组显示名称。例如，如果此 Calendar 是阴阳历系统并且 YEAR 字段给出的年份值具有闰月，则此方法将返回包含闰月名称的月份名称，并且月份名称将映射到它们特定于年份的值。

默认实现支持包含在 DateFormatSymbols 中的显示名称。例如，如果字段为 MONTH，样式为 ALL_STYLES，则此方法返回一个 Map，其中包含 DateFormatSymbols#getShortMonths() 和 DateFormatSymbols#getMonths() 返回的所有字符串。

参数：

返回:

包含样式和语言环境中的所有显示名称及其字段值的 Map，如果没有为字段定义显示名称，则为 null

Throws:

complete

protected void complete()

填写日历字段中任何未设置的字段。 首先，如果尚未从日历字段值计算时间值（与 Epoch 的毫秒偏移量），则调用 computeTime() 方法。 然后，调用 computeFields() 方法来计算所有日历字段值。

getAvailableCalendarTypes

public static SetString getAvailableCalendarTypes()

返回一个不可修改的 Set，其中包含运行时环境中 Calendar 支持的所有日历类型。 可用的日历类型可用于 Unicode 语言环境扩展。 返回的 Set 至少包含“gregory”。 日历类型不包括别名，例如“gregory”的“gregorian”。

返回:

一个不可修改的 Set 包含所有可用的日历类型

getCalendarType

public String getCalendarType()

返回此日历的日历类型。 日历类型由 Unicode 区域设置数据标记语言 (LDML) 规范定义。

此方法的默认实现返回此 Calendar 实例的类名。 任何实现 LDML 定义的日历系统的子类都应该重写此方法以返回适当的日历类型。

返回:

LDML 定义的日历类型或此 Calendar 实例的类名

equals

public boolean equals(Object obj)

将此日历与指定的对象进行比较。 当且仅当参数是同一日历系统的日历对象时，结果才为true，该对象在与此对象相同的日历参数下表示相同的时间值（从纪元开始的毫秒偏移量）。

Calendar 参数是由 isLenient、getFirstDayOfWeek、getMinimalDaysInFirstWeek 和 getTimeZone 方法表示的值。 如果两个日历之间的这些参数有任何差异，则此方法返回 false。

使用 compareTo 方法仅比较时间值。

覆盖：

类 Object 中的等于

参数：

返回:

如果此对象等于 obj，则为 true； 否则为false。

hashCode

public int hashCode()

返回此日历的哈希码。

覆盖：

类 Object 中的 hashCode

返回:

此对象的哈希码值。

before

public boolean before(Object when)

返回此 Calendar 是否表示指定 Object 表示的时间之前的时间。 该方法等价于：

         compareTo(when) < 0 

当且仅当 when 是 Calendar 实例。 否则，该方法返回 false。

参数：

返回:

如果此日历的时间早于 when 表示的时间，则为 true； 否则为false。

after

public boolean after(Object when)

返回此 Calendar 是否表示指定 Object 表示的时间之后的时间。 该方法等价于：

         compareTo(when) > 0 

当且仅当 when 是 Calendar 实例。 否则，该方法返回 false。

参数：

返回:

如果此日历的时间在 when 表示的时间之后，则为 true； 否则为false。

compareTo

public int compareTo(Calendar anotherCalendar)

比较两个 Calendar 对象表示的时间值（从 Epoch 开始的毫秒偏移量）。

指定者：

接口 ComparableCalendar 中的 compareTo

参数：

返回:

如果参数表示的时间等于此日历表示的时间，则值为 0； 如果此日历的时间早于参数表示的时间，则值小于 0； 如果此日历的时间在参数表示的时间之后，则值大于 0。

Throws:

add

public abstract void add(int field, int amount)

根据日历的规则，在给定的日历字段中添加或减去指定的时间量。 例如，要从日历的当前时间减去 5 天，可以通过调用实现：

add(Calendar.DAY_OF_MONTH, -5).

参数:

roll

public abstract void roll(int field, boolean up)

在给定时间字段上添加或减去（上/下）单个时间单位，而不更改更大的字段。 例如，要将当前日期向上滚动一天，您可以通过调用来实现：

roll(Calendar.DATE, true). 在年份或 Calendar.YEAR 字段上滚动时，它将在 1 和调用 getMaximum(Calendar.YEAR) 返回的值之间滚动年份值。 在月份或 Calendar.MONTH 字段上滚动时，日期等其他字段可能会发生冲突，需要更改。 例如，在 01/31/96 日期滚动月份将导致 02/29/96。 当滚动一天中的小时或 Calendar.HOUR_OF_DAY 字段时，它将滚动 0 到 23 之间的小时值，该值从零开始。

参数：

roll

public void roll(int field, int amount)

将指定的（签名的）金额添加到指定的日历字段而不更改更大的字段。 负数表示向下滚动。

注意：Calendar 上的这个默认实现只是重复调用滚动一个单位的 roll() 版本。 这可能并不总是正确的。 例如，如果 DAY_OF_MONTH 字段为 31，则滚动到二月会将其设置为 28。此函数的 GregorianCalendar 版本解决了这个问题。 其他子类也应该提供对这个函数的覆盖，以做正确的事情。

参数：

setTimeZone

public void setTimeZone(TimeZone value)

使用给定的时区值设置时区。

参数：

getTimeZone

public TimeZone getTimeZone()

获取时区。

返回:

与此日历关联的时区对象。

setLenient

public void setLenient(boolean lenient)

指定日期/时间解释是否宽松。 在宽松的解释下，诸如“1996 年 2 月 942 日”这样的日期将被视为等同于 1996 年 2 月 1 日之后的第 941 天。在严格（非宽松）的解释下，这样的日期将导致抛出异常。 默认是宽松的。

参数：

isLenient

public boolean isLenient()

告诉日期/时间解释是否宽松。

返回:

如果此日历的解释模式宽松，则为 true； 否则为false。

setFirstDayOfWeek

public void setFirstDayOfWeek(int value)

设置一周的第一天是什么； 例如，美国的星期日，法国的星期一。

参数：

getFirstDayOfWeek

public int getFirstDayOfWeek()

获取一周的第一天是什么； 例如，美国的星期日，法国的星期一。

返回:

一周的第一天。

setMinimalDaysInFirstWeek

public void setMinimalDaysInFirstWeek(int value)

设置一年中第一周所需的最少天数； 例如，如果第一周被定义为包含一年中第一个月的第一天的一周，则使用值 1 调用此方法。如果必须是整周，则使用值 7。

参数：

getMinimalDaysInFirstWeek

public int getMinimalDaysInFirstWeek()

获取一年中第一周所需的最少天数； 例如，如果第一周被定义为包含一年中第一个月的第一天的一周，则此方法返回 1。如果所需的最少天数必须是一整周，则此方法返回 7。

返回:

一年中第一周所需的最少天数。

isWeekDateSupported

public boolean isWeekDateSupported()

返回此日历是否支持星期日期。

此方法的默认实现返回 false。

返回:

如果此日历支持星期日期，则为 true； 否则为false。

getWeekYear

public int getWeekYear()

返回此日历表示的周年。 周年与周周期同步。 第一周的第一天是一年中一周的第一天。

此方法的默认实现会引发 UnsupportedOperationException。

返回:

本日历的周年

Throws:

setWeekDate

public void setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)

使用给定的日期说明符设置此日历的日期 – 星期几、一年中的星期和星期几。

与 set 方法不同，所有日历字段和时间值都是在返回时计算的。

如果 weekOfYear 超出了 weekYear 中的有效周范围，则在宽松模式下调整 weekYear 和 weekOfYear 值，或者在非宽松模式下抛出 IllegalArgumentException。

此方法的默认实现会引发 UnsupportedOperationException。

参数：

Throws:

getWeeksInWeekYear

public int getWeeksInWeekYear()

返回此日历表示的一周年中的周数。

此方法的默认实现会引发 UnsupportedOperationException。

返回:

一周中的周数。

Throws:

getMinimum

public abstract int getMinimum(int field)

返回此 Calendar 实例的给定日历字段的最小值。 最小值定义为 get 方法为任何可能的时间值返回的最小值。 最小值取决于实例的日历系统特定参数。

参数：

返回:

给定日历字段的最小值。

getMaximum

public abstract int getMaximum(int field)

返回此 Calendar 实例的给定日历字段的最大值。 最大值定义为 get 方法为任何可能的时间值返回的最大值。 最大值取决于实例的日历系统特定参数。

参数：

返回:

给定日历字段的最大值。

getGreatestMinimum

public abstract int getGreatestMinimum(int field)

返回此 Calendar 实例的给定日历字段的最大最小值。 最高最小值定义为 getActualMinimum(int) 针对任何可能的时间值返回的最大值。 最大最小值取决于实例的日历系统特定参数。

参数：

返回:

给定日历字段的最高最小值。

getLeastMaximum

public abstract int getLeastMaximum(int field)

返回此 Calendar 实例的给定日历字段的最低最大值。 最低最大值定义为 getActualMaximum(int) 为任何可能的时间值返回的最小值。 最小最大值取决于实例的日历系统特定参数。 例如，公历系统的日历为 DAY_OF_MONTH 字段返回 28，因为 28 日是该日历中最短月份的最后一天，即普通年份的二月。

参数：

返回:

给定日历字段的最低最大值。

getActualMinimum

public int getActualMinimum(int field)

在给定此日历的时间值的情况下，返回指定日历字段可能具有的最小值。

此方法的默认实现使用迭代算法来确定日历字段的实际最小值。 如果可能，子类应该用更有效的实现来覆盖它——在许多情况下，它们可以简单地返回 getMinimum()。

参数：

返回:

此日历的时间值的给定日历字段的最小值

getActualMaximum

public int getActualMaximum(int field)

在给定此日历的时间值的情况下，返回指定日历字段可以具有的最大值。 例如，MONTH 字段的实际最大值在某些年份为 12，而在希伯来日历系统中其他年份为 13。

此方法的默认实现使用迭代算法来确定日历字段的实际最大值。 如果可能，子类应该用更有效的实现来覆盖它。

参数：

返回:

此日历的时间值的给定日历字段的最大值

clone

public Object clone()

创建并返回此对象的副本。

覆盖：

在类 Object 中克隆

返回:

此对象的副本。

toString

public String toString()

返回此日历的字符串表示形式。 此方法仅用于调试目的，返回字符串的格式可能因实现而异。 返回的字符串可能为空但不能为空。

覆盖：

类 Object 中的 toString

返回:

此日历的字符串表示形式。

toInstant

public final Instant toInstant()

将此对象转换为 Instant。

转换会创建一个 Instant，它表示时间线上与此日历相同的点。

返回:

表示时间线上同一点的瞬间