java.text
類別 MessageFormat

java.lang.Object
  java.text.Format
      java.text.MessageFormat

所有已實作的介面：

Serializable, Cloneable

public class MessageFormat
extends Format

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 子類別的一個有效的網要字元串。

格式型別	格式樣式	創建的子格式
無	無	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 = {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, 序列化表格

巢狀類別摘要

static class

MessageFormat.Field 在從 MessageFormat.formatToCharacterIterator 返回的 AttributedCharacterIterator 中定義用作屬性鍵的常數。

建構子摘要

MessageFormat(String pattern)
建構預設語言環境和指定網要的 MessageFormat。

MessageFormat(String pattern, Locale locale)
建構指定語言環境和網要的 MessageFormat。

方法摘要

void	applyPattern(String pattern) 設置此訊息格式所使用的網要。
Object	clone() 創建並返回此物件的一個副本。
boolean	equals(Object obj) 兩個訊息格式物件之間的相等性比較
StringBuffer	format(Object[] arguments, StringBuffer result, FieldPosition pos) 格式化一個物件陣列，並將 MessageFormat 的網要添加到所提供的 StringBuffer，用格式化後的物件替換格式元素。
StringBuffer	format(Object arguments, StringBuffer result, FieldPosition pos) 格式化一個物件陣列，並將 MessageFormat 的網要添加到所提供的 StringBuffer，用格式化後的物件替換格式元素。
static String	format(String pattern, Object... arguments) 創建具有給定網要的 MessageFormat，並用它來格式化給定的參數。
AttributedCharacterIterator	formatToCharacterIterator(Object arguments) 格式化一個物件陣列，並將它們插入 MessageFormat 的網要中，產生一個 AttributedCharacterIterator。
Format[]	getFormats() 獲取用於以前所設置的網要字元串中格式元素的格式。
Format[]	getFormatsByArgumentIndex() 獲取傳遞給 format 方法或從 parse 方法返回的值的格式。
Locale	getLocale() 獲取創建或比較子格式時所使用的語言環境。
int	hashCode() 產生此訊息格式物件的雜湊碼。
Object[]	parse(String source) 從給定字元串的開始位置解析文本，以產生一個物件陣列。
Object[]	parse(String source, ParsePosition pos) 解析字元串。
Object	parseObject(String source, ParsePosition pos) 解析字元串文本，產生一個物件陣列。
void	setFormat(int formatElementIndex, Format newFormat) 使用在以前設置的網要字元串中給定的格式元素索引來設置格式元素使用的格式。
void	setFormatByArgumentIndex(int argumentIndex, Format newFormat) 設置用於以前所設置的網要字元串中格式元素的格式，其中以前的網要字元串是用給定的參數索引設置的。
void	setFormats(Format[] newFormats) 設置用於以前所設置的網要字元串中格式元素的格式。
void	setFormatsByArgumentIndex(Format[] newFormats) 設置傳遞給 format 方法或從 parse 方法返回的值使用的格式。
void	setLocale(Locale locale) 設置創建或比較子格式時要使用的語言環境。
String	toPattern() 返回表示訊息格式當前狀態的網要。

從類別 java.text.Format 繼承的方法

format, parseObject

從類別 java.lang.Object 繼承的方法

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

建構子詳細資訊

MessageFormat

public MessageFormat(String pattern)

建構預設語言環境和指定網要的 MessageFormat。建構子首先設置語言環境，然後解析網要，並為其包含的格式元素創建子格式列表。在類別描述中指定了網要及其解釋。

參數：

pattern - 此訊息格式的網要

拋出：

IllegalArgumentException - 如果網要無效

MessageFormat

public MessageFormat(String pattern,
                     Locale locale)

建構指定語言環境和網要的 MessageFormat。建構子首先設置語言環境，然後解析網要，並為其包含的格式元素創建子格式列表。在類別描述中指定了網要及其解釋。

參數：

pattern - 此訊息格式的網要

locale - 此訊息格式的語言環境

拋出：

IllegalArgumentException - 如果網要無效

從以下版本開始：

1.4

方法詳細資訊

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，則參數是不可用的。

子格式	參數	格式化文本
所有	不可用	"{" + 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)
null	instanceof Date	DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)
null	instanceof String	argument
null	所有	argument.toString()

如果 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

public Object clone()

創建並返回此物件的一個副本。

覆寫：

類別 Format 中的 clone

返回：

此實例的一個副本。

另請參見：

Cloneable

equals

public boolean equals(Object obj)

兩個訊息格式物件之間的相等性比較

覆寫：

類別 Object 中的 equals

參數：

obj - 要與之比較的參考物件。

返回：

如果此物件與 obj 參數相同，則返回 true；否則返回 false。

另請參見：

Object.hashCode(), Hashtable

hashCode

public int hashCode()

產生此訊息格式物件的雜湊碼。

覆寫：

類別 Object 中的 hashCode

返回：

此物件的一個雜湊碼值。

另請參見：

Object.equals(java.lang.Object), Hashtable