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
在字符串中 ,可以使用一对单引号来引用除单引号以外的任何字符。 例如,模式字符串"'{0}'"
表示字符串"{0}"
,而不是FormatElement 。 单引号本身必须由两个单引号表示''
整个字符串 。 例如,模式字符串"'{''}'"
被解释为'{
(起始引号和左大括号), ''
(单引号)和}'
(右括号括号和引号结尾)的'{'
, 不是 '{'
和'}'
(引用左右大括号):代表字符串"{'}"
, 而不是 "{}"
。
SubformatPattern由其对应的子格式解释,并且子格式依赖模式规则适用。 例如,模式字符串"{1,number,$'#',##}"
( SubformatPattern with underline)将产生带有引号的数字格式,结果如: "$#31,45"
。 有关详细信息,请参阅每个Format
子类文档。
任何不匹配的报价在给定模式结束时被视为关闭。 例如,模式字符串"'{0}"
被视为模式"'{0}'"
。
任何不引用花样的花括号必须平衡。 例如, "ab {0} de"
和"ab '}' de"
是有效的模式,但"ab {0'}' de"
, "ab } de"
和"''{''"
都没有。
MessageFormat
。
请注意,本地化程序可能需要在原始版本没有转换的字符串中使用单引号。
所述ArgumentIndex值是使用数字写入一个非负整数'0'
通过'9'
,并代表一个指数到arguments
数组传递到format
方法或由所述返回的结果阵列parse
方法。
FormatType和FormatStyle值用于为format元素创建一个Format
实例。 下表显示了值映射到Format
实例。 表中未显示的组合是非法的。 SubformatPattern必须是所使用的Format
子类的有效模式字符串。
null
number
(none) NumberFormat.getInstance
(getLocale())
integer
NumberFormat.getIntegerInstance
(getLocale())
currency
NumberFormat.getCurrencyInstance
(getLocale())
percent
NumberFormat.getPercentInstance
(getLocale())
SubformatPattern new
DecimalFormat
(subformatPattern,
DecimalFormatSymbols.getInstance
(getLocale()))
date
(none) 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
(none) 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
实例:
fileCount的输出值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,如上例所示,或通过使用模式。 见ChoiceFormat
以获取更多信息。
form.applyPattern( "There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.");
注意:如上所述,由ChoiceFormat
中的MessageFormat
生成的字符串被视为特殊MessageFormat
; “{”的出现用于表示子格式,并导致递归。 如果您以MessageFormat
创建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
, DecimalFormatSymbols
, ChoiceFormat
, DateFormat
, SimpleDateFormat
, Serialized Form
Modifier and Type | Class and Description |
---|---|
static class |
MessageFormat.Field
定义被用作属性键的常量
AttributedCharacterIterator 从返回
MessageFormat.formatToCharacterIterator 。
|
Constructor and Description |
---|
MessageFormat(String pattern)
为默认的
FORMAT 区域设置和指定的模式构造一个MessageFormat。
|
MessageFormat(String pattern, Locale locale)
为指定的区域设置和模式构造一个MessageFormat。
|
Modifier and Type | Method and Description |
---|---|
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 方法返回的
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 方法返回的
parse 。
|
void |
setLocale(Locale locale)
设置创建或比较子格式时要使用的区域设置。
|
String |
toPattern()
返回表示消息格式的当前状态的模式。
|
format, parseObject
public MessageFormat(String pattern)
FORMAT
语言环境和指定的模式构造一个MessageFormat。
构造函数首先设置区域设置,然后解析模式,并为其中包含的格式元素创建一个子格式列表。
模式及其解释在class description中规定 。
pattern
- 此消息格式的模式
IllegalArgumentException
- 如果模式无效
public MessageFormat(String pattern, Locale locale)
pattern
- 此消息格式的模式
locale
- 此消息格式的区域设置
IllegalArgumentException
- 如果模式无效
public void setLocale(Locale locale)
applyPattern
和toPattern
方法,如果格式元素指定格式类型,因此具有applyPattern
方法中创建的applyPattern
,以及 format
和formatToCharacterIterator
方法,如果格式元素不指定格式类型,因此在格式化方法中创建子格式。 locale
- 创建或比较子格式时要使用的区域设置
public Locale getLocale()
public void applyPattern(String pattern)
pattern
- 此消息格式的模式
IllegalArgumentException
- 如果模式无效
public String toPattern()
public void setFormatsByArgumentIndex(Format[] newFormats)
format
方法中的值或从parse
方法返回的parse
。
newFormats
中元素的newFormats
对应于在先前设置的模式字符串中使用的参数索引。
newFormats
中格式的newFormats
因此对应于传递给format
方法的arguments
数组或format
方法返回的结果数组的元素parse
。
如果在模式字符串中使用多个格式元素的参数索引,则所有这些格式元素都使用相应的新格式。 如果模式字符串中的任何格式元素都不使用参数索引,则忽略相应的新格式。 如果提供的格式比所需的格式少,那么仅替换小于newFormats.length
的参数索引的格式。
newFormats
- 要使用的新格式
NullPointerException
- 如果
newFormats
为空
public void setFormats(Format[] newFormats)
newFormats
中格式的顺序对应于模式字符串中格式元素的顺序。
如果模式字符串所需的格式多于其他格式,则忽略其余格式。 如果提供的格式少于所需的格式,那么只替换前newFormats.length
格式。
由于模式字符串中的格式元素的顺序在本地化期间经常发生变化,所以通常最好使用setFormatsByArgumentIndex
方法,该方法假定与传递给format
方法或结果数组的arguments
数组中的元素顺序相对应的格式顺序由parse
方法返回。
newFormats
- 使用的新格式
NullPointerException
- 如果
newFormats
为空
public void setFormatByArgumentIndex(int argumentIndex, Format newFormat)
format
方法的arguments
数组的索引或由parse
方法返回的结果数组。
如果参数索引用于模式字符串中的多个格式元素,则新格式将用于所有此类格式元素。 如果参数索引不用于模式字符串中的任何格式元素,则将忽略新格式。
argumentIndex
- 要使用新格式的参数索引
newFormat
- 要使用的新格式
public void setFormat(int formatElementIndex, Format newFormat)
由于模式字符串中的格式元素的顺序通常在本地化期间发生变化,所以通常最好使用setFormatByArgumentIndex
方法,该方法根据它们指定的参数索引来访问格式元素。
formatElementIndex
- 模式中格式元素的索引
newFormat
- 用于指定格式元素的格式
ArrayIndexOutOfBoundsException
- 如果
formatElementIndex
等于或大于模式字符串中格式元素的数量
public Format[] getFormatsByArgumentIndex()
format
方法的值的格式或从parse
方法返回的parse
。
返回数组中元素的索引对应于先前设置的模式字符串中使用的参数索引。
的返回的数组中的格式的顺序因此对应于在元素的顺序arguments
阵列传递给format
方法或由所述返回的结果阵列parse
方法。
如果模式字符串中的多个格式元素使用参数索引,则在数组中返回用于最后一个格式元素的格式。 如果模式字符串中的任何格式元素都不使用参数索引,则在数组中返回null。
public Format[] getFormats()
由于模式字符串中的格式元素的顺序通常在本地化期间发生变化,所以通常最好使用getFormatsByArgumentIndex
方法,该方法假定与传递给format
方法的arguments
数组中的元素顺序相对应的格式顺序或返回的结果数组按parse
方法。
public final StringBuffer format(Object[] arguments, StringBuffer result, FieldPosition pos)
MessageFormat
的格式(格式化元素替换为格式化对象)附加到所提供的StringBuffer
。
用于各个格式元素取代的文本被从格式元件的电流子格式和派生arguments
元件格式元素的参数索引在由下表的第一匹配线所示。 如果arguments
为null
或少于argumentIndex + 1元素,则参数不可用 。
"{" + argumentIndex + "}"
any null
"null"
instanceof ChoiceFormat
any subformat.format(argument).indexOf('{') >= 0 ?
(new MessageFormat(subformat.format(argument), getLocale())).format(argument) : subformat.format(argument)
!= null
any 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
any argument.toString()
如果pos
是非空,并且指的是Field.ARGUMENT
,将返回第一个格式化字符串的位置。
arguments
- 要格式化和替换的对象数组。
result
- 附加文本。
pos
- 在输入端:一个对齐字段,如果需要的话。
输出:对齐字段的偏移量。
result
,附带格式化的文本
IllegalArgumentException
- 如果
arguments
数组中的参数不是使用它的格式元素所期望的类型。
public static String format(String pattern, Object... arguments)
(new MessageFormat
(pattern)).format
(arguments, new StringBuffer(), null).toString()
pattern
- 模式字符串
arguments
- 要格式化的对象
IllegalArgumentException
- 如果模式无效,或者
arguments
数组中的参数不是使用它的格式元素所期望的类型。
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
数组中的参数不是使用它的格式元素所期望的类型。
public AttributedCharacterIterator formatToCharacterIterator(Object arguments)
MessageFormat
的模式中,生成一个AttributedCharacterIterator
。
您可以使用返回的AttributedCharacterIterator
构建生成的字符串,以及确定有关生成的字符串的信息。
返回的AttributedCharacterIterator
的文本与返回的文本相同
format
(arguments, new StringBuffer(), null).toString()
此外, AttributedCharacterIterator
至少包含属性,指示从arguments
数组中的参数生成文本的arguments
。 这些属性的键的类型为MessageFormat.Field
,它们的值为Integer
对象,指示生成文本的参数的arguments
数组中的索引。
来自MessageFormat
使用的底层Format
实例的属性/值也将放在结果AttributedCharacterIterator
。 这样,您不仅可以在生成的字符串中找到参数的位置,还可以找到它所包含的字段。
formatToCharacterIterator
在
Format
arguments
- 要格式化和替换的对象数组。
NullPointerException
- 如果
arguments
为空。
IllegalArgumentException
- 如果
arguments
数组中的参数不是使用它的格式元素所期望的类型。
public Object[] parse(String source, ParsePosition pos)
警告:在许多情况下,解析可能会失败。 例如:
source
- 要解析的字符串
pos
- 解析位置
public Object[] parse(String source) throws ParseException
source
- A
String
,其开头应解析。
Object
数组。
ParseException
- 如果指定字符串的开头不能被解析。
public Object parseObject(String source, ParsePosition pos)
该方法尝试从pos
给出的索引开始分析文本。 如果解析成功,那么在使用最后一个字符之后,索引pos
被更新为索引(解析不一定使用直到字符串末尾的所有字符),并且返回解析的对象数组。 更新后的pos
可用于指示下一次调用此方法的起始点。 如果发生错误,则pos
的索引不会更改,错误索引pos
设置为发生错误的pos
的索引,返回null。
有关消息解析的更多信息,请参阅parse(String, ParsePosition)
方法。
parseObject
在
Format
source
- A
String
,其中一部分应解析。
pos
ParsePosition
的索引和错误索引信息的
pos
- A
ParsePosition
对象。
Object
数组。
万一出错,返回null。
NullPointerException
- 如果
pos
为空。
public boolean equals(Object obj)
equals
在
Object
obj
- 用于比较的参考对象。
true
如果此对象与obj参数相同;
false
否则。
Object.hashCode()
, HashMap
public int hashCode()
hashCode
在
Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.