模块 java.base
包 java.text

类 SimpleDateFormat

java.lang.Object
java.text.Format
java.text.DateFormat
java.text.SimpleDateFormat
所有已实现的接口：
Serializable , Cloneable
public class SimpleDateFormat extends DateFormat
SimpleDateFormat 是以locale敏感的方式格式化和解析日期的具体类。它允许格式化（日期→文本）、解析（文本→日期）和规范化。

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

日期和时间模式

日期和时间格式由 date and time pattern 字符串指定。在日期和时间模式字符串中，从 'A' 到 'Z' 以及从 'a' 到 'z' 的未加引号的字母被解释为代表日期或时间字符串组件的模式字母。可以使用单引号 (') 引用文本以避免解释。 "''" 代表单引号。不解释所有其他字符；它们在格式化期间被简单地复制到输出字符串中，或者在解析期间与输入字符串匹配。

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

图表显示模式字母、日期/时间组件、演示文稿和示例。
Letter 日期或时间组件 推介会 示例
G 代号 Text AD
y Year Year 1996； 96
Y 周年 Year 2009 ； 09
M 一年中的月份（上下文敏感） Month July； Jul； 07
L 一年中的月份（独立形式） Month July； Jul； 07
w 一年中的一周 Number 27
W 一个月中的一周 Number 2
D 一年中的某一天 Number 189
d 一个月中的第几天 Number 10
F 一个月中的星期几 Number 2
E 星期中的日期名称 Text Tuesday ； Tue
u 星期几（1 = 星期一，...，7 = 星期日） Number 1
a 上午/下午标记 Text PM
H 一天中的小时数 (0-23) Number 0
k 一天中的小时 (1-24) Number 24
K 上午/下午的小时 (0-11) Number 0
h 上午/下午的时间 (1-12) Number 12
m 小时中的分钟 Number 30
s 分秒秒 Number 55
S 毫秒 Number 978
z 时区 一般时区 Pacific Standard Time ； PST ； GMT-08:00
Z 时区 RFC 822 时区 -0800
X 时区 ISO 8601 时区 -08 ； -0800 ； -08:00
模式字母通常会重复出现，因为它们的数量决定了确切的呈现方式：
  • Text: 格式化时，如果模式字母的数量为4个或更多，则使用完整形式；否则，如果可用，将使用简短或缩写的形式。对于解析，两种形式都被接受，与模式字母的数量无关。

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

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

    如果指定了周年 'Y' 并且 calendar 不支持任何 周年 ，则使用日历年 ('y')。可以通过调用 getCalendar() .isWeekDateSupported() 来测试对周年的支持。

  • Month: 如果模式字母的数量为 3 个或更多，则月份被解释为 text ；否则，它被解释为 数字 。
    • 字母 M 生成上下文相关的月份名称，例如名称的嵌入形式。字母 M 是上下文相关的，因为当它用于独立模式时，例如“MMMM”，它给出月份名称的独立形式，当它用于包含其他字段的模式时，例如，“d MMMM”，它给出了月份名称的格式形式。例如，加泰罗尼亚语中的 January 在格式形式中是“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 标准的基本拉丁语块。

    对于解析，RFC 822 时区 也被接受。

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

    对于解析，一般时区 也被接受。

  • ISO 8601 Time zone: 模式字母的数量指定用于格式化和解析的格式，如下所示： 
       ISO8601TimeZone:
       OneLetterISO8601TimeZone
       TwoLetterISO8601TimeZone
       ThreeLetterISO8601TimeZone
   OneLetterISO8601TimeZone:
       Sign TwoDigitHours
       Z 
   TwoLetterISO8601TimeZone:
       Sign TwoDigitHours Minutes
       Z 
   ThreeLetterISO8601TimeZone:
       Sign TwoDigitHours : Minutes
       Z
    其他定义与 一般时区 或 RFC 822 时区 相同。

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

    对于解析，"Z" 被解析为 UTC 时区指示符。 一般时区 被 not 接受。

    如果模式字母的数量为 4 个或更多，则在构造 SimpleDateFormat 或 应用模式 时抛出 IllegalArgumentException 。

SimpleDateFormat 还支持 localized date and time pattern 字符串。在这些字符串中，上述模式字母可以替换为其他依赖于区域设置的模式字母。 SimpleDateFormat 不处理模式字母以外的文本本地化；这取决于类的客户端。

示例

以下示例显示了在美国locale中如何解释日期和时间模式。给定的日期和时间是美国太平洋时间时区的当地时间 2001-07-04 12:08:56。
在美国locale中解释的日期和时间模式示例
日期和时间模式 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

同步化

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

API 注意：
考虑使用 DateTimeFormatter 作为不可变且线程安全的替代方案。
自从：
1.1
参见：

  • 构造方法详细信息

    • SimpleDateFormat

      public SimpleDateFormat()
      使用默认 FORMAT 区域设置的默认模式和日期格式符号构造 SimpleDateFormat。笔记：此构造函数可能不支持所有locale。要全面覆盖，请使用 DateFormat 类中的工厂方法。

    • SimpleDateFormat

      public SimpleDateFormat(String  pattern)
      使用给定的模式和默认 FORMAT locale的默认日期格式符号构造一个 SimpleDateFormat。笔记：此构造函数可能不支持所有locale。要全面覆盖，请使用 DateFormat 类中的工厂方法。

      这相当于调用 SimpleDateFormat(pattern, Locale.getDefault(Locale.Category.FORMAT)) 。

      参数：
      pattern - 描述日期和时间格式的模式
      抛出：
      NullPointerException - 如果给定模式为空
      IllegalArgumentException - 如果给定的模式无效
      参见：

    • SimpleDateFormat

      public SimpleDateFormat(String  pattern, Locale  locale)
      使用给定模式和给定locale的默认日期格式符号构造一个 SimpleDateFormat。笔记：此构造函数可能不支持所有locale。要全面覆盖，请使用 DateFormat 类中的工厂方法。
      参数：
      pattern - 描述日期和时间格式的模式
      locale - 应使用其日期格式符号的locale
      抛出：
      NullPointerException - 如果给定的模式或locale为空
      IllegalArgumentException - 如果给定的模式无效

    • SimpleDateFormat

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

  • 方法详情

    • set2DigitYearStart

      public void set2DigitYearStart(Date  startDate)
      设置 100 年期限，两位数的年份将被解释为从用户指定的日期开始。
      参数：
      startDate - 在解析期间，两位数的年份将被放置在 startDate 到 startDate + 100 years 的范围内。
      抛出：
      NullPointerException - 如果 startDate 是 null。
      自从：
      1.2
      参见：

    • get2DigitYearStart

      public Date  get2DigitYearStart()
      返回 100 年期间的开始日期，两位数的年份被解释为在其中。
      返回：
      解析两位数年份的 100 年期间的开始
      自从：
      1.2
      参见：

    • format

      public StringBuffer  format(Date  date, StringBuffer  toAppendTo, FieldPosition  pos)
      将给定的 Date 格式化为日期/时间字符串并将结果附加到给定的 StringBuffer 。
      指定者：
      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 构建结果字符串，以及确定关于结果字符串的信息。

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

      重写：
      formatToCharacterIterator 在类 Format 中
      参数：
      obj - 要格式化的对象
      返回：
      描述格式化值的 AttributedCharacterIterator。
      抛出：
      NullPointerException - 如果 obj 为空。
      IllegalArgumentException - 如果 Format 无法格式化给定的对象，或者如果 Format 的模式字符串无效。
      自从：
      1.4

    • parse

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

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

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

      指定者：
      parse 在类 DateFormat 中
      参数：
      text - 一个 String ，其中的一部分应该被解析。
      pos - 具有如上所述的索引和错误索引信息的 ParsePosition 对象。
      返回：
      从字符串中解析出的 Date。如果出现错误，则返回 null。
      抛出：
      NullPointerException - 如果 text 或 pos 为空。

    • toPattern

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

    • toLocalizedPattern

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

    • applyPattern

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

    • applyLocalizedPattern

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

    • getDateFormatSymbols

      public DateFormatSymbols  getDateFormatSymbols()
      获取此日期格式的日期和时间格式符号的副本。
      返回：
      此日期格式的日期和时间格式符号
      参见：

    • setDateFormatSymbols

      public void setDateFormatSymbols(DateFormatSymbols  newFormatSymbols)
      设置此日期格式的日期和时间格式符号。
      参数：
      newFormatSymbols - 新的日期和时间格式符号
      抛出：
      NullPointerException - 如果给定的 newFormatSymbols 为空
      参见：

    • clone

      public Object  clone()
      创建此 SimpleDateFormat 的副本。这也会克隆格式的日期格式符号。
      重写：
      clone 在类 DateFormat 中
      返回：
      这个SimpleDateFormat的克隆
      参见：

    • hashCode

      public int hashCode()
      返回此 SimpleDateFormat 对象的哈希码值。
      重写：
      hashCode 在类 DateFormat 中
      返回：
      此 SimpleDateFormat 对象的哈希码值。
      参见：

    • equals

      public boolean equals(Object  obj)
      比较给定对象与 this SimpleDateFormat 是否相等。
      重写：
      equals 在类 DateFormat 中
      参数：
      obj - 要比较的参考对象。
      返回：
      如果给定对象等于此 SimpleDateFormat，则为真
      参见：