模块 java.base

包 java.util

类 Calendar.Builder

java.lang.Object

java.util.Calendar.Builder

封闭类：

Calendar

public static class Calendar.Builder extends Object 
      

Calendar.Builder 用于根据各种日期时间参数创建 Calendar。

有两种方法可以将 Calendar 设置为日期时间值。一种是将即时参数设置为与 时代 的毫秒偏移量。另一种是将各个字段参数（例如 YEAR ）设置为所需的值。这两种方式不能混用。尝试同时设置即时字段和单独字段将导致抛出 IllegalStateException 。但是，允许覆盖即时或字段参数的先前值。

如果没有足够的字段参数来确定日期和/或时间，则在构建 Calendar 时使用日历特定的默认值。例如，如果没有为公历指定 YEAR 值，则将使用 1970。如果字段参数之间存在任何冲突，则应用决议规则。因此，字段设置的顺序很重要。

除了日期时间参数外，还可以设置 locale、时区、星期定义 和 宽大模式 参数。

示例

以下是示例用法。示例代码假定 Calendar 常量是静态导入的。

以下代码生成日期为 2012-12-31（公历）的 Calendar，因为星期一是 ISO 8601 兼容周参数 一周的第一天。

  Calendar cal = new Calendar.Builder().setCalendarType("iso8601")
            .setWeekDate(2013, 1, MONDAY).build();

以下代码生成日期为 1989-01-08（公历）的日文 Calendar，假设默认的 ERA 是从那天开始的 Heisei。

  Calendar cal = new Calendar.Builder().setCalendarType("japanese")
            .setFields(YEAR, 1, DAY_OF_YEAR, 1).build();

自从：

1.8

参见：

• Calendar.getInstance(TimeZone, Locale)
• Calendar.fields

构造方法总结

构造方法

构造方法	描述
Builder()	构造一个 Calendar.Builder

方法总结

修饰符和类型	方法	描述
Calendar	build()	返回根据 setter 方法设置的参数构建的 Calendar。
Calendar.Builder	set(int field, int value)	将 field 参数设置为给定的 value 。
Calendar.Builder	setCalendarType(String type)	将日历类型参数设置为给定的 type 。
Calendar.Builder	setDate(int year, int month, int dayOfMonth)	将日期字段参数设置为 year、month 和 dayOfMonth 给出的值。
Calendar.Builder	setFields(int... fieldValuePairs)	将字段参数设置为其由 fieldValuePairs 给出的值，这些值是字段及其值的对。
Calendar.Builder	setInstant(long instant)	将即时参数设置为给定的 instant 值，该值是 纪元 的毫秒偏移量。
Calendar.Builder	setInstant(Date instant)	将即时参数设置为 Date 给出的 instant 值。
Calendar.Builder	setLenient(boolean lenient)	将宽松模式参数设置为 lenient 给出的值。
Calendar.Builder	setLocale(Locale locale)	将locale参数设置为给定的 locale 。
Calendar.Builder	setTimeOfDay(int hourOfDay, int minute, int second)	将时间字段参数设置为 hourOfDay、minute 和 second 给出的值。
Calendar.Builder	setTimeOfDay(int hourOfDay, int minute, int second, int millis)	将时间字段参数设置为 hourOfDay、minute、second 和 millis 给出的值。
Calendar.Builder	setTimeZone(TimeZone zone)	将时区参数设置为给定的 zone 。
Calendar.Builder	setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)	将基于周的日期参数设置为具有给定日期说明符的值 - 年周、年中周和周中天。
Calendar.Builder	setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)	将周定义参数设置为 firstDayOfWeek 和 minimalDaysInFirstWeek 给出的值，用于确定一年的 第一周。

在类 java.lang.Object 中声明的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

建设者

public Builder()
            

构造一个 Calendar.Builder

方法详情

setInstant

public Calendar.Builder  setInstant(long instant)
            

将即时参数设置为给定的 instant 值，该值是 纪元 的毫秒偏移量。

参数：

instant - 距纪元的毫秒偏移量

返回：

这个Calendar.Builder

抛出：

IllegalStateException - 如果已经设置了任何字段参数

参见：

• Calendar.setTime(Date)
• Calendar.setTimeInMillis(long)
• Calendar.time

setInstant

public Calendar.Builder  setInstant(Date  instant)
            

将即时参数设置为 Date 给出的 instant 值。此方法等效于对 setInstant(instant.getTime()) 的调用。

参数：

instant - 一个 Date 表示距纪元的毫秒偏移量

返回：

这个Calendar.Builder

抛出：

NullPointerException - 如果 instant 是 null

IllegalStateException - 如果已经设置了任何字段参数

参见：

• Calendar.setTime(Date)
• Calendar.setTimeInMillis(long)
• Calendar.time

set

public Calendar.Builder  set(int field, int value)
            

将 field 参数设置为给定的 value 。 field 是 Calendar.fields 的索引，例如 DAY_OF_MONTH 。此方法不执行字段值验证。在构建 Calendar 时，任何超出范围的值要么在宽松模式下被归一化，要么在非宽松模式下被检测为无效值。

参数：

field - Calendar 字段的索引

value - 字段值

返回：

这个Calendar.Builder

抛出：

IllegalArgumentException - 如果 field 无效

IllegalStateException - 如果即时值已经设置，或者字段设置次数过多（大约 Integer.MAX_VALUE ）。

参见：

• Calendar.set(int, int)

setFields

public Calendar.Builder  setFields(int... fieldValuePairs)
            

将字段参数设置为其由 fieldValuePairs 给出的值，这些值是字段及其值的对。例如，

  setFields(Calendar.YEAR, 2013,
       Calendar.MONTH, Calendar.DECEMBER,
       Calendar.DAY_OF_MONTH, 23);

等同于以下 set 调用的序列：

  set(Calendar.YEAR, 2013)
  .set(Calendar.MONTH, Calendar.DECEMBER)
  .set(Calendar.DAY_OF_MONTH, 23);

参数：

fieldValuePairs - 字段值对

返回：

这个Calendar.Builder

抛出：

NullPointerException - 如果 fieldValuePairs 是 null

IllegalArgumentException - 如果任何字段无效，或者 fieldValuePairs.length 是奇数。

IllegalStateException - 如果已设置即时值，或者字段设置次数过多（大约 Integer.MAX_VALUE ）。

setDate

public Calendar.Builder  setDate(int year, int month, int dayOfMonth)
            

将日期字段参数设置为 year、month 和 dayOfMonth 给出的值。此方法等效于调用：

  setFields(Calendar.YEAR, year,
       Calendar.MONTH, month,
       Calendar.DAY_OF_MONTH, dayOfMonth);

参数：

year - YEAR 值

month - MONTH 值（月份编号为 0-based ）。

dayOfMonth - DAY_OF_MONTH 值

返回：

这个Calendar.Builder

setTimeOfDay

public Calendar.Builder  setTimeOfDay(int hourOfDay, int minute, int second)
            

将时间字段参数设置为 hourOfDay、minute 和 second 给出的值。此方法等效于调用：

  setTimeOfDay(hourOfDay, minute, second, 0);

参数：

hourOfDay - HOUR_OF_DAY 值（24 小时制）

minute - MINUTE 值

second - SECOND 值

返回：

这个Calendar.Builder

setTimeOfDay

public Calendar.Builder  setTimeOfDay(int hourOfDay, int minute, int second, int millis)
            

将时间字段参数设置为 hourOfDay、minute、second 和 millis 给出的值。此方法等效于调用：

  setFields(Calendar.HOUR_OF_DAY, hourOfDay,
       Calendar.MINUTE, minute,
       Calendar.SECOND, second,
       Calendar.MILLISECOND, millis);

参数：

hourOfDay - HOUR_OF_DAY 值（24 小时制）

minute - MINUTE 值

second - SECOND 值

millis - MILLISECOND 值

返回：

这个Calendar.Builder

setWeekDate

public Calendar.Builder  setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)
            

将基于周的日期参数设置为具有给定日期说明符的值 - 年周、年中周和周中天。

如果指定的日历不支持星期日期，build 方法将抛出一个 IllegalArgumentException 。

参数：

weekYear - 星期年

weekOfYear - 基于 weekYear 的周数

dayOfWeek - 星期几值：DAY_OF_WEEK 字段的常量之一：SUNDAY ，...，SATURDAY 。

返回：

这个Calendar.Builder

参见：

• Calendar.setWeekDate(int, int, int)
• Calendar.isWeekDateSupported()

setTimeZone

public Calendar.Builder  setTimeZone(TimeZone  zone)
            

将时区参数设置为给定的 zone 。如果没有为这个 Calendar.Builder 提供时区参数，则 默认TimeZone 将在 build 方法中使用。

参数：

zone - TimeZone

返回：

这个Calendar.Builder

抛出：

NullPointerException - 如果 zone 是 null

参见：

• Calendar.setTimeZone(TimeZone)

setLenient

public Calendar.Builder  setLenient(boolean lenient)
            

将宽松模式参数设置为 lenient 给出的值。如果没有给这个 Calendar.Builder 提供宽松的参数，那么 build 方法将使用宽松模式。

参数：

lenient - true 用于宽松模式； false 用于非宽松模式

返回：

这个Calendar.Builder

参见：

• Calendar.setLenient(boolean)

setCalendarType

public Calendar.Builder  setCalendarType(String  type)
            

将日历类型参数设置为给定的 type 。此方法给出的日历类型优先于 locale 给出的任何显式或隐式日历类型。

除了 Calendar.getAvailableCalendarTypes 方法返回的可用日历类型外，"gregorian" 和 "iso8601" 作为 "gregory" 的别名也可用于此方法。

参数：

type - 日历类型

返回：

这个Calendar.Builder

抛出：

NullPointerException - 如果 type 是 null

IllegalArgumentException - 如果 type 未知

IllegalStateException - 如果已经设置了另一种日历类型

参见：

• Calendar.getCalendarType()
• Calendar.getAvailableCalendarTypes()

setLocale

public Calendar.Builder  setLocale(Locale  locale)
            

将locale参数设置为给定的 locale 。如果没有为这个 Calendar.Builder 提供locale，则将使用 defaultLocale for Locale.Category.FORMAT 。

如果调用 setCalendarType 方法没有明确给出日历类型，则 Locale 值用于确定要构建的 Calendar 的类型。

如果调用 setWeekDefinition 方法时未明确给出周定义参数，则使用 Locale 的默认值。

参数：

locale - Locale

返回：

这个Calendar.Builder

抛出：

NullPointerException - 如果 locale 是 null

参见：

• Calendar.getInstance(Locale)

setWeekDefinition

public Calendar.Builder  setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)
            

将周定义参数设置为 firstDayOfWeek 和 minimalDaysInFirstWeek 给出的值，用于确定一年的 第一周。此方法给出的参数优先于 locale 给出的默认值。

参数：

firstDayOfWeek - 一周的第一天； Calendar.SUNDAY 到 Calendar.SATURDAY 之一

minimalDaysInFirstWeek - 第一周的最少天数 (1..7)

返回：

这个Calendar.Builder

抛出：

IllegalArgumentException - 如果 firstDayOfWeek 或 minimalDaysInFirstWeek 无效

参见：

• Calendar.getFirstDayOfWeek()
• Calendar.getMinimalDaysInFirstWeek()

build

public Calendar  build()
            

返回根据 setter 方法设置的参数构建的 Calendar。 setCalendarType 方法或locale 给出的日历类型用于确定要创建的Calendar。如果没有给出明确的日历类型，则创建区域设置的默认日历。

如果日历类型为 "iso8601" ，则 GregorianCalendar 的 公历更改日期 设置为 Date(Long.MIN_VALUE) 为 proleptic 公历。其周定义参数也设置为 符合ISO 8601标准 。请注意，使用 "iso8601" 创建的 GregorianCalendar 的 getCalendarType 方法返回 "gregory" 。

如果没有明确给出这些参数，则默认值用于区域设置和时区。

如果区域设置包含带“tz” Unicode 扩展 的时区，并且未明确指定时区，则使用区域设置中的时区。

任何超出范围的字段值要么在宽松模式下被规范化，要么在非宽松模式下被检测为无效值。

返回：

一个 Calendar 使用这个 Calendar.Builder 的参数构建

抛出：

IllegalArgumentException - 如果日历类型未知，或者在非宽松模式下给出了任何无效的字段值，或者如果为不支持周日期的日历类型给出了周日期。

参见：

• Calendar.getInstance(TimeZone, Locale)
• Locale.getDefault(Locale.Category)
• TimeZone.getDefault()