Module java.base
Package java.text

Class 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提供了许多类方法，用于根据默认或给定的区域设置和多种格式样式获取默认的日期/时间格式化程序。格式样式包括FULL、LONG、MEDIUM和SHORT。有关使用这些样式的更多详细信息和示例，请参阅方法描述。

DateFormat可帮助您为任何区域设置格式化和解析日期。您的代码可以完全独立于月份、星期几甚至日历格式的区域约定：农历还是阳历。

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

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

如果要格式化多个日期，最好获取格式并多次使用，以便系统不必多次获取有关本地语言和国家约定的信息。

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

要为不同的区域设置格式化日期，请在调用getDateInstance()时指定它。

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

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

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

myDate = df.parse(myString);

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

  • SHORT完全是数字，例如12.13.52或下午3:30
  • MEDIUM较长，例如1952年1月12日
  • LONG更长，例如1952年1月12日或下午3:30:32
  • FULL非常详细，例如1952年4月12日星期二公元或下午3:30:42 PST。

如果希望，还可以在格式上设置时区。如果希望对格式或解析有更多控制（或希望为用户提供更多控制），可以尝试将从工厂方法获取的DateFormat转换为SimpleDateFormat。这对大多数国家/地区都适用；只需记住将其放在try块中，以防遇到异常的国家/地区。

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

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

同步

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

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

  • Field Details

    • calendar

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

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

    • numberFormat

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

    • 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
      用于基于一的HOUR字段对齐的有用常量。用于日期/时间格式化的FieldPosition中。HOUR1_FIELD用于基于一的12小时制时钟。例如，11:30 PM + 1小时 的结果为 12:30 AM。
      参见:

    • 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
      默认样式模式的常量。其值为MEDIUM。
      参见:

  • Constructor Details

    • DateFormat

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

  • Method Details

    • format

      public final StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition fieldPosition)
      将给定的Object格式化为日期时间字符串。格式化的字符串附加到给定的StringBuffer。
      指定者:
      format 在类 Format
      参数:
      obj - 必须是一个表示距离Epoch的毫秒偏移量的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 - 输入时，开始解析的位置；输出时，解析终止的位置，或者如果解析失败，则为起始位置。
      返回:
      一个Date，如果无法解析输入，则返回null

    • parseObject

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

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

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

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

    • getTimeInstance

      public static final DateFormat getTimeInstance()
      获取默认FORMAT区域设置的默认格式化样式的时间格式化程序。 getTimeInstance(DEFAULT, Locale.getDefault(Locale.Category.FORMAT))。

      返回:
      一个时间格式化程序。
      参见:

    • getTimeInstance

      public static final DateFormat getTimeInstance(int style)
      获取默认FORMAT区域设置的给定格式化样式的时间格式化程序。 getTimeInstance(style, Locale.getDefault(Locale.Category.FORMAT))。

      参数:
      style - 给定的格式化样式。例如，在美国区域设置中，SHORT表示"h:mm a"。
      返回:
      一个时间格式化程序。
      参见:

    • getTimeInstance

      public static final DateFormat getTimeInstance(int style, Locale aLocale)
      获取给定区域设置的给定格式化样式的时间格式化程序。
      参数:
      style - 给定的格式化样式。例如，在美国区域设置中，SHORT表示"h:mm a"。
      aLocale - 给定的区域设置。
      返回:
      一个时间格式化程序。

    • getDateInstance

      public static final DateFormat getDateInstance()
      获取默认FORMAT区域设置的默认格式化样式的日期格式化程序。 getDateInstance(DEFAULT, Locale.getDefault(Locale.Category.FORMAT))。

      返回:
      一个日期格式化程序。
      参见:

    • getDateInstance

      public static final DateFormat getDateInstance(int style)
      获取默认FORMAT区域设置的给定格式化样式的日期格式化程序。 getDateInstance(style, Locale.getDefault(Locale.Category.FORMAT))。

      参数:
      style - 给定的格式化样式。例如，在美国区域设置中，SHORT表示"M/d/yy"。
      返回:
      一个日期格式化程序。
      参见:

    • getDateInstance

      public static final DateFormat getDateInstance(int style, Locale aLocale)
      获取给定区域设置的给定格式化样式的日期格式化程序。
      参数:
      style - 给定的格式化样式。例如，在美国区域设置中，SHORT表示"M/d/yy"。
      aLocale - 给定的区域设置。
      返回:
      一个日期格式化程序。

    • 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区域设置的日期/时间格式化程序。

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

      参数：
      dateStyle - 给定的日期格式样式。例如，在美国区域中，"M/d/yy"对应SHORT。
      timeStyle - 给定的时间格式样式。例如，在美国区域中，"h:mm a"对应SHORT。
      返回：
      日期/时间格式化程序。
      另请参阅：

    • getDateTimeInstance

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

    • getInstance

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

    • getAvailableLocales

      public static Locale[] getAvailableLocales()
      返回所有区域设置的数组，该数组表示此类的get*Instance方法可以返回本地化实例的并集。返回的数组代表Java运行时和已安装的DateFormatProvider实现支持的区域设置的并集。至少，返回的数组必须包含等于Locale.ROOT和等于Locale.US的Locale实例。
      返回：
      可用于本地化DateFormat实例的区域设置数组。

    • setCalendar

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

      之前设置的任何TimeZone和leniency值将被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调用覆盖。

      此方法设置的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();
      返回：
      如果calendar是宽松的，则为true；否则为false。
      另请参阅：

    • hashCode

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

    • equals

      public boolean equals(Object obj)
      重写equals
      重写：
      equals 在类 Object中
      参数：
      obj - 要比较的引用对象。
      返回：
      如果此对象与obj参数相同，则为true；否则为false。
      另请参阅：

    • clone

      public Object clone()
      重写Cloneable
      重写：
      clone 在类 Format中
      返回：
      此实例的克隆。
      另请参阅：