模块  java.base
软件包  java.text

Class SimpleDateFormat

  • 实现的所有接口
    Serializable ， Cloneable 
    public class SimpleDateFormatextends DateFormat
    SimpleDateFormat是一个用于以区域设置敏感的方式格式化和解析日期的具体类。 它允许格式化（日期→文本），解析（文本→日期）和规范化。

    SimpleDateFormat允许您从为日期时间格式选择任何用户定义的模式开始。 不过，建议您创建一个日期-时间格式有两种getTimeInstance ， getDateInstance ，或getDateTimeInstance在DateFormat 。 这些类方法中的每一个都可以返回使用默认格式模式初始化的日期/时间格式化程序。 您可以根据需要使用applyPattern方法修改格式模式。 有关使用这些方法的更多信息，请参见DateFormat 。

    日期和时间模式

    日期和时间格式由日期和时间模式字符串指定。 在日期和时间模式字符串中，从'A'到'Z'以及从'a'到'z'未加引号的字母被解释为表示日期或时间字符串的组成部分的模式字母。 可以使用单引号（ ' ）引用文本以避免解释。 "''"代表单引号。 不解释所有其他字符; 它们只是在格式化过程中被复制到输出字符串中，或者在解析过程中与输入字符串匹配。

    定义了以下模式字母（从'A'到'Z'以及从'a'到'z'所有其他字符都是保留的）：

    Chart shows pattern letters, date/time component, presentation, and examples.
    Letter Date or Time Component Presentation Examples
    G Era designator Text AD
    y Year Year 1996; 96
    Y Week year Year 2009; 09
    M Month in year (context sensitive) Month July; Jul; 07
    L Month in year (standalone form) Month July; Jul; 07
    w Week in year Number 27
    W Week in month Number 2
    D Day in year Number 189
    d Day in month Number 10
    F Day of week in month Number 2
    E Day name in week Text Tuesday; Tue
    u Day number of week (1 = Monday, ..., 7 = Sunday) Number 1
    a Am/pm marker Text PM
    H Hour in day (0-23) Number 0
    k Hour in day (1-24) Number 24
    K Hour in am/pm (0-11) Number 0
    h Hour in am/pm (1-12) Number 12
    m Minute in hour Number 30
    s Second in minute Number 55
    S Millisecond Number 978
    z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
    Z Time zone RFC 822 time zone -0800
    X Time zone ISO 8601 time zone -08; -0800; -08:00
    模式字母通常会重复，因为它们的数字决定了确切的呈现方式：
    • Text:格式化，如果模式字母数为4或更多，则使用完整格式; 否则，如果可用，则使用简短或缩写形式。 对于解析，两种形式都被接受，与模式字母的数量无关。

    • Number:对于格式化，模式字母的数量是最小位数，较短的数字是零填充到此数量。 对于解析，除非需要分隔两个相邻字段，否则将忽略模式字母的数量。

    • Year:如果格式化程序的Calendar是公历，则应用以下规则。
      • 对于格式化，如果模式字母的数量为2，则年份被截断为2位数; 否则它被解释为number 。
      • 对于解析，如果模式字母的数量大于2，则无论数字位数如何，都按字面解释年份。 所以使用“MM / dd / yyyy”模式，“01/11/12”解析到公元12年1月11日
      • 对于使用缩写年份模式（“y”或“yy”）进行解析， SimpleDateFormat必须解释相对于某个世纪的缩写年份。 它通过将日期调整为创建SimpleDateFormat实例之前的80年和之后的20年来实现此SimpleDateFormat 。 例如，使用1997年1月1日创建的“MM / dd / yy”模式和SimpleDateFormat实例，字符串“01/11/12”将被解释为2012年1月11日，而字符串“05/04 / 64“将被解释为1964年5月4日。在解析期间，只有由Character.isDigit(char)定义的正好两位数组成的字符串将被解析为默认世纪。 字面上解释任何其他数字字符串，例如一位数字符串，三位或更多位数字符串，或不是所有数字的两位数字符串（例如，“ - 1”）。 所以使用相同的模式解析“01/02/3”或“01/02/003”，如公元1月2日。 同样，“01/02 / -3”被解析为公元前1月2日。
      否则，将应用日历系统特定表单。 对于格式化和解析，如果模式字母的数量为4或更多，则使用特定于日历的long form 。 否则，使用特定于日历的short or abbreviated form 。

      如果指定周年'Y'且calendar不支持任何week years ，则使用日历年（ 'y' ）。 可以通过致电getCalendar()测试一周的支持。 isWeekDateSupported() 。

    • Month:如果模式字母的数量为3或更多，则月份将被解释为text ; 否则，它被解释为number 。
      • 字母M生成上下文敏感的月份名称，例如嵌入的名称形式。 字母M在上下文中是敏感的，当它在独立模式中使用时，例如“MMMM”，它给出了月份名称的独立形式，并且当它在包含其他字段的模式中使用时，例如，“d MMMM”，它给出了月份名称的格式形式。 例如，加泰罗尼亚语中的1月是格式形式的“de gener”，而它是独立形式的“gener”。 在这种情况下，“MMMM”将产生“gener”，而“d MMMM”的月份部分将产生“de gener”。 如果DateFormatSymbols已经与构造明确设置SimpleDateFormat(String,DateFormatSymbols)或方法setDateFormatSymbols(DateFormatSymbols) ，由给定月份名称DateFormatSymbols使用。
      • 字母L生成独立形式的月份名称。

    • General time zone:如果时区有名称，则解释为text 。 对于表示GMT偏移值的时区，使用以下语法： 
        GMTOffsetTimeZone:             GMT Sign Hours : Minutes     Sign: one of             + -     Hours:             Digit             Digit Digit     Minutes:             Digit Digit     Digit: one of             0 1 2 3 4 5 6 7 8 9
      小时数必须介于0到23之间， 分钟数必须介于00和59之间。格式与区域设置无关，数字必须取自Unicode标准的Basic Latin块。

      对于解析，也接受RFC 822 time zones 。

    • RFC 822 time zone:格式化时，使用RFC 822 4位时区格式： 
        RFC822TimeZone:             Sign TwoDigitHours Minutes     TwoDigitHours:             Digit Digit
      TwoDigitHours必须介于00和23之间。其他定义与general time zones相同 。

      对于解析，也接受general time zones 。

    • ISO 8601 Time zone:模式字母的数量指定格式化和解析的格式，如下所示： 
        ISO8601TimeZone:             OneLetterISO8601TimeZone             TwoLetterISO8601TimeZone             ThreeLetterISO8601TimeZone     OneLetterISO8601TimeZone:             Sign TwoDigitHours             Z     TwoLetterISO8601TimeZone:             Sign TwoDigitHours Minutes             Z     ThreeLetterISO8601TimeZone:             Sign TwoDigitHours : Minutes             Z
      其他定义如general time zones或RFC 822 time zones 。

      对于格式化，如果GMT的偏移值为0，则生成"Z" 。 如果模式字母的数量为1，则忽略任何小时的一小时。 例如，如果模式为"X"且时区为"GMT+05:30" ， "+05"生成"+05" 。

      对于解析， "Z"被解析为UTC时区指示符。 不接受General time zones 。

      如果模式字母的数目是4或更多， IllegalArgumentException被构建时抛出SimpleDateFormat或applying a pattern 。

    SimpleDateFormat还支持本地化的日期和时间模式字符串。 在这些字符串中，上述模式字母可以用其他依赖于语言环境的模式字母替换。 SimpleDateFormat不处理模式字母以外的文本本地化; 这取决于班级的客户。

    例子

    以下示例显示如何在美国语言环境中解释日期和时间模式。 给定的日期和时间是2001-07-04 12:08:56在美国太平洋时间的当地时间。
    Examples of date and time patterns interpreted in the U.S. locale
    Date and Time Pattern Result
    "yyyy.MM.dd G 'at' HH:mm:ss z" 2001.07.04 AD at 12:08:56 PDT
    "EEE, MMM d, ''yy" Wed, Jul 4, '01
    "h:mm a" 12:08 PM
    "hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
    "K:mm a, z" 0:08 PM, PDT
    "yyyyy.MMMMM.dd GGG hh:mm aaa" 02001.July.04 AD 12:08 PM
    "EEE, d MMM yyyy HH:mm:ss Z" Wed, 4 Jul 2001 12:08:56 -0700
    "yyMMddHHmmssZ" 010704120856-0700
    "yyyy-MM-dd'T'HH:mm:ss.SSSZ" 2001-07-04T12:08:56.235-0700
    "yyyy-MM-dd'T'HH:mm:ss.SSSXXX" 2001-07-04T12:08:56.235-07:00
    "YYYY-'W'ww-u" 2001-W27-3

    Synchronization

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

    从以下版本开始：
    1.1
    另请参见：
    Java Tutorial ， Calendar ， TimeZone ， DateFormat ， DateFormatSymbols ， Serialized Form

    • 构造方法详细信息

      • SimpleDateFormat

        public SimpleDateFormat()
        构造一个SimpleDateFormat使用默认模式和日期格式符号默认FORMAT区域设置。 注意：此构造函数可能不支持所有语言环境。 要获得完整覆盖，请使用DateFormat类中的工厂方法。

      • SimpleDateFormat

        public SimpleDateFormat​(String pattern,                        Locale locale)
        使用给定模式和给定语言环境的默认日期格式符号构造SimpleDateFormat 。 注意：此构造函数可能不支持所有语言环境。 要获得完整覆盖，请使用DateFormat类中的工厂方法。
        参数
        pattern - 描述日期和时间格式的模式
        locale - 应使用其日期格式符号的区域设置
        异常
        NullPointerException - 如果给定的模式或区域设置为null
        IllegalArgumentException - 如果给定的模式无效

      • SimpleDateFormat

        public SimpleDateFormat​(String pattern,                        DateFormatSymbols formatSymbols)
        使用给定的模式和日期格式符号构造 SimpleDateFormat 。
        参数
        pattern - 描述日期和时间格式的模式
        formatSymbols - 要用于格式化的日期格式符号
        异常
        NullPointerException - 如果给定的模式或formatSymbols为null
        IllegalArgumentException - 如果给定的模式无效

    • 方法详细信息

      • set2DigitYearStart

        public void set2DigitYearStart​(Date startDate)
        设置100年期间2位数年份将被解释为在用户指定的日期开始。
        参数
        startDate - 在解析期间，两位数年份将放在 startDate到 startDate + 100 years的范围内。
        异常
        NullPointerException - 如果 startDate是 null 。
        从以下版本开始：
        1.2
        另请参见：
        get2DigitYearStart()

      • get2DigitYearStart

        public Date get2DigitYearStart()
        返回100年期间的开始日期2位数年份被解释为在其中。
        结果
        解析两位数年份的100年期间的开始
        从以下版本开始：
        1.2
        另请参见：
        set2DigitYearStart(java.util.Date)

      • format

        public StringBuffer format​(Date date,                           StringBuffer toAppendTo,                           FieldPosition pos)
        将给定的 Date为日期/时间字符串，并将结果附加到给定的 StringBuffer 。
        Specified by:
        format在课程 DateFormat
        参数
        date - 要格式化为日期时间字符串的日期时间值。
        toAppendTo - 要附加新的日期时间文本。
        pos - 跟踪返回字符串中字段的位置。 例如，给定日期时间文本"1996.07.10 AD at 15:08:56 PDT" ，如果给定的fieldPosition是DateFormat.YEAR_FIELD ，则开始索引和结束索引fieldPosition将分别设置为0和4。 请注意，如果相同的日期时间字段在模式中出现多次，则将为该日期时间字段的第一次出现设置fieldPosition 。 例如，对于第一次出现的时区模式字符，使用模式"h a z (zzzz)"和对齐字段DateFormat.TIMEZONE_FIELD将Date格式化为日期时间字符串"1 PM PDT (Pacific Daylight Time)" ，将开始索引和结束索引fieldPosition分别设置为5和8 'z' 。
        结果
        格式化的日期时间字符串。
        异常
        NullPointerException - 如果任何参数是 null 。

      • formatToCharacterIterator

        public AttributedCharacterIterator formatToCharacterIterator​(Object obj)
        格式化一个生成AttributedCharacterIterator的对象。 您可以使用返回的AttributedCharacterIterator来构建生成的String，以及确定有关生成的String的信息。

        AttributedCharacterIterator的每个属性键的类型为DateFormat.Field ，其对应的属性值与属性键相同。

        重写：
        formatToCharacterIterator在课程 Format
        参数
        obj - 要格式化的对象
        结果
        AttributedCharacterIterator描述格式化的值。
        异常
        NullPointerException - 如果obj为null。
        IllegalArgumentException - 如果Format无法格式化给定对象，或者Format的模式字符串无效。
        从以下版本开始：
        1.4

      • parse

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

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

        此解析操作使用calendar生成Date 。 在解析之前，所有calendar的日期时间字段都是cleared ，并且calendar的日期时间字段的默认值用于任何缺少的日期时间信息。 例如，如果解析操作没有给出年份值，则解析的Date的年份值为1970， 其中 Date为GregorianCalendar 。 可能会覆盖TimeZone值，具体取决于给定的模式和text的时区值。 之前通过调用setTimeZone设置的任何TimeZone值可能需要恢复以进行进一步操作。

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

      • toPattern

        public String toPattern()
        返回描述此日期格式的模式字符串。
        结果
        描述此日期格式的模式字符串。

      • toLocalizedPattern

        public String toLocalizedPattern()
        返回描述此日期格式的本地化模式字符串。
        结果
        描述此日期格式的本地化模式字符串。

      • applyPattern

        public void applyPattern​(String pattern)
        将给定的模式字符串应用于此日期格式。
        参数
        pattern - 此日期格式的新日期和时间模式
        异常
        NullPointerException - 如果给定的模式为null
        IllegalArgumentException - 如果给定的模式无效

      • applyLocalizedPattern

        public void applyLocalizedPattern​(String pattern)
        将给定的本地化模式字符串应用于此日期格式。
        参数
        pattern - 要映射到此格式的新日期和时间格式模式的字符串
        异常
        NullPointerException - 如果给定的模式为null
        IllegalArgumentException - 如果给定的模式无效

      • setDateFormatSymbols

        public void setDateFormatSymbols​(DateFormatSymbols newFormatSymbols)
        设置此日期格式的日期和时间格式符号。
        参数
        newFormatSymbols - 新的日期和时间格式符号
        异常
        NullPointerException - 如果给定的newFormatSymbols为null
        另请参见：
        getDateFormatSymbols()

      • clone

        public Object clone()
        创建此SimpleDateFormat的副本。 这也克隆了格式的日期格式符号。
        重写：
        clone ，课程 DateFormat
        结果
        此 SimpleDateFormat
        另请参见：
        Cloneable

      • equals

        public boolean equals​(Object obj)
        比较给定对象与此 SimpleDateFormat是否相等。
        重写：
        equals在课程 DateFormat
        参数
        obj - 要与之比较的引用对象。
        结果
        如果给定对象等于此 SimpleDateFormat
        另请参见：
        Object.hashCode() ， HashMap