模块  java.base
软件包  java.text

Class DateFormat

  • 实现的所有接口
    SerializableCloneable
    已知直接子类:
    SimpleDateFormat

    public abstract class DateFormat
    extends Format
    DateFormat是日期/时间格式化子类的抽象类,它以与语言无关的方式格式化和分析日期或时间。 日期/时间格式化子类(例如SimpleDateFormat )允许格式化(即,日期→文本),解析(文本“日期”)和规范化。 日期表示为Date对象或自1970年1月1日00:00:00 GMT以来的毫秒数。

    DateFormat提供了许多类方法,用于根据默认或给定的区域设置和多种格式样式获取默认日期/时间格式化程序。 格式化风格包括FULLLONGMEDIUMSHORT 在方法描述中提供了更多细节和使用这些样式的示例。

    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获取日期和时间格式。 您可以向这些工厂方法传递不同的选项以控制结果的长度; SHORTMEDIUMLONGFULL 确切的结果取决于区域设置,但通常:

    • SHORT是完全数字,例如12.13.523:30pm
    • MEDIUM更长,例如Jan 12, 1952
    • LONG更长,例如January 12, 19523:30:32pm
    • FULL是完全指定的,例如Tuesday, April 12, 1952 AD or 3:30:42pm PST

    如果需要,您还可以在格式上设置时区。 如果你想在格式或分析更精确的控制,(或者希望给用户更多的控制),可以尝试铸造DateFormat ,你从工厂方法到获得SimpleDateFormat 这对大多数国家都有效; 只要记住把它放在一个try块中,万一你遇到一个不寻常的块。

    您还可以使用ParsePositionFieldPosition的解析和格式化方法的形式,以允许您

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

    Synchronization

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

    实现要求:
    从以下版本开始:
    1.1
    另请参见:
    FormatNumberFormatSimpleDateFormatCalendarGregorianCalendarTimeZoneSerialized 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 - 必须是 DateNumber表示距离 Epoch毫秒的偏移量。
        toAppendTo - 返回日期时间字符串的字符串缓冲区。
        fieldPosition - 跟踪返回字符串中字段的位置。 例如,给定日期时间文本"1996.07.10 AD at 15:08:56 PDT" ,如果给定的fieldPositionYEAR_FIELD ,则开始索引和结束索引fieldPosition将分别设置为0和4。 请注意,如果相同的日期时间字段在模式中出现多次,则将为该日期时间字段的第一次出现设置fieldPosition 例如,对于第一次出现的时区模式字符,使用模式"h a z (zzzz)"和对齐字段TIMEZONE_FIELDDate格式化为日期时间字符串"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" ,如果给定的fieldPositionYEAR_FIELD ,则开始索引和结束索引fieldPosition将分别设置为0和4。 请注意,如果相同的日期时间字段在模式中出现多次,则将为该日期时间字段的第一次出现设置fieldPosition 例如,对于第一次出现的时区模式字符,使用模式"h a z (zzzz)"和对齐字段TIMEZONE_FIELDDate格式化为日期时间字符串"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 Datenull
      • 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 - 如果 sourcepos为空。
      • 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)
        设置此日期格式使用的日历。 最初,使用指定或默认语言环境的默认日历。

        之前设置的任何TimeZoneleniency值都将被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