模块  java.base
软件包  java.text

Class 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可帮助您格式化和解析任何区域设置的日期。 您的代码可以完全独立于几个月，一周中的日期，甚至是日历格式的区域设置约定：月球与太阳能。

    要格式化当前Locale的日期，请使用以下静态工厂方法之一： 

    
 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 extensions ，则会覆盖日历，国家/地区和/或格式化时区。 如果同时指定了“ca”和“rg”，则“ca”扩展名中的日历将取代“rg”扩展名中的隐式日历。

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

    
 myDate = df.parse(myString);

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

    • 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的解析和格式化方法的形式，以允许您

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

    Synchronization

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

    实现要求：
    从以下版本开始：
    1.1
    另请参见：
    Format ， NumberFormat ， SimpleDateFormat ， Calendar ， GregorianCalendar ， TimeZone ， Serialized Form

    • 字段详细信息

      • calendar

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

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

      • 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用于基于1的12小时制。 例如，11：30 PM + 1小时结果在12:30 AM。
        另请参见：
        常数字段值

      • HOUR0_FIELD

        public static final int HOUR0_FIELD
        基于零的HOUR场对齐的有用常量。 用于FieldPosition的日期/时间格式。 HOUR0_FIELD用于从零开始的12小时制。 例如，晚上11:30 + 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。
        另请参见：
        常数字段值

    • 构造方法详细信息

      • DateFormat

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

    • 方法详细信息

      • format

        public final StringBuffer format​(Object obj,
                                 StringBuffer toAppendTo,
                                 FieldPosition fieldPosition)
        将给定的Object为日期时间字符串。 格式化的字符串将附加到给定的StringBuffer 。
        Specified by:
        format在课程 Format
        参数
        obj - 必须是 Date或 Number表示距离 Epoch毫秒的偏移量。
        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

      • 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 ，相当于Date(837039900000L) 。

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

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

        参数
        source - 要解析的日期/时间字符串
        pos - 输入时，开始解析的位置; on output，解析终止的位置，或解析失败时的起始位置。
        结果
        如果无法解析输入， null Date或 null

      • parseObject

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

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

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

        Specified by:
        parseObject在课程 Format
        参数
        source - A String ，其中一部分应该被解析。
        pos - 具有 ParsePosition索引和错误索引信息的 ParsePosition对象。
        结果
        从字符串解析的Date 。 如果出现错误，则返回null。
        异常
        NullPointerException - 如果 source或 pos为空。

      • getTimeInstance

        public static final DateFormat getTimeInstance​(int style,
                                               Locale aLocale)
        获取具有给定语言环境的给定格式样式的时间格式化程序。
        参数
        style - 给定的格式样式。 例如，SHORT表示美国语言环境中的“h：mm a”。
        aLocale - 给定的语言环境。
        结果
        时间格式器。

      • getDateInstance

        public static final DateFormat getDateInstance​(int style,
                                               Locale aLocale)
        获取具有给定语言环境的给定格式样式的日期格式化程序。
        参数
        style - 给定的格式样式。 例如，美国语言环境中的“M / d / yy”为SHORT。
        aLocale - 给定的语言环境。
        结果
        日期格式化程序。

      • 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方法可以get*Instance返回本地化实例。 返回的数组表示Java运行时和已安装的DateFormatProvider实现支持的语言环境的并集 。 它必须至少包含Locale实例，等于Locale.US 。
        结果
        可为其提供本地化 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 ，解析是宽松的
        另请参见：
        Calendar.setLenient(boolean)

      • isLenient

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

      • equals

        public boolean equals​(Object obj)
        覆盖等于
        重写：
        equals在课程 Object
        参数
        obj - 要与之比较的引用对象。
        结果
        true如果此对象与obj参数相同; 否则为false 。
        另请参见：
        Object.hashCode() ， HashMap

      • clone

        public Object clone()
        覆盖Cloneable
        重写：
        clone在课程 Format
        结果
        这个实例的克隆。
        另请参见：
        Cloneable