模块 java.base
包 java.text

类 DateFormat

java.lang.Object
java.text.Format
java.text.DateFormat
所有已实现的接口：
Serializable , Cloneable
已知子类：
SimpleDateFormat
public abstract class DateFormat extends Format
DateFormat 是日期/时间格式化子类的抽象类，它以独立于语言的方式格式化和解析日期或时间。日期/时间格式化子类，例如 SimpleDateFormat ，允许格式化（即日期→文本）、解析（文本→日期）和规范化。日期表示为 Date 对象或自 1970 年 1 月 1 日 00:00:00 GMT 以来的毫秒数。

DateFormat 提供了许多类方法，用于根据默认或给定的locale和多种格式化样式获取默认日期/时间格式化程序。格式样式包括 FULL 、 LONG 、 MEDIUM 和 SHORT 。方法描述中提供了使用这些样式的更多详细信息和示例。

DateFormat 帮助您格式化和解析任何locale的日期。您的代码可以完全独立于月份、星期几甚至日历格式的locale约定：阴历与阳历。

要为当前区域设置格式化日期，请使用静态工厂方法之一：


 myString = DateFormat.getDateInstance().format(myDate);

如果您正在格式化多个日期，那么获取格式并多次使用它会更有效，这样系统就不必多次获取有关当地语言和国家惯例的信息。


 DateFormat df = DateFormat.getDateInstance();
 for (int i = 0; i < myDate.length; ++i) {
   output.println(df.format(myDate[i]) + "; ");
 }

要为不同的locale格式化日期，请在对 getDateInstance() 的调用中指定它。


 DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);

如果指定的locale包含“ca”（日历）、“rg”（区域覆盖）和/或“tz”（时区）Unicode 扩展，则日历、国家和/或用于格式化的时区将被覆盖。如果同时指定了“ca”和“rg”，则“ca”扩展中的日历会取代“rg”扩展中的隐式日历。

您也可以使用 DateFormat 进行解析。


 myDate = df.parse(myString);

使用 getDateInstance 获取该国家/地区的正常日期格式。还有其他可用的静态工厂方法。使用 getTimeInstance 获取该国家/地区的时间格式。使用 getDateTimeInstance 获取日期和时间格式。您可以将不同的选项传递给这些工厂方法来控制结果的长度；从 SHORT 到 MEDIUM 到 LONG 到 FULL 。确切的结果取决于locale，但通常是：

  • SHORT 完全是数字，例如 12.13.52 或 3:30pm
  • MEDIUM 更长，比如Jan 12, 1952
  • LONG 更长，例如 January 12, 1952 或 3:30:32pm
  • FULL 已完全指定，例如 Tuesday, April 12, 1952 AD or 3:30:42pm PST 。

如果需要，您还可以在格式上设置时区。如果你想要更多地控制格式或解析，（或者想要给你的用户更多的控制权），你可以尝试将从工厂方法获得的 DateFormat 转换为 SimpleDateFormat 。这将适用于大多数国家；请记住将它放在 try 块中，以防遇到不寻常的情况。

您还可以使用 ParsePosition 和 FieldPosition 的解析和格式化方法的形式，以允许您

  • 逐步解析字符串的各个部分。
  • 对齐任何特定字段，或找出它在屏幕上的位置以供选择。

同步化

日期格式不同步。建议为每个线程创建单独的格式实例。如果多个线程同时访问一个格式，则必须在外部进行同步。

API 注意：
考虑使用 DateTimeFormatter 作为不可变且线程安全的替代方案。
实现要求：
自从：
1.1
参见：

  • 字段详细信息

    • calendar

      protected Calendar  calendar
      Calendar 用于计算日期时间字段和时间的实例。该字段用于格式化和解析。

      子类应将此字段初始化为适合与此 DateFormat 关联的 Locale 的 Calendar 。

    • numberFormat

      protected NumberFormat  numberFormat
      DateFormat 用于格式化日期和时间中的数字的数字格式化程序。子类应将其初始化为适合与此 DateFormat 关联的locale的数字格式。

    • ERA_FIELD

      public static final int ERA_FIELD
      ERA 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • YEAR_FIELD

      public static final int YEAR_FIELD
      YEAR 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • MONTH_FIELD

      public static final int MONTH_FIELD
      MONTH 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • DATE_FIELD

      public static final int DATE_FIELD
      DATE 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • HOUR_OF_DAY1_FIELD

      public static final int HOUR_OF_DAY1_FIELD
      用于基于 HOUR_OF_DAY 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。 HOUR_OF_DAY1_FIELD 用于以一为基础的 24 小时制。例如，23:59 + 01:00 结果为 24:59。
      参见：

    • HOUR_OF_DAY0_FIELD

      public static final int HOUR_OF_DAY0_FIELD
      用于从零开始的 HOUR_OF_DAY 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。 HOUR_OF_DAY0_FIELD 用于从零开始的 24 小时时钟。例如，23:59 + 01:00 结果为 00:59。
      参见：

    • MINUTE_FIELD

      public static final int MINUTE_FIELD
      MINUTE 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • SECOND_FIELD

      public static final int SECOND_FIELD
      SECOND 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • MILLISECOND_FIELD

      public static final int MILLISECOND_FIELD
      MILLISECOND 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • DAY_OF_WEEK_FIELD

      public static final int DAY_OF_WEEK_FIELD
      用于 DAY_OF_WEEK 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • DAY_OF_YEAR_FIELD

      public static final int DAY_OF_YEAR_FIELD
      用于 DAY_OF_YEAR 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • DAY_OF_WEEK_IN_MONTH_FIELD

      public static final int DAY_OF_WEEK_IN_MONTH_FIELD
      用于 DAY_OF_WEEK_IN_MONTH 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • WEEK_OF_YEAR_FIELD

      public static final int WEEK_OF_YEAR_FIELD
      WEEK_OF_YEAR 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • WEEK_OF_MONTH_FIELD

      public static final int WEEK_OF_MONTH_FIELD
      用于 WEEK_OF_MONTH 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • AM_PM_FIELD

      public static final int AM_PM_FIELD
      AM_PM 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • HOUR1_FIELD

      public static final int HOUR1_FIELD
      用于基于 1 的 HOUR 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。 HOUR1_FIELD 用于基于 1 的 12 小时时钟。例如，晚上 11:30 + 1 小时的结果是凌晨 12:30。
      参见：

    • HOUR0_FIELD

      public static final int HOUR0_FIELD
      用于从零开始的 HOUR 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。 HOUR0_FIELD 用于从零开始的 12 小时时钟。例如，11:30 PM + 1 小时的结果是 00:30 AM。
      参见：

    • TIMEZONE_FIELD

      public static final int TIMEZONE_FIELD
      用于 TIMEZONE 字段对齐的有用常量。在日期/时间格式的 FieldPosition 中使用。
      参见：

    • FULL

      public static final int FULL
      完整样式模式的常量。
      参见：

    • LONG

      public static final int LONG
      长样式模式的常量。
      参见：

    • MEDIUM

      public static final int MEDIUM
      中等样式模式的常量。
      参见：

    • SHORT

      public static final int SHORT
      短样式模式的常量。
      参见：

    • DEFAULT

      public static final int DEFAULT
      默认样式模式的常量。它的值是中等。
      参见：

  • 构造方法详细信息

    • DateFormat

      protected DateFormat()
      创建新的日期格式。

  • 方法详情

    • format

      public final StringBuffer  format(Object  obj, StringBuffer  toAppendTo, FieldPosition  fieldPosition)
      将给定的 Object 格式化为日期时间字符串。格式化的字符串附加到给定的 StringBuffer 。
      指定者：
      format 在类 Format 中
      参数：
      obj - 必须是 Date 或 Number 表示与 时代 的毫秒偏移量。
      toAppendTo - 返回日期时间字符串的字符串缓冲区。
      fieldPosition - 跟踪字段在返回字符串中的位置。例如，给定一个日期时间文本 "1996.07.10 AD at 15:08:56 PDT"，如果给定的 fieldPosition 是 YEAR_FIELD ，则 fieldPosition 的开始索引和结束索引将分别设置为 0 和 4。请注意，如果同一日期时间字段在一个模式中出现多次，fieldPosition 将设置为该日期时间字段的第一次出现。例如，使用模式 "h a z (zzzz)" 和对齐字段 TIMEZONE_FIELD 将 Date 格式化为日期时间字符串 "1 PM PDT (Pacific Daylight Time)" ，对于第一次出现的时区模式字符，fieldPosition 的开始索引和结束索引将分别设置为 5 和 8 'z'。
      返回：
      作为 toAppendTo 传入的字符串缓冲区，附加了格式化文本。
      抛出：
      IllegalArgumentException - 如果 Format 无法格式化给定的 obj。
      参见：

    • format

      public abstract StringBuffer  format(Date  date, StringBuffer  toAppendTo, FieldPosition  fieldPosition)
      将 Date 格式化为日期时间字符串。格式化的字符串附加到给定的 StringBuffer 。
      参数：
      date - 要格式化为日期时间字符串的日期。
      toAppendTo - 返回日期时间字符串的字符串缓冲区。
      fieldPosition - 跟踪字段在返回字符串中的位置。例如，给定一个日期时间文本 "1996.07.10 AD at 15:08:56 PDT"，如果给定的 fieldPosition 是 YEAR_FIELD ，则 fieldPosition 的开始索引和结束索引将分别设置为 0 和 4。请注意，如果同一日期时间字段在一个模式中出现多次，fieldPosition 将设置为该日期时间字段的第一次出现。例如，使用模式 "h a z (zzzz)" 和对齐字段 TIMEZONE_FIELD 将 Date 格式化为日期时间字符串 "1 PM PDT (Pacific Daylight Time)" ，对于第一次出现的时区模式字符，fieldPosition 的开始索引和结束索引将分别设置为 5 和 8 'z'。
      返回：
      作为 toAppendTo 传入的字符串缓冲区，附加了格式化文本。

    • format

      public final String  format(Date  date)
      将 Date 格式化为日期时间字符串。
      参数：
      date - 要格式化为日期时间字符串的时间值。
      返回：
      格式化的日期时间字符串。

    • parse

      public Date  parse(String  source) throws ParseException
      从给定字符串的开头解析文本以生成日期。该方法可能不会使用给定字符串的整个文本。

      有关日期解析的更多信息，请参阅 parse(String, ParsePosition) 方法。

      参数：
      source - 一个 String 的开头应该被解析。
      返回：
      从字符串中解析出的 Date。
      抛出：
      ParseException - 如果无法解析指定字符串的开头。

    • parse

      public abstract Date  parse(String  source, ParsePosition  pos)
      根据给定的解析位置解析日期/时间字符串。例如，时间文本 "07/10/96 4:5 PM, PDT" 将被解析为等同于 Date(837039900000L) 的 Date。

      默认情况下，解析是宽松的：如果输入不是此对象的格式方法所使用的形式，但仍可以解析为日期，则解析成功。客户可以通过调用 setLenient(false) 坚持严格遵守格式。

      此解析操作使用 calendar 生成 Date。因此，calendar 的日期时间字段和 TimeZone 值可能已被覆盖，具体取决于子类实现。之前通过调用 setTimeZone 设置的任何 TimeZone 值可能需要恢复以进行进一步操作。

      参数：
      source - 要解析的日期/时间字符串
      pos - 输入时，开始解析的位置；在输出上，解析终止的位置，或者解析失败时的开始位置。
      返回：
      A Date 或 null 如果无法解析输入

    • parseObject

      public Object  parseObject(String  source, ParsePosition  pos)
      解析字符串中的文本以生成 Date 。

      该方法尝试从 pos 给出的索引开始解析文本。如果解析成功，则将pos的索引更新为最后使用的字符之后的索引（解析不一定使用到字符串末尾的所有字符），并返回解析日期。更新后的 pos 可用于指示下一次调用此方法的起点。如果发生错误，则不更改pos的索引，将pos的错误索引设置为发生错误的字符的索引，并返回null。

      有关日期解析的更多信息，请参阅 parse(String, ParsePosition) 方法。

      指定者：
      parseObject 在类 Format 中
      参数：
      source - A String ，其中的一部分应该被解析。
      pos - 具有如上所述的索引和错误索引信息的 ParsePosition 对象。
      返回：
      从字符串中解析出的 Date。如果出现错误，则返回 null。
      抛出：
      NullPointerException - 如果 source 或 pos 为空。

    • getTimeInstance

      public static final DateFormat  getTimeInstance()
      获取具有默认 FORMAT 区域设置的默认格式化样式的时间格式化程序。

      这相当于调用 getTimeInstance(DEFAULT, Locale.getDefault(Locale.Category.FORMAT)) 。

      返回：
      时间格式化程序。
      参见：

    • getTimeInstance

      public static final DateFormat  getTimeInstance(int style)
      为默认 FORMAT locale获取具有给定格式样式的时间格式化程序。

      这相当于调用 getTimeInstance(style, Locale.getDefault(Locale.Category.FORMAT)) 。

      参数：
      style - 给定的格式样式。例如，在美国locale中，SHORT 表示“h:mm a”。
      返回：
      时间格式化程序。
      参见：

    • getTimeInstance

      public static final DateFormat  getTimeInstance(int style, Locale  aLocale)
      获取具有给定locale的给定格式样式的时间格式化程序。
      参数：
      style - 给定的格式样式。例如，在美国locale中，SHORT 表示“h:mm a”。
      aLocale - 给定的locale。
      返回：
      时间格式化程序。

    • getDateInstance

      public static final DateFormat  getDateInstance()
      获取具有默认 FORMAT 区域设置的默认格式化样式的日期格式化程序。

      这相当于调用 getDateInstance(DEFAULT, Locale.getDefault(Locale.Category.FORMAT)) 。

      返回：
      日期格式化程序。
      参见：

    • getDateInstance

      public static final DateFormat  getDateInstance(int style)
      为默认 FORMAT locale获取具有给定格式样式的日期格式化程序。

      这相当于调用 getDateInstance(style, Locale.getDefault(Locale.Category.FORMAT)) 。

      参数：
      style - 给定的格式样式。例如，在美国locale中，SHORT 表示“M/d/yy”。
      返回：
      日期格式化程序。
      参见：

    • getDateInstance

      public static final DateFormat  getDateInstance(int style, Locale  aLocale)
      获取具有给定locale的给定格式样式的日期格式化程序。
      参数：
      style - 给定的格式样式。例如，在美国locale中，SHORT 表示“M/d/yy”。
      aLocale - 给定的locale。
      返回：
      日期格式化程序。

    • getDateTimeInstance

      public static final DateFormat  getDateTimeInstance()
      获取具有默认 FORMAT 区域设置的默认格式化样式的日期/时间格式化程序。

      这相当于调用 getDateTimeInstance(DEFAULT, DEFAULT, Locale.getDefault(Locale.Category.FORMAT)) 。

      返回：
      日期/时间格式化程序。
      参见：

    • getDateTimeInstance

      public static final DateFormat  getDateTimeInstance(int dateStyle, int timeStyle)
      获取具有默认 FORMAT locale的给定日期和时间格式化样式的日期/时间格式化程序。

      这相当于调用 getDateTimeInstance(dateStyle, timeStyle, Locale.getDefault(Locale.Category.FORMAT)) 。

      参数：
      dateStyle - 给定的日期格式样式。例如，在美国locale中，SHORT 表示“M/d/yy”。
      timeStyle - 给定的时间格式样式。例如，在美国locale中，SHORT 表示“h:mm a”。
      返回：
      日期/时间格式化程序。
      参见：

    • getDateTimeInstance

      public static final DateFormat  getDateTimeInstance(int dateStyle, int timeStyle, Locale  aLocale)
      获取具有给定locale的给定格式样式的日期/时间格式化程序。
      参数：
      dateStyle - 给定的日期格式样式。
      timeStyle - 给定的时间格式样式。
      aLocale - 给定的locale。
      返回：
      日期/时间格式化程序。

    • getInstance

      public static final DateFormat  getInstance()
      获取对日期和时间都使用 SHORT 样式的默认日期/时间格式化程序。
      返回：
      日期/时间格式化程序

    • getAvailableLocales

      public static Locale [] getAvailableLocales()
      返回所有locale的数组，此类的 get*Instance 方法可以为其返回本地化实例。返回的数组表示 Java 运行时和已安装的 DateFormatProvider 实现支持的locale的联合。至少，返回的数组必须包含一个等于 Locale.ROOT 的 Locale 实例和一个等于 Locale.US 的 Locale 实例。
      返回：
      本地化 DateFormat 实例可用的locale数组。

    • setCalendar

      public void setCalendar(Calendar  newCalendar)
      设置此日期格式要使用的日历。最初，使用指定或默认locale的默认日历。

      之前设置的任何 TimeZone 和 宽大 值都将被 newCalendar 的值覆盖。

      参数：
      newCalendar - 日期格式要使用的新 Calendar

    • getCalendar

      public Calendar  getCalendar()
      获取与此日期/时间格式化程序关联的日历。
      返回：
      与此日期/时间格式化程序关联的日历。

    • setNumberFormat

      public void setNumberFormat(NumberFormat  newNumberFormat)
      允许您设置数字格式化程序。
      参数：
      newNumberFormat - 给定的新 NumberFormat。

    • getNumberFormat

      public NumberFormat  getNumberFormat()
      获取此日期/时间格式化程序用于格式化和解析时间的数字格式化程序。
      返回：
      此日期/时间格式化程序使用的数字格式化程序。

    • setTimeZone

      public void setTimeZone(TimeZone  zone)
      设置此 DateFormat 对象的日历时区。此方法等效于以下调用。 
      
 getCalendar().setTimeZone(zone)

      通过此方法设置的 TimeZone 被 setCalendar 调用覆盖。

      调用 parse 方法后，此方法设置的 TimeZone 可能会被覆盖。

      参数：
      zone - 给定的新时区。

    • getTimeZone

      public TimeZone  getTimeZone()
      获取时区。此方法等效于以下调用。 
      
 getCalendar().getTimeZone()
      返回：
      与 DateFormat 日历关联的时区。

    • setLenient

      public void setLenient(boolean lenient)
      指定日期/时间解析是否宽松。通过宽松的解析，解析器可以使用试探法来解释与该对象的格式不完全匹配的输入。通过严格解析，输入必须匹配此对象的格式。

      此方法等效于以下调用。

      
 getCalendar().setLenient(lenient)

      调用 setCalendar() 会覆盖此宽大值。

      参数：
      lenient - 当 true 时，解析宽松
      参见：

    • isLenient

      public boolean isLenient()
      判断日期/时间解析是否宽松。此方法等效于以下调用。 
      
 getCalendar().isLenient()
      返回：
      true 如果 calendar 宽松； false否则。
      参见：

    • hashCode

      public int hashCode()
      重写哈希码
      重写：
      hashCode 在类 Object 中
      返回：
      此对象的哈希码值。
      参见：

    • equals

      public boolean equals(Object  obj)
      重写等于
      重写：
      equals 在类 Object 中
      参数：
      obj - 要比较的参考对象。
      返回：
      true 如果此对象与 obj 参数相同； false否则。
      参见：

    • clone

      public Object  clone()
      重写可克隆
      重写：
      clone 在类 Format 中
      返回：
      此实例的克隆。
      参见：