MessageFormat的使用和API说明

港控/mmm° 2023-06-16 15:54 12阅读 0赞

先上例子：

/**  
         * @Title: MessageFormatTest.java
         * @Package com.burns
         * @Description: TODO(用一句话描述该文件做什么)
         * @author 35725
         * @date 2019年11月27日 上午9:17:04 
         * @version V1.0  
         */
        
    package com.burns;
    
    import java.text.MessageFormat;
    
    /**
         * @ClassName: MessageFormatTest
         * @Description: TODO(这里用一句话描述这个类的作用)
         * @author 35725
         * @date 2019年11月27日
         *
         */
    
    public class MessageFormatTest {
    	
    	private static String pattern = "当前执行到：{0}{1}，下一个执行第{2}{3}";
    
    	public static void main(String[] args) {
    		for (int i = 0; i < 10; i++) {
    			System.out.println(MessageFormat.format(pattern , new Object[]{i,"次",i+1,"次"}));
    			
    		}
    	}
    
    }

输出结果：

当前执行到：0次，下一个执行第1次
    当前执行到：1次，下一个执行第2次
    当前执行到：2次，下一个执行第3次
    当前执行到：3次，下一个执行第4次
    当前执行到：4次，下一个执行第5次
    当前执行到：5次，下一个执行第6次
    当前执行到：6次，下一个执行第7次
    当前执行到：7次，下一个执行第8次
    当前执行到：8次，下一个执行第9次
    当前执行到：9次，下一个执行第10次

`MessageFormat` 提供了以与语言无关方式生成连接消息的方式。使用此方法构造向终端用户显示的消息。

`MessageFormat` 获取一组对象，格式化这些对象，然后将格式化后的字符串插入到模式中的适当位置。

**注：**`MessageFormat` 不同于其他 `Format` 类，因为 `MessageFormat` 对象是用其构造方法之一创建的（而不是使用 `getInstance` 样式的工厂方法创建的）。工厂方法不是必需的，因为 `MessageFormat` 本身不实现特定于语言环境的行为。特定于语言环境的行为是由所提供的模式和用于已插入参数的子格式来定义的。

模式及其解释

`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:
>              StringPartopt
>              String StringPart
>     
>      StringPart:
>              ''
>              ' QuotedString '
>              UnquotedString
>     
>      SubformatPattern:
>              SubformatPatternPartopt
>              SubformatPattern SubformatPatternPart
>     
>      SubFormatPatternPart:
>              ' QuotedPattern '
>              UnquotedPattern

在 *String* 中，`"''"` 表示单引号。*QuotedString* 可以包含除单引号之外的任意字符；围绕的单引号被移除。*UnquotedString* 可以包含除单引号和左花括号之外的任意字符。因此，格式化后消息字符串为 "'\{0\}'" 的字符串可以写作 `"'''{'0}''"` 或 `"'''{0}'''"`。

在 *SubformatPattern* 中，应用了不同的规则。*QuotedPattern* 可包含除单引号之外的任意字符，但**不** 移除围绕的单引号，因此它们可以由子格式解释。例如，`"{1,number,$'#',##}"` 将产生一个带井号的数字格式，结果如："$\#31,45"。 *UnquotedPattern* 可以包含除单引号之外的任意字符，但其中的花括号必须成对出现。例如，`"ab {0} de"` 和 `"ab '}' de"` 是有效的子格式模式，而 `"ab {0'}' de"` 和 `"ab } de"` 则是无效的。

**警告：**

不过，在消息格式模式中使用引号的规则在一定程度上显示混乱。尤其是，本地化程序并不总是清楚单引号是否需要成对。要确保通知本地化程序关于规则的信息，并告诉它们（例如，通过使用资源包源文件中的注释）MessageFormat 将处理哪些字符串。注意，本地化程序在转换后的字符串中必须使用单引号，其中原始版本不包含单引号。

*ArgumentIndex* 值是使用数字 '0' 到 '9' 表示的非负整数，它表示传递给 `format` 方法的 `arguments` 数组的一个索引，或者表示由 `parse` 方法返回的结果数组的一个索引。

*FormatType* 和 *FormatStyle* 值用来创建格式元素的 `Format` 实例。下表显示了值如何映射到 Format 实例。表中没有显示的组合是非法的。*SubformatPattern* 必须是所使用的 Format 子类的一个有效的模式字符串。

<table> 
 <tbody> 
  <tr> 
   <th>格式类型</th> 
   <th>格式样式</th> 
   <th>创建的子格式</th> 
  </tr> 
  <tr> 
   <td><em>无</em></td> 
   <td><em>无</em></td> 
   <td><code>null</code></td> 
  </tr> 
  <tr> 
   <td><code>number</code></td> 
   <td><em>无</em></td> 
   <td><code>NumberFormat.getInstance(getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>integer</code></td> 
   <td><code>NumberFormat.getIntegerInstance(getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>currency</code></td> 
   <td><code>NumberFormat.getCurrencyInstance(getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>percent</code></td> 
   <td><code>NumberFormat.getPercentInstance(getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><em>SubformatPattern</em></td> 
   <td><code>new DecimalFormat(subformatPattern, DecimalFormatSymbols.getInstance(getLocale()))</code></td> 
  </tr> 
  <tr> 
   <td><code>date</code></td> 
   <td><em>无</em></td> 
   <td><code>DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>short</code></td> 
   <td><code>DateFormat.getDateInstance(DateFormat.SHORT, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>medium</code></td> 
   <td><code>DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>long</code></td> 
   <td><code>DateFormat.getDateInstance(DateFormat.LONG, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>full</code></td> 
   <td><code>DateFormat.getDateInstance(DateFormat.FULL, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><em>SubformatPattern</em></td> 
   <td><code>new SimpleDateFormat(subformatPattern, getLocale()) </code></td> 
  </tr> 
  <tr> 
   <td><code>time</code></td> 
   <td><em>无</em></td> 
   <td><code>DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>short</code></td> 
   <td><code>DateFormat.getTimeInstance(DateFormat.SHORT, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>medium</code></td> 
   <td><code>DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>long</code></td> 
   <td><code>DateFormat.getTimeInstance(DateFormat.LONG, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><code>full</code></td> 
   <td><code>DateFormat.getTimeInstance(DateFormat.FULL, getLocale())</code></td> 
  </tr> 
  <tr> 
   <td><em>SubformatPattern</em></td> 
   <td><code>new SimpleDateFormat(subformatPattern, getLocale()) </code></td> 
  </tr> 
  <tr> 
   <td><code>choice</code></td> 
   <td><em>SubformatPattern</em></td> 
   <td><code>new ChoiceFormat(subformatPattern)</code></td> 
  </tr> 
 </tbody> 
</table>

用法信息

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

第一个例子使用静态的方法 `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 = {new Long(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 = {new Long(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}.");

**注：**从上面的例子可以看到，由 `MessageFormat` 中的 `ChoiceFormat` 所生成的字符串要进行特殊处理；'\{' 的出现用来指示子格式，并导致递归。如果 `MessageFormat` 和 `ChoiceFormat` 都是以编程方式创建的（而不是使用字符串模式），那么要注意不要生成对其自身进行递归的格式，这将导致无限循环。

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

>     MessageFormat mf = new MessageFormat("{0,number,#.##}, {0,number,#.#}");
>      Object[] objs = {new Double(3.1415)};
>      String result = mf.format( objs );
>      // result now equals "3.14, 3.1"
>      objs = null;
>      objs = mf.parse(result, new ParsePosition(0));
>      // objs now equals {new Double(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")}

同步

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

**另请参见：**

`Locale`, `Format`, `NumberFormat`, `DecimalFormat`, `ChoiceFormat`, 序列化表格

--------------------

<table> 
 <tbody> 
  <tr> 
   <th colspan="2"><strong>嵌套类摘要</strong></th> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>static&nbsp;class</code></td> 
   <td><code><strong><a rel="nofollow">MessageFormat.Field</a></strong></code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;在从 <code>MessageFormat.formatToCharacterIterator</code> 返回的 <code>AttributedCharacterIterator</code> 中定义用作属性键的常量。</td> 
  </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
  <tr> 
   <th colspan="2"><strong>构造方法摘要</strong></th> 
  </tr> 
  <tr> 
   <td><code><strong><a rel="nofollow">MessageFormat</a></strong>(<a rel="nofollow">String</a>&nbsp;pattern)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;构造默认语言环境和指定模式的 MessageFormat。</td> 
  </tr> 
  <tr> 
   <td><code><strong><a rel="nofollow">MessageFormat</a></strong>(<a rel="nofollow">String</a>&nbsp;pattern, <a rel="nofollow">Locale</a>&nbsp;locale)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;构造指定语言环境和模式的 MessageFormat。</td> 
  </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
  <tr> 
   <th colspan="2"><strong>方法摘要</strong></th> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;void</code></td> 
   <td><code><strong><a rel="nofollow">applyPattern</a></strong>(<a rel="nofollow">String</a>&nbsp;pattern)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;设置此消息格式所使用的模式。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">Object</a></code></td> 
   <td><code><strong><a rel="nofollow">clone</a></strong>()</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;创建并返回此对象的一个副本。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;boolean</code></td> 
   <td><code><strong><a rel="nofollow">equals</a></strong>(<a rel="nofollow">Object</a>&nbsp;obj)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;两个消息格式对象之间的相等性比较</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">StringBuffer</a></code></td> 
   <td><code><strong><a rel="nofollow">format</a></strong>(<a rel="nofollow">Object</a>[]&nbsp;arguments, <a rel="nofollow">StringBuffer</a>&nbsp;result, <a rel="nofollow">FieldPosition</a>&nbsp;pos)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;格式化一个对象数组，并将 <code>MessageFormat</code> 的模式添加到所提供的 <code>StringBuffer</code>，用格式化后的对象替换格式元素。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">StringBuffer</a></code></td> 
   <td><code><strong><a rel="nofollow">format</a></strong>(<a rel="nofollow">Object</a>&nbsp;arguments, <a rel="nofollow">StringBuffer</a>&nbsp;result, <a rel="nofollow">FieldPosition</a>&nbsp;pos)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;格式化一个对象数组，并将 <code>MessageFormat</code> 的模式添加到所提供的 <code>StringBuffer</code>，用格式化后的对象替换格式元素。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>static&nbsp;<a rel="nofollow">String</a></code></td> 
   <td><code><strong><a rel="nofollow">format</a></strong>(<a rel="nofollow">String</a>&nbsp;pattern, <a rel="nofollow">Object</a>...&nbsp;arguments)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;创建具有给定模式的 MessageFormat，并用它来格式化给定的参数。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">AttributedCharacterIterator</a></code></td> 
   <td><code><strong><a rel="nofollow">formatToCharacterIterator</a></strong>(<a rel="nofollow">Object</a>&nbsp;arguments)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;格式化一个对象数组，并将它们插入 <code>MessageFormat</code> 的模式中，生成一个 <code>AttributedCharacterIterator</code>。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">Format</a>[]</code></td> 
   <td><code><strong><a rel="nofollow">getFormats</a></strong>()</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;获取用于以前所设置的模式字符串中格式元素的格式。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">Format</a>[]</code></td> 
   <td><code><strong><a rel="nofollow">getFormatsByArgumentIndex</a></strong>()</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;获取传递给 <code>format</code> 方法或从 <code>parse</code> 方法返回的值的格式。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">Locale</a></code></td> 
   <td><code><strong><a rel="nofollow">getLocale</a></strong>()</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;获取创建或比较子格式时所使用的语言环境。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;int</code></td> 
   <td><code><strong><a rel="nofollow">hashCode</a></strong>()</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;生成此消息格式对象的哈希码。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">Object</a>[]</code></td> 
   <td><code><strong><a rel="nofollow">parse</a></strong>(<a rel="nofollow">String</a>&nbsp;source)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;从给定字符串的开始位置解析文本，以生成一个对象数组。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">Object</a>[]</code></td> 
   <td><code><strong><a rel="nofollow">parse</a></strong>(<a rel="nofollow">String</a>&nbsp;source, <a rel="nofollow">ParsePosition</a>&nbsp;pos)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;解析字符串。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">Object</a></code></td> 
   <td><code><strong><a rel="nofollow">parseObject</a></strong>(<a rel="nofollow">String</a>&nbsp;source, <a rel="nofollow">ParsePosition</a>&nbsp;pos)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;解析字符串文本，生成一个对象数组。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;void</code></td> 
   <td><code><strong><a rel="nofollow">setFormat</a></strong>(int&nbsp;formatElementIndex, <a rel="nofollow">Format</a>&nbsp;newFormat)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;使用在以前设置的模式字符串中给定的格式元素索引来设置格式元素使用的格式。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;void</code></td> 
   <td><code><strong><a rel="nofollow">setFormatByArgumentIndex</a></strong>(int&nbsp;argumentIndex, <a rel="nofollow">Format</a>&nbsp;newFormat)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;设置用于以前所设置的模式字符串中格式元素的格式，其中以前的模式字符串是用给定的参数索引设置的。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;void</code></td> 
   <td><code><strong><a rel="nofollow">setFormats</a></strong>(<a rel="nofollow">Format</a>[]&nbsp;newFormats)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;设置用于以前所设置的模式字符串中格式元素的格式。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;void</code></td> 
   <td><code><strong><a rel="nofollow">setFormatsByArgumentIndex</a></strong>(<a rel="nofollow">Format</a>[]&nbsp;newFormats)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;设置传递给 <code>format</code> 方法或从 <code>parse</code> 方法返回的值使用的格式。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;void</code></td> 
   <td><code><strong><a rel="nofollow">setLocale</a></strong>(<a rel="nofollow">Locale</a>&nbsp;locale)</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;设置创建或比较子格式时要使用的语言环境。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><code>&nbsp;<a rel="nofollow">String</a></code></td> 
   <td><code><strong><a rel="nofollow">toPattern</a></strong>()</code><br> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;返回表示消息格式当前状态的模式。</td> 
  </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
  <tr> 
   <th><strong>构造方法详细信息</strong></th> 
  </tr> 
 </tbody> 
</table>

### MessageFormat ###

public MessageFormat(String pattern)

构造默认语言环境和指定模式的 MessageFormat。构造方法首先设置语言环境，然后解析模式，并为其包含的格式元素创建子格式列表。在类描述中指定了模式及其解释。

**参数：**

`pattern` \- 此消息格式的模式

**抛出：**

`IllegalArgumentException` \- 如果模式无效

--------------------

### MessageFormat ###

public MessageFormat(String pattern,
                         Locale locale)

构造指定语言环境和模式的 MessageFormat。构造方法首先设置语言环境，然后解析模式，并为其包含的格式元素创建子格式列表。在类描述中指定了模式及其解释。

**参数：**

`pattern` \- 此消息格式的模式

`locale` \- 此消息格式的语言环境

**抛出：**

`IllegalArgumentException` \- 如果模式无效

**从以下版本开始：**

1.4

<table> 
 <tbody> 
  <tr> 
   <th><strong>方法详细信息</strong></th> 
  </tr> 
 </tbody> 
</table>

### setLocale ###

public void setLocale(Locale locale)

设置创建或比较子格式时要使用的语言环境。 这将影响对下面方法的后续调用

*  对 `applyPattern` 和 `toPattern` 方法的后续调用，如果格式元素指定了格式类型并且因此具有在 `applyPattern` 方法中创建的子格式，以及
 *  对 `format` 和 `formatToCharacterIterator` 方法的后续调用，如果格式元素未指定格式类型并且因此具有在格式化方法中创建的子格式。

不影响已经创建的子格式。

**参数：**

`locale` \- 创建或比较子格式时所使用的语言环境

--------------------

### getLocale ###

public Locale getLocale()

获取创建或比较子格式时所使用的语言环境。

**返回：**

创建或比较子格式时所使用的语言环境

--------------------

### applyPattern ###

public void applyPattern(String pattern)

设置此消息格式所使用的模式。此方法对模式进行解析，并为其所包含的格式元素创建子格式列表。在类描述中指定了模式及其解释。

**参数：**

`pattern` \- 此消息格式的模式

**抛出：**

`IllegalArgumentException` \- 如果模式无效

--------------------

### toPattern ###

public String toPattern()

返回表示消息格式当前状态的模式。字符串是从内部信息创建的，因此不需要与以前应用的模式相等。

**返回：**

表示消息格式当前状态的模式

--------------------

### setFormatsByArgumentIndex ###

public void setFormatsByArgumentIndex(Format[] newFormats)

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

如果一个参数索引用于模式字符串中的多个格式元素，那么对应的新的格式将用于所有这样的格式元素。如果参数索引不用于模式字符串的任何一个格式元素，那么对应的新的格式将被忽略。如果提供的格式少于所需的格式，那么只替换其参数索引小于 `newFormats.length` 的格式。

**参数：**

`newFormats` \- 要使用的新格式

**抛出：**

`NullPointerException` \- 如果 `newFormats` 为 null

**从以下版本开始：**

1.4

--------------------

### setFormats ###

public void setFormats(Format[] newFormats)

设置用于以前所设置的模式字符串中格式元素的格式。`newFormats` 中的格式顺序对应于模式字符串中的格式元素的顺序。

如果提供的格式多于模式字符串所需的格式，那么剩余的格式将被忽略。如果提供的格式少于所需的格式，那么只替换前 `newFormats.length` 个格式。

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

**参数：**

`newFormats` \- 要使用的新格式

**抛出：**

`NullPointerException` \- 如果 `newFormats` 为 null

--------------------

### setFormatByArgumentIndex ###

public void setFormatByArgumentIndex(int argumentIndex,
                                         Format newFormat)

设置用于以前所设置的模式字符串中格式元素的格式，其中以前的模式字符串是用给定的参数索引设置的。参数索引是格式元素定义的一部分，它表示传递给 `format` 方法或从 `parse` 方法返回的结果数组的 `arguments` 数组的索引。

如果参数索引用于模式字符串中的多个格式元素，那么新的格式将用于所有这样的格式元素。如果参数索引没有用于模式字符串的任何格式元素，那么新的格式将被忽略。

**参数：**

`argumentIndex` \- 要用于新的格式的参数索引

`newFormat` \- 要使用的新格式

**从以下版本开始：**

1.4

--------------------

### setFormat ###

public void setFormat(int formatElementIndex,
                          Format newFormat)

使用在以前设置的模式字符串中给定的格式元素索引来设置格式元素使用的格式。格式元素索引是从模式字符串起始位置开始计数的、从 0 开始的数字。

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

**参数：**

`formatElementIndex` \- 模式中的格式元素的索引

`newFormat` \- 要用于指定格式元素的格式

**抛出：**

`ArrayIndexOutOfBoundsException` \- 如果 formatElementIndex 等于或大于模式字符串中格式元素的个数

--------------------

### getFormatsByArgumentIndex ###

public Format[] getFormatsByArgumentIndex()

获取传递给 `format` 方法或从 `parse` 方法返回的值的格式。返回的数组中的元素的索引对应于以前设置模式字符串中所使用的参数索引。因此，返回的数组中的格式顺序对应于传递给 `format` 方法或从 `parse` 方法返回的 `arguments` 数组中的元素顺序。

如果一个参数索引用于模式字符串中的多个格式元素，那么在数组中将返回用于最后一个这样的元素的格式。如果参数索引不用于模式字符串中的任何一个格式元素，那么在数组中将返回 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，则参数是*不可用的*。

<table> 
 <tbody> 
  <tr> 
   <th>子格式</th> 
   <th>参数</th> 
   <th>格式化文本</th> 
  </tr> 
  <tr> 
   <td><em>所有</em></td> 
   <td><em>不可用</em></td> 
   <td><code>"{" + argumentIndex + "}"</code></td> 
  </tr> 
  <tr> 
   <td><em>所有</em></td> 
   <td><code>null</code></td> 
   <td><code>"null"</code></td> 
  </tr> 
  <tr> 
   <td><code>instanceof ChoiceFormat</code></td> 
   <td><em>所有</em></td> 
   <td><code>subformat.format(argument).indexOf('{') &gt;= 0 ?<br> (new MessageFormat(subformat.format(argument), getLocale())).format(argument) : subformat.format(argument)</code></td> 
  </tr> 
  <tr> 
   <td><code>!= null</code></td> 
   <td><em>所有</em></td> 
   <td><code>subformat.format(argument)</code></td> 
  </tr> 
  <tr> 
   <td><code>null</code></td> 
   <td><code>instanceof Number</code></td> 
   <td><code>NumberFormat.getInstance(getLocale()).format(argument)</code></td> 
  </tr> 
  <tr> 
   <td><code>null</code></td> 
   <td><code>instanceof Date</code></td> 
   <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)</code></td> 
  </tr> 
  <tr> 
   <td><code>null</code></td> 
   <td><code>instanceof String</code></td> 
   <td><code>argument</code></td> 
  </tr> 
  <tr> 
   <td><code>null</code></td> 
   <td><em>所有</em></td> 
   <td><code>argument.toString()</code></td> 
  </tr> 
 </tbody> 
</table>

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

**参数：**

`arguments` \- 要被格式化和替换的对象数组。

`result` \- 添加文本的位置。

`pos` \- 输入时：如果需要，是一个对齐字段。输出时：为对齐字段的偏移量。

**抛出：**

`IllegalArgumentException` \- 如果 `arguments` 数组中的参数不是使用该参数的格式元素期望的类型。

--------------------

### format ###

public static String format(String pattern,
                                Object... arguments)

创建具有给定模式的 MessageFormat，并用它来格式化给定的参数。这等效于

> `(new MessageFormat(pattern)).format(arguments, new StringBuffer(), null).toString()`

**抛出：**

`IllegalArgumentException` \- 如果模式无效，或者 `arguments` 数组中的参数不是使用该参数的格式元素期望的类型。

--------------------

### 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` 数组中的参数不是使用该参数的格式元素期望的类型。

--------------------

### 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` 中。这不仅允许查找参数被存放在得到的 String 中的位置，而且允许查找它依次包含哪些字段。

**覆盖：**

类 `Format` 中的 `formatToCharacterIterator`

**参数：**

`arguments` \- 要被格式化和替换的对象数组。

**返回：**

描述格式化后的值的 AttributedCharacterIterator。

**抛出：**

`NullPointerException` \- 如果 `arguments` 为 null。

`IllegalArgumentException` \- 如果 `arguments` 数组中的参数不是使用该参数的格式元素期望的类型。

**从以下版本开始：**

1.4

--------------------

### parse ###

public Object[] parse(String source,
                          ParsePosition pos)

解析字符串。

警告：在许多情况下解析可能失败。例如：

*  如果某个参数未出现在模式中。
 *  如果丢失了参数的格式信息，例如对于一个格式化选项，其中一个大数格式化为 "many"。
 *  尚未处理递归（其中替换后的字符串包含 \{n\} 引用）。
 *  当解析的某个部分不明确时，将不能总找到一个匹配（或者正确的匹配）。例如，如果模式 "\{1\},\{2\}" 用于字符串参数 \{"a,b", "c"\}，它将格式化为 "a,b,c"。当解析结果时，它将返回 \{"a", "b,c"\}。
 *  如果字符串中的参数被解析多次，那么将保留最后一次的解析结果。

当解析失败时，使用 ParsePosition.getErrorIndex() 来查找字符串的哪个位置导致了解析失败。返回的错误索引是要用来与字符串比较的子模式的起始偏移量。例如，如果解析的字符串 "AAA \{0\} BBB" 与模式 "AAD \{0\} BBB" 进行比较，则错误索引为 0。当发生错误时，对此方法的调用将返回 null。如果源为 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)` 方法。

**指定者：**

类 `Format` 中的 `parseObject`

**参数：**

`source` \- 应该解析其中一部分的 `String`。

`pos` \- 具有以上所述的索引和错误索引信息的 `ParsePosition` 对象。

**返回：**

从字符串进行解析的 `Object` 数组。如果发生错误，则返回 null。

**抛出：**

`NullPointerException` \- 如果 `pos` 为 null。

--------------------

### clone ###