MessageFormat 類別

定義

[Android.Runtime.Register("android/icu/text/MessageFormat", ApiSince=24, DoNotGenerateAcw=true)]
public class MessageFormat : Android.Icu.Text.UFormat

[<Android.Runtime.Register("android/icu/text/MessageFormat", ApiSince=24, DoNotGenerateAcw=true)>]
type MessageFormat = class
    inherit UFormat

繼承

Object

JavaObject

Object

_Format

UFormat

MessageFormat

屬性

RegisterAttribute

備註

<強力>[加護病房增強]</強重> 加護病房取代 java.text.MessageFormat. ICU特有的方法、領域及其他功能標示為「<強力>[重症監護室]</強力>」。

MessageFormat 準備字串供使用者顯示，並可選擇參數（變數/佔位符）。 論元可以以任意順序出現，這是翻譯成不同文法語言所必需的。

MessageFormat 是由 <一個 em>模式</em> 字串構成，參數為 {curly braces}，這些參數會被格式化的值取代。

MessageFormat 與其他 Format 類別不同的是，你是用其中一個建構子來建立 MessageFormat 物件（不是用 getInstance style factory 方法）。 工廠方法並非必需，因為 MessageFormat 工廠方法本身不實作特定區域的行為。 任何特定地區的行為都由你提供的模式和插入參數所使用的子格式所定義。

參數可以命名（使用識別碼）或編號（使用小 ASCII 整數）。 部分 API 方法僅對參數編號有效，若模式中有命名參數則拋出例外（參見 #usesNamedArguments()）。

參數可能不指定任何格式類型。 此時，數字值以預設（區域）NumberFormat格式，Date值以預設（區域）DateFormat格式，其他值則使用其 toString（） 值。

參數可能指定一個「簡單」型別，該類型會建立、快取並使用指定的 Format 物件。

一個參數可能具有帶有巢狀 MessageFormat 子模式的「複雜」型態。 在格式化過程中，根據參數值選擇其中一個子訊息並遞迴格式化。

建構後，可以為頂層參數設定自訂 Format 物件，覆蓋該參數的預設格式化與解析行為。 然而，自訂格式化可以透過在模式字串中寫一個無型參數，並提供預先格式化的字串值來達成。

格式化時，MessageFormat 會取一組參數值並寫入輸出字串。 參數值可以以陣列形式傳遞（當模式僅包含編號參數時）或映射（同時適用於命名與編號參數）。

每個參數會透過陣列索引或映射鍵與其中一個輸入值匹配，並依照其模式規格格式化（或若設定了自訂格式物件，則使用自訂格式物件）。 編號模式參數會與包含該數字的 ASCII 十進位數字字串（無前置零）的映射金鑰匹配。

<h3>「模式」模式>及其詮釋</h3>

MessageFormat 使用以下形式的模式： <Blockquote>

message = messageText (argument messageText)*
            argument = noneArg | simpleArg | complexArg
            complexArg = choiceArg | pluralArg | selectArg | selectordinalArg

            noneArg = '{' argNameOrNumber '}'
            simpleArg = '{' argNameOrNumber ',' argType [',' argStyle] '}'
            choiceArg = '{' argNameOrNumber ',' "choice" ',' choiceStyle '}'
            pluralArg = '{' argNameOrNumber ',' "plural" ',' pluralStyle '}'
            selectArg = '{' argNameOrNumber ',' "select" ',' selectStyle '}'
            selectordinalArg = '{' argNameOrNumber ',' "selectordinal" ',' pluralStyle '}'

            choiceStyle: see {@link ChoiceFormat}
            pluralStyle: see {@link PluralFormat}
            selectStyle: see {@link SelectFormat}

            argNameOrNumber = argName | argNumber
            argName = [^[[:Pattern_Syntax:][:Pattern_White_Space:]]]+
            argNumber = '0' | ('1'..'9' ('0'..'9')*)

            argType = "number" | "date" | "time" | "spellout" | "ordinal" | "duration"
            argStyle = "short" | "medium" | "long" | "full" | "integer" | "currency" | "percent" | argStyleText

</區塊引用>

<ul><li>messageText 可以包含引號的字串，包括語法字元。 引號字串以 ASCII 撇號和語法字元（通常是 {大括號}）開頭，直到下一個撇號為止。 在引用字串內外的雙 ASCII 撇號代表一個字面撇號。 <li>可引用語法字元包括所有 messageText 部分中的 {捲括號}，加上 messageText 中緊鄰複數風格內的 '#' 符號，以及 choiceStyle 內緊鄰 messageText 中的 '|' 符號。 <li>另 MessagePattern.ApostropheMode<見 li>在 argStyleText 中，每個 ASCII 撇號都以引用的字面文字開頭和結尾，且未引號的 {curly braces} 必須成對出現。 </ul>

建議：對於人類可讀的文字，請使用真實的撇號（單引號）\\u2019，並且只在程式語法中使用 ASCII 撇號（\\u0027 '），就像在 MessageFormat 中引用一樣。 請參閱 Unicode 標準中 U+0027 撇號的註解。

choice論元類型已被棄用。 使用 plural 適當的複數選擇論證，以及 select 在固定選擇集合中使用簡單選擇的論證。

argType和 argStyle 值用於建立Format格式元素的實例。 下表展示了這些值如何映射到格式實例。 未在表格中顯示的組合是違法的。 任何 argStyleText 必須是所用 Format 子類別的有效模式字串。

<表格邊框=1><tr><th>argType <th>argStyle <th>結果 格式物件 <tr><td colspan=2>（none）<td>null<tr><td rowspan=5>number<td>（none）<td>NumberFormat.getInstance(getLocale())<tr><td>integer<td>NumberFormat.getIntegerInstance(getLocale())<tr><td>currency<>NumberFormat.getCurrencyInstance(getLocale())<td tr td td tr><td td tr>percent<>NumberFormat.getPercentInstance(getLocale())<><td>argStyleText<td>new DecimalFormat(argStyleText, new DecimalFormatSymbols(getLocale()))<tr><td rowspan=6>date<td>（none）<td>DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())<tr><td>short<>DateFormat.getDateInstance(DateFormat.SHORT, getLocale())<td><td>medium<tr td>DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())<><>long<>td trDateFormat.getDateInstance(DateFormat.LONG, getLocale())<td td tr><td>full<>DateFormat.getDateInstance(DateFormat.FULL, getLocale())<><td td tr> argStyleText <td>new SimpleDateFormat(argStyleText, getLocale())<TR><TD rowspan=6>time<TD>（none）<td>DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())<tr><td>short<>DateFormat.getTimeInstance(DateFormat.SHORT, getLocale())<td tr><td>medium<td>DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())<tr><>long<>DateFormat.getTimeInstance(DateFormat.LONG, getLocale())<td tr><td td>full<>DateFormat.getTimeInstance(DateFormat.FULL, getLocale())<tr><>td argStyleText <td tr>new SimpleDateFormat(argStyleText, getLocale())<><td>spellout<td> argStyleText （optional）<td>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.SPELLOUT) <br>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText);<tr><td td>ordinal<> argStyleText （optional）<td>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.ORDINAL) <br>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText);<tr><td td>duration<> argStyleText （optional）<td>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.DURATION) <br>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(argStyleText);</table>

<h4>“diffsjdk”>與java.text.MessageFormat</h4的差異>

ICU MessageFormat 支援命名與編號參數，而 JDK 訊息格式僅支援編號參數。 命名參數使模式更易閱讀。

ICU 採用更友善的撇號引用語法。 在訊息文字中，撇號只有在緊接語法字元（多為 {大括號}）緊接著時，才會開始引用字面文字。<在> JDK 訊息格式中，撇號總是以引號開始，這需要像「don't」和「aujourd'hui」這類常用文字，並用雙撇號（如「don't」和「aujourd''hui」）來書寫。 如需詳細資訊，請參閱 MessagePattern.ApostropheMode。

ICU 不會為 choiceArg、pluralArg 或 selectArg 建立 ChoiceFormat 物件，而是自行處理這些參數。 JDK MessageFormat 確實會建立並使用 ChoiceFormat 物件（new ChoiceFormat(argStyleText)）。 JDK完全不支持複數和選擇性論點。

<h4>使用資訊</h4>

以下是一些用法範例： <blockquote>

Object[] arguments = {
                7,
                new Date(System.currentTimeMillis()),
                "a disturbance in the Force"
            };

            String result = MessageFormat.format(
                "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
                arguments);

<em>output</em>: At 12:30 PM on Jul 3, 2053, there was a disturbance
                      in the Force on planet 7.

</blockquote> 通常訊息格式來自資源，參數會在執行時動態設定。

範例 2： <區塊引用>

Object[] testArgs = { 3, "MyDisk" };

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

            System.out.println(form.format(testArgs));

            // output, with different testArgs
<em>output</em>: The disk "MyDisk" contains 0 file(s).
<em>output</em>: The disk "MyDisk" contains 1 file(s).
<em>output</em>: The disk "MyDisk" contains 1,273 file(s).

</區塊引用>

對於包含複數形式的訊息，您可以使用複數論元：

MessageFormat msgFmt = new MessageFormat(
                "{num_files, plural, " +
                "=0{There are no files on disk \"{disk_name}\".}" +
                "=1{There is one file on disk \"{disk_name}\".}" +
                "other{There are # files on disk \"{disk_name}\".}}",
                ULocale.ENGLISH);
            Map args = new HashMap();
            args.put("num_files", 0);
            args.put("disk_name", "MyDisk");
            System.out.println(msgFmt.format(args));
            args.put("num_files", 3);
            System.out.println(msgFmt.format(args));

<em>output</em>:
            There are no files on disk "MyDisk".
            There are 3 files on "MyDisk".

詳情請參閱 PluralFormat 及PluralRules

<h4>「同步」同步></h4>

訊息格式不同步。 建議為每個執行緒建立獨立格式實例。 若多個執行緒同時存取同一格式，必須在外部同步。

Java 文件 android.icu.text.MessageFormat。

本頁部分內容為基於 Open Source Project 所創建與分享的作品，並依授權條款所描述的使用進行修改。