Module  java.base
软件包  java.text

Class DateFormat

  • All Implemented Interfaces:
    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);

    您也可以使用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的日期/时间格式。
        另请参见：
        Constant Field Values

      • YEAR_FIELD

        public static final int YEAR_FIELD
        YEAR场对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • MONTH_FIELD

        public static final int MONTH_FIELD
        MONTH字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • DATE_FIELD

        public static final int DATE_FIELD
        DATE字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • 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。
        另请参见：
        Constant Field Values

      • 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。
        另请参见：
        Constant Field Values

      • MINUTE_FIELD

        public static final int MINUTE_FIELD
        MINUTE字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • SECOND_FIELD

        public static final int SECOND_FIELD
        有用的常数用于SECOND场对齐。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • MILLISECOND_FIELD

        public static final int MILLISECOND_FIELD
        MILLISECOND字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • DAY_OF_WEEK_FIELD

        public static final int DAY_OF_WEEK_FIELD
        DAY_OF_WEEK字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • DAY_OF_YEAR_FIELD

        public static final int DAY_OF_YEAR_FIELD
        DAY_OF_YEAR字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • DAY_OF_WEEK_IN_MONTH_FIELD

        public static final int DAY_OF_WEEK_IN_MONTH_FIELD
        DAY_OF_WEEK_IN_MONTH字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • WEEK_OF_YEAR_FIELD

        public static final int WEEK_OF_YEAR_FIELD
        WEEK_OF_YEAR字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • WEEK_OF_MONTH_FIELD

        public static final int WEEK_OF_MONTH_FIELD
        WEEK_OF_MONTH字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • AM_PM_FIELD

        public static final int AM_PM_FIELD
        AM_PM字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • HOUR1_FIELD

        public static final int HOUR1_FIELD
        基于一个HOUR字段对齐的常用常数。 用于FieldPosition的日期/时间格式。 HOUR1_FIELD用于基于1个12小时制的时钟。 例如，11:30 PM + 1小时结果在12:30 AM。
        另请参见：
        Constant Field Values

      • HOUR0_FIELD

        public static final int HOUR0_FIELD
        基于零的HOUR场对齐的有用常数。 用于FieldPosition的日期/时间格式。 HOUR0_FIELD用于零基12小时制。 例如，上午11:30 PM + 1小时结果是00:30 AM。
        另请参见：
        Constant Field Values

      • TIMEZONE_FIELD

        public static final int TIMEZONE_FIELD
        TIMEZONE字段对齐的常用常数。 用于FieldPosition的日期/时间格式。
        另请参见：
        Constant Field Values

      • MEDIUM

        public static final int MEDIUM
        中等风格图案的常数。
        另请参见：
        Constant Field Values

      • DEFAULT

        public static final int DEFAULT
        常数为默认样式模式。 其值为MEDIUM。
        另请参见：
        Constant Field Values

    • 构造方法详细信息

      • DateFormat

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

    • 方法详细信息

      • format

        public final StringBuffer format​(Object obj,
                                 StringBuffer toAppendTo,
                                 FieldPosition fieldPosition)
        覆盖格式。 将时间对象格式化成时间字符串。 时间对象的示例是以毫秒为单位的时间值和Date对象。
        Specified by:
        format在 Format
        参数
        obj - 必须是数字或日期。
        toAppendTo - 返回时间字符串的字符串缓冲区。
        fieldPosition - 跟踪返回字符串中字段的位置。 在输入：对齐字段，如果需要。 输出：对齐字段的偏移量。 例如，给定时间文本“1996.07.10 AD在15:08:56 PDT”，如果给定的fieldPosition为DateFormat.YEAR_FIELD，则fieldPosition的起始索引和结束索引将分别设置为0和4。 请注意，如果相同的时间字段在模式中出现多次，则fieldPosition将被设置为该时间字段的第一个出现。 例如，使用模式“haz（zzzz）”和对齐字段DateFormat.TIMEZONE_FIELD将日期格式化为时间字符串“1 PM PDT（太平洋夏令时）”，fieldPosition的起始索引和结束索引将设置为5和8，分别是时区模式字符“z”的第一次出现。
        结果
        字符串缓冲区以forAppendTo传递，并附加了格式化的文本。
        异常
        IllegalArgumentException - 如果 Format无法格式化给定的 obj 。
        另请参见：
        Format

      • format

        public abstract StringBuffer format​(Date date,
                                    StringBuffer toAppendTo,
                                    FieldPosition fieldPosition)
        将日期格式化成日期/时间字符串。
        参数
        date - 要格式化为日期/时间字符串的日期。
        toAppendTo - 返回日期/时间字符串的字符串缓冲区。
        fieldPosition - 跟踪返回字符串中字段的位置。 在输入：对齐字段，如果需要。 输出：对齐字段的偏移量。 例如，给定时间文本“1996.07.10 AD在15:08:56 PDT”，如果给定的fieldPosition为DateFormat.YEAR_FIELD，则fieldPosition的起始索引和结束索引将分别设置为0和4。 请注意，如果相同的时间字段在模式中出现多次，则fieldPosition将被设置为该时间字段的第一个出现。 例如，使用模式“haz（zzzz）”和对齐字段DateFormat.TIMEZONE_FIELD将日期格式化为时间字符串“1 PM PDT（太平洋夏令时）”，fieldPosition的起始索引和结束索引将设置为5和8，分别是时区模式字符“z”的第一次出现。
        结果
        字符串缓冲区以forAppendTo传递，并附加了格式化的文本。

      • format

        public final String format​(Date date)
        将日期格式化成日期/时间字符串。
        参数
        date - 要格式化为时间字符串的时间值。
        结果
        格式化的时间字符串。

      • parse

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

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

        参数
        source - A String其开头应该被解析。
        结果
        A 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 - 输入时，开始解析的位置; 输出，解析终止的位置，或解析失败时的起始位置。
        结果
        A 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 -A ParsePosition具有如上所述的索引和错误索引信息的对象。
        结果
        A Date从字符串中解析。 万一出错，返回null。
        异常
        NullPointerException - 如果 source或 pos为空。

      • getTimeInstance

        public static final DateFormat getTimeInstance​(int style,
                                               Locale aLocale)
        获取给定区域设置的给定格式化样式的时间格式化程序。
        参数
        style - 给定的格式化样式。 例如，美国地区的“h：mm a”的短路。
        aLocale - 给定的区域设置。
        结果
        时间格式化

      • getDateInstance

        public static final DateFormat getDateInstance​(int style,
                                               Locale aLocale)
        获取给定区域设置的给定格式化样式的日期格式化程序。
        参数
        style - 给定的格式化样式。 例如，美国地区的“M / d / yy”短路。
        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方法可以返回本地化实例。 返回的数组表示由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可能会由于调用parse方法而被覆盖。

        参数
        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​()
        覆盖可克隆
        重写：
        clone在 Format
        结果
        这个实例的一个克隆。
        另请参见：
        Cloneable