模块 java.base
包 java.text

类 MessageFormat

java.lang.Object
java.text.Format
java.text.MessageFormat
所有已实现的接口：
Serializable , Cloneable
public class MessageFormat extends Format
MessageFormat 提供了一种以语言中立的方式生成串联消息的方法。使用它来构造为最终用户显示的消息。

MessageFormat 获取一组对象，对它们进行格式化，然后将格式化后的字符串插入模式中适当的位置。

Note: MessageFormat 与其他 Format 类的不同之处在于您使用其构造函数之一创建 MessageFormat 对象（而不是使用 getInstance 样式工厂方法）。工厂方法不是必需的，因为 MessageFormat 本身不实现特定于locale的行为。任何特定于locale的行为都由您提供的模式以及用于插入参数的子格式定义。

模式及其解释

MessageFormat 使用以下形式的模式： 
 MessageFormatPattern:
     String
     MessageFormatPattern FormatElement String

 FormatElement:
     { ArgumentIndex }
     { ArgumentIndex , FormatType }
     { ArgumentIndex , FormatType , FormatStyle }

 FormatType: one of 
     number date time choice

 FormatStyle:
     short
     medium
     long
     full
     integer
     currency
     percent
     SubformatPattern

在一个String, 一对单引号可以用来引用除单引号之外的任意字符。例如，模式字符串 "'{0}'" 表示字符串 "{0}"，而不是FormatElement.单引号本身必须由双单引号 '' 表示String.例如，模式字符串 "'{''}'" 被解释为 '{（引号开始和左大括号）、''（单引号）和 }'（右大括号和引号结束）、not、'{' 和 '}'（被引用）的序列左右花括号）：代表字符串 "{'}" , not "{}" 。

A SubformatPattern由其相应的子格式解释，并且应用依赖于子格式的模式规则。例如，模式字符串 "{1,number,$'#',##}" (SubformatPattern带下划线）将生成带有引号的数字格式，结果如： "$#31,45"。有关详细信息，请参阅每个 Format 子类文档。

任何不匹配的报价在给定模式的末尾都被视为已关闭。例如，模式字符串 "'{0}" 被视为模式 "'{0}'"。

未引用模式中的任何花括号都必须平衡。例如，"ab {0} de" 和 "ab '}' de" 是有效模式，但 "ab {0'}' de"、"ab } de" 和 "''{''" 不是。

警告：
不幸的是，在消息格式模式中使用引号的规则有些令人困惑。特别是，对于本地化人员来说，单引号是否需要加倍并不总是很明显。确保将规则告知本地化人员，并告诉他们（例如，通过在资源包源文件中使用注解）哪些字符串将由 MessageFormat 处理。请注意，本地化人员可能需要在原始版本没有的翻译字符串中使用单引号。

这ArgumentIndexvalue 是使用数字 '0' 到 '9' 编写的非负整数，表示传递给 format 方法的 arguments 数组或 parse 方法返回的结果数组的索引。

这FormatType和FormatStyle值用于为格式元素创建 Format 实例。下表显示了值如何映射到 Format 实例。表中未显示的组合是非法的。 ASubformatPattern必须是所使用的 Format 子类的有效模式字符串。

显示 FormatType 和 FormatStyle 值如何映射到 Format 实例
FormatType FormatStyle 子格式创建
（没有任何） （没有任何） null
number （没有任何） NumberFormat.getInstance (getLocale())
integer NumberFormat.getIntegerInstance (getLocale())
currency NumberFormat.getCurrencyInstance (getLocale())
percent NumberFormat.getPercentInstance (getLocale())
SubformatPattern new DecimalFormat (subformatPattern, DecimalFormatSymbols.getInstance (getLocale()))
date （没有任何） DateFormat.getDateInstance ( DateFormat.DEFAULT , getLocale())
short DateFormat.getDateInstance ( DateFormat.SHORT , getLocale())
medium DateFormat.getDateInstance ( DateFormat.DEFAULT , getLocale())
long DateFormat.getDateInstance ( DateFormat.LONG , getLocale())
full DateFormat.getDateInstance ( DateFormat.FULL , getLocale())
SubformatPattern new SimpleDateFormat (subformatPattern, getLocale())
time （没有任何） DateFormat.getTimeInstance ( DateFormat.DEFAULT , getLocale())
short DateFormat.getTimeInstance ( DateFormat.SHORT , getLocale())
medium DateFormat.getTimeInstance ( DateFormat.DEFAULT , getLocale())
long DateFormat.getTimeInstance ( DateFormat.LONG , getLocale())
full DateFormat.getTimeInstance ( DateFormat.FULL , getLocale())
SubformatPattern new SimpleDateFormat (subformatPattern, getLocale())
choice SubformatPattern new ChoiceFormat (subformatPattern)

使用信息

下面是一些使用示例。在真正的国际化程序中，消息格式模式和其他静态字符串当然会从资源包中获取。其他参数将在运行时动态确定。

第一个示例使用静态方法 MessageFormat.format ，它在内部创建一个 MessageFormat 供一次性使用：

 int planet = 7;
 String event = "a disturbance in the Force";

 String result = MessageFormat.format(
   "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
   planet, new Date(), event);
输出是： 
 At 12:30 PM on Jul 3, 2053, there was a disturbance in the Force on planet 7.

以下示例创建了一个可以重复使用的 MessageFormat 实例：

 int fileCount = 1273;
 String diskName = "MyDisk";
 Object[] testArgs = {Long.valueOf(fileCount), diskName};

 MessageFormat form = new MessageFormat(
   "The disk \"{1}\" contains {0} file(s).");

 System.out.println(form.format(testArgs));
fileCount 具有不同值的输出： 
 The disk "MyDisk" contains 0 file(s).
 The disk "MyDisk" contains 1 file(s).
 The disk "MyDisk" contains 1,273 file(s).

对于更复杂的模式，您可以使用 ChoiceFormat 为单数和复数生成正确的形式：

 MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}.");
 double[] filelimits = {0,1,2};
 String[] filepart = {"no files","one file","{0,number} files"};
 ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart);
 form.setFormatByArgumentIndex(0, fileform);

 int fileCount = 1273;
 String diskName = "MyDisk";
 Object[] testArgs = {Long.valueOf(fileCount), diskName};

 System.out.println(form.format(testArgs));
fileCount 具有不同值的输出： 
 The disk "MyDisk" contains no files.
 The disk "MyDisk" contains one file.
 The disk "MyDisk" contains 1,273 files.

您可以通过编程方式创建 ChoiceFormat，如上例所示，或使用模式。有关详细信息，请参阅 ChoiceFormat 。


 form.applyPattern(
  "There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.");

Note: 正如我们在上面看到的，MessageFormat 中的 ChoiceFormat 生成的字符串被视为特殊字符串； '{' 的出现用于指示子格式，并导致递归。如果您以编程方式创建 MessageFormat 和 ChoiceFormat（而不是使用字符串模式），则请注意不要生成自身递归的格式，这将导致无限循环。

当单个参数在字符串中被解析多次时，最后一次匹配将是解析的最终结果。例如，

 MessageFormat mf = new MessageFormat("{0,number,#.##}, {0,number,#.#}");
 Object[] objs = {Double.valueOf(3.1415)};
 String result = mf.format( objs );
 // result now equals "3.14, 3.1"
 objs = mf.parse(result, new ParsePosition(0));
 // objs now equals {Double.valueOf(3.1)}

同样，使用包含多次出现的同一参数的模式对 MessageFormat 对象进行解析将返回最后一个匹配项。例如，

 MessageFormat mf = new MessageFormat("{0}, {0}, {0}");
 String forParsing = "x, y, z";
 Object[] objs = mf.parse(forParsing, new ParsePosition(0));
 // result now equals {new String("z")}

同步化

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

自从：
1.1
参见：

  • 构造方法详细信息

    • MessageFormat

      public MessageFormat(String  pattern)
      为默认的 FORMAT locale和指定的模式构造 MessageFormat。构造函数首先设置locale，然后解析模式并为其中包含的格式元素创建子格式列表。 类描述 中指定了模式及其解释。
      参数：
      pattern - 此消息格式的模式
      抛出：
      IllegalArgumentException - 如果模式无效
      NullPointerException - 如果 pattern 是 null

    • MessageFormat

      public MessageFormat(String  pattern, Locale  locale)
      为指定的locale和模式构造 MessageFormat。构造函数首先设置locale，然后解析模式并为其中包含的格式元素创建子格式列表。 类描述 中指定了模式及其解释。
      参数：
      pattern - 此消息格式的模式
      locale - 此消息格式的locale
      抛出：
      IllegalArgumentException - 如果模式无效
      NullPointerException - 如果 pattern 是 null
      自从：
      1.4

  • 方法详情

    • setLocale

      public void setLocale(Locale  locale)
      设置创建或比较子格式时要使用的locale。这会影响后续调用
      • 到 applyPattern 和 toPattern 方法，如果格式元素指定格式类型并因此在 applyPattern 方法中创建子格式，以及
      • 到 format 和 formatToCharacterIterator 方法，如果格式元素没有指定格式类型，因此在格式化方法中创建了子格式。
      已经创建的子格式不受影响。
      参数：
      locale - 创建或比较子格式时使用的locale

    • getLocale

      public Locale  getLocale()
      获取在创建或比较子格式时使用的locale。
      返回：
      创建或比较子格式时使用的locale

    • applyPattern

      public void applyPattern(String  pattern)
      设置此消息格式使用的模式。该方法解析模式并为其中包含的格式元素创建子格式列表。 类描述 中指定了模式及其解释。
      参数：
      pattern - 此消息格式的模式
      抛出：
      IllegalArgumentException - 如果模式无效
      NullPointerException - 如果 pattern 是 null

    • toPattern

      public String  toPattern()
      返回表示消息格式当前状态的模式。该字符串是根据内部信息构建的，因此不一定等于先前应用的模式。
      返回：
      表示消息格式当前状态的模式

    • setFormatsByArgumentIndex

      public void setFormatsByArgumentIndex(Format [] newFormats)
      设置用于传递给 format 方法或从 parse 方法返回的值的格式。 newFormats 中的元素索引对应于先前设置的模式字符串中使用的参数索引。因此，newFormats 中的格式顺序对应于传递给 format 方法的 arguments 数组或 parse 方法返回的结果数组中元素的顺序。

      如果参数索引用于模式字符串中的多个格式元素，则相应的新格式将用于所有此类格式元素。如果参数索引未用于模式字符串中的任何格式元素，则相应的新格式将被忽略。如果提供的格式少于所需的格式，则仅替换参数索引小于 newFormats.length 的格式。

      参数：
      newFormats - 使用的新格式
      抛出：
      NullPointerException - 如果 newFormats 为空
      自从：
      1.4

    • setFormats

      public void setFormats(Format [] newFormats)
      设置格式以用于先前设置的模式字符串中的格式元素。 newFormats 中的格式顺序对应于模式字符串中格式元素的顺序。

      如果提供的格式多于模式字符串所需的格式，则忽略其余格式。如果提供的格式比需要的少，则只替换前 newFormats.length 格式。

      由于模式字符串中格式元素的顺序在本地化过程中经常发生变化，因此通常最好使用 setFormatsByArgumentIndex 方法，该方法假定格式顺序对应于传递给 format 方法或结果数组的 arguments 数组中的元素顺序由 parse 方法返回。

      参数：
      newFormats - 使用的新格式
      抛出：
      NullPointerException - 如果 newFormats 为空

    • setFormatByArgumentIndex

      public void setFormatByArgumentIndex(int argumentIndex, Format  newFormat)
      设置用于先前设置的模式字符串中使用给定参数索引的格式元素的格式。参数索引是格式元素定义的一部分，表示传递给 format 方法的 arguments 数组或 parse 方法返回的结果数组的索引。

      如果参数索引用于模式字符串中的多个格式元素，则新格式将用于所有此类格式元素。如果参数索引未用于模式字符串中的任何格式元素，则忽略新格式。

      参数：
      argumentIndex - 使用新格式的参数索引
      newFormat - 使用的新格式
      自从：
      1.4

    • setFormat

      public void setFormat(int formatElementIndex, Format  newFormat)
      设置格式以用于先前设置的模式字符串中具有给定格式元素索引的格式元素。格式元素索引是格式元素的从零开始的编号，从模式字符串的开头开始计数。

      由于模式字符串中格式元素的顺序在本地化过程中经常发生变化，因此通常最好使用 setFormatByArgumentIndex 方法，该方法根据格式元素指定的参数索引访问格式元素。

      参数：
      formatElementIndex - 模式中格式元素的索引
      newFormat - 用于指定格式元素的格式
      抛出：
      ArrayIndexOutOfBoundsException - 如果 formatElementIndex 等于或大于模式字符串中格式元素的数量

    • getFormatsByArgumentIndex

      public Format [] getFormatsByArgumentIndex()
      获取用于传递到 format 方法或从 parse 方法返回的值的格式。返回数组中元素的索引对应于先前设置的模式字符串中使用的参数索引。因此，返回数组中的格式顺序对应于传递给 format 方法的 arguments 数组或 parse 方法返回的结果数组中元素的顺序。

      如果参数索引用于模式字符串中的多个格式元素，则在数组中返回用于最后一个此类格式元素的格式。如果参数索引未用于模式字符串中的任何格式元素，则数组中返回 null。

      返回：
      模式中用于参数的格式
      自从：
      1.4

    • getFormats

      public Format [] getFormats()
      获取用于先前设置的模式字符串中的格式元素的格式。返回数组中格式的顺序对应于模式字符串中格式元素的顺序。

      由于模式字符串中格式元素的顺序在本地化过程中经常发生变化，因此通常最好使用 getFormatsByArgumentIndex 方法，该方法假定格式顺序对应于传递给 format 方法的 arguments 数组中的元素顺序或返回的结果数组通过 parse 方法。

      返回：
      用于模式中格式元素的格式

    • format

      public final StringBuffer  format(Object [] arguments, StringBuffer  result, FieldPosition  pos)
      格式化对象数组并将 MessageFormat 的模式（格式元素由格式化对象替换）附加到提供的 StringBuffer 。

      替换单个格式元素的文本源自格式元素的当前子格式和格式元素参数索引处的 arguments 元素，如下表的第一匹配行所示。一个论点是不可用如果 arguments 是 null 或少于 argumentIndex+1 个元素。

      子格式、参数和格式化文本的示例
      子格式 参数 格式化文本
      任何 不可用 "{" + argumentIndex + "}"
      null "null"
      instanceof ChoiceFormat 任何 subformat.format(argument).indexOf('{') >= 0 ?
      (new MessageFormat(subformat.format(argument), getLocale())).format(argument) : subformat.format(argument)
      != null 任何 subformat.format(argument)
      null instanceof Number NumberFormat.getInstance(getLocale()).format(argument)
      instanceof Date DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)
      instanceof String argument
      任何 argument.toString()

      如果 pos 不为空，并且引用 Field.ARGUMENT ，则将返回第一个格式化字符串的位置。

      参数：
      arguments - 要格式化和替换的对象数组。
      result - 附加文本的位置。
      pos - 跟踪第一个替换参数在输出字符串中的位置。
      返回：
      作为 result 传入的字符串缓冲区，附加了格式化文本
      抛出：
      IllegalArgumentException - 如果 arguments 数组中的参数不是使用它的格式元素所期望的类型。
      NullPointerException - 如果 result 是 null

    • format

      public static String  format(String  pattern, Object ... arguments)
      创建具有给定模式的 MessageFormat 并使用它来格式化给定的参数。这相当于
      (new MessageFormat(pattern)).format(arguments, new StringBuffer(), null).toString()
      参数：
      pattern - 模式字符串
      arguments - 要格式化的对象
      返回：
      格式化的字符串
      抛出：
      IllegalArgumentException - 如果模式无效，或者如果 arguments 数组中的参数不是使用它的格式元素所期望的类型。
      NullPointerException - 如果 pattern 是 null

    • format

      public final StringBuffer  format(Object  arguments, StringBuffer  result, FieldPosition  pos)
      格式化对象数组并将 MessageFormat 的模式（格式元素由格式化对象替换）附加到提供的 StringBuffer 。这相当于
      format((Object[]) arguments, result, pos)
      指定者：
      format 在类 Format 中
      参数：
      arguments - 要格式化和替换的对象数组。
      result - 附加文本的位置。
      pos - 跟踪第一个替换参数在输出字符串中的位置。
      返回：
      作为 toAppendTo 传入的字符串缓冲区，附加了格式化文本
      抛出：
      IllegalArgumentException - 如果 arguments 数组中的参数不是使用它的格式元素所期望的类型。
      NullPointerException - 如果 result 是 null

    • formatToCharacterIterator

      public AttributedCharacterIterator  formatToCharacterIterator(Object  arguments)
      格式化一个对象数组并将它们插入到 MessageFormat 的模式中，生成一个 AttributedCharacterIterator 。您可以使用返回的 AttributedCharacterIterator 构建结果字符串，以及确定关于结果字符串的信息。

      返回的 AttributedCharacterIterator 的文本与返回的文本相同

      format(arguments, new StringBuffer(), null).toString()

      此外，AttributedCharacterIterator 至少包含指示文本从 arguments 数组中的参数生成的位置的属性。这些属性的键是 MessageFormat.Field 类型，它们的值是 Integer 对象，指示生成文本的参数在 arguments 数组中的索引。

      MessageFormat 使用的底层 Format 实例的属性/值也将放置在生成的 AttributedCharacterIterator 中。这使您不仅可以找到参数在结果字符串中的位置，还可以找到它依次包含哪些字段。

      重写：
      formatToCharacterIterator 在类 Format 中
      参数：
      arguments - 要格式化和替换的对象数组。
      返回：
      描述格式化值的 AttributedCharacterIterator。
      抛出：
      NullPointerException - 如果 arguments 为空。
      IllegalArgumentException - 如果 arguments 数组中的参数不是使用它的格式元素所期望的类型。
      自从：
      1.4

    • parse

      public Object [] parse(String  source, ParsePosition  pos)
      解析字符串。

      注意事项：在许多情况下，解析可能会失败。例如：

      • 如果其中一个参数没有出现在模式中。
      • 如果参数的格式丢失信息，例如选择格式，其中大量格式为“许多”。
      • 尚未处理递归（其中替换的字符串包含 {n} 引用。）
      • 如果解析的某些部分不明确，则不会总能找到匹配项（或正确的匹配项）。例如，如果模式“{1},{2}”与字符串参数 {"a,b", "c"} 一起使用，它将格式化为 "a,b,c"。解析结果时，会返回{"a", "b,c"}。
      • 如果单个参数在字符串中被解析多次，则以后的解析为准。
      当解析失败时，使用 ParsePosition.getErrorIndex() 找出字符串中解析失败的位置。返回的错误索引是字符串与之比较的子模式的起始偏移量。例如，如果解析字符串“AAA {0} BBB”正在与模式“AAD {0} BBB”进行比较，则错误索引为 0。发生错误时，调用此方法将返回 null。如果源为空，则返回一个空数组。
      参数：
      source - 要解析的字符串
      pos - 解析位置
      返回：
      已解析对象的数组
      抛出：
      NullPointerException - 如果 pos 是非空 source 字符串的 null。

    • parse

      public Object [] parse(String  source) throws ParseException
      从给定字符串的开头解析文本以生成对象数组。该方法可能不会使用给定字符串的整个文本。

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

      参数：
      source - 一个 String 的开头应该被解析。
      返回：
      从字符串中解析出的 Object 数组。
      抛出：
      ParseException - 如果无法解析指定字符串的开头。

    • parseObject

      public Object  parseObject(String  source, ParsePosition  pos)
      解析字符串中的文本以生成对象数组。

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

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

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

    • clone

      public Object  clone()
      创建并返回此对象的副本。
      重写：
      clone 在类 Format 中
      返回：
      此实例的克隆。
      参见：

    • equals

      public boolean equals(Object  obj)
      两个消息格式对象之间的相等性比较
      重写：
      equals 在类 Object 中
      参数：
      obj - 要比较的参考对象。
      返回：
      true 如果此对象与 obj 参数相同； false否则。
      参见：

    • hashCode

      public int hashCode()
      为消息格式对象生成哈希码。
      重写：
      hashCode 在类 Object 中
      返回：
      此对象的哈希码值。
      参见：