Класс MessageFormat

public class MessageFormat extends Format

Примечание о реализации:

В эталонной реализации предел ArgumentIndex равен 10 000.

Показывает, как значения FormatType и FormatStyle сопоставляются с экземплярами Format

FormatType	FormatStyle	Созданный Subformat

(none)	(none)	null
number	(none)	NumberFormat.getInstance(getLocale())
	integer	NumberFormat.getIntegerInstance(getLocale())
	currency	NumberFormat.getCurrencyInstance(getLocale())
	percent	NumberFormat.getPercentInstance(getLocale())
	compact_short	NumberFormat.getCompactNumberInstance(getLocale(), NumberFormat.Style.SHORT)
	compact_long	NumberFormat.getCompactNumberInstance(getLocale(), NumberFormat.Style.LONG)
	SubformatPattern	new DecimalFormat(subformatPattern, DecimalFormatSymbols.getInstance(getLocale()))
dtf_date	(none)	DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(getLocale())
	short	DateTimeFormatter.ofLocalizedDate(FormatStyle.SHORT).withLocale(getLocale())
	medium	DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(getLocale())
	long	DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).withLocale(getLocale())
	full	DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(getLocale())
	SubformatPattern	DateTimeFormatter.ofPattern(subformatPattern, getLocale())
dtf_time	(none)	DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM).withLocale(getLocale())
	short	DateTimeFormatter.ofLocalizedTime(FormatStyle.SHORT).withLocale(getLocale())
	medium	DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM).withLocale(getLocale())
	long	DateTimeFormatter.ofLocalizedTime(FormatStyle.LONG).withLocale(getLocale())
	full	DateTimeFormatter.ofLocalizedTime(FormatStyle.FULL).withLocale(getLocale())
	SubformatPattern	DateTimeFormatter.ofPattern(subformatPattern, getLocale())
dtf_datetime	(none)	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM).withLocale(getLocale())
	short	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT).withLocale(getLocale())
	medium	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM).withLocale(getLocale())
	long	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.LONG).withLocale(getLocale())
	full	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.FULL).withLocale(getLocale())
	SubformatPattern	DateTimeFormatter.ofPattern(subformatPattern, getLocale())
pre-defined DateTimeFormatter(s)	(none)	The pre-defined DateTimeFormatter(s) are used as a FormatType : BASIC_ISO_DATE, ISO_LOCAL_DATE, ISO_OFFSET_DATE, ISO_DATE, ISO_LOCAL_TIME, ISO_OFFSET_TIME, ISO_TIME, ISO_LOCAL_DATE_TIME, ISO_OFFSET_DATE_TIME, ISO_ZONED_DATE_TIME, ISO_DATE_TIME, ISO_ORDINAL_DATE, ISO_WEEK_DATE, ISO_INSTANT, RFC_1123_DATE_TIME
date	(none)	DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())
	short	DateFormat.getDateInstance(DateFormat.SHORT, getLocale())
	medium	DateFormat.getDateInstance(DateFormat.MEDIUM, 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.MEDIUM, getLocale())
long	DateFormat.getTimeInstance(DateFormat.LONG, getLocale())
full	DateFormat.getTimeInstance(DateFormat.FULL, getLocale())
SubformatPattern	new SimpleDateFormat(subformatPattern, getLocale())
choice	SubformatPattern	new ChoiceFormat(subformatPattern)
list	(none)	ListFormat.getInstance(getLocale(), ListFormat.Type.STANDARD, ListFormat.Style.FULL)
	or	ListFormat.getInstance(getLocale(), ListFormat.Type.OR, ListFormat.Style.FULL)
	unit	ListFormat.getInstance(getLocale(), ListFormat.Type.UNIT, ListFormat.Style.FULL}

Правила цитирования в шаблонах

Внутри String, пара одинарных кавычек может использоваться для цитирования произвольных символов, кроме одинарных кавычек. Например, строка шаблона "'{0}'" представляет строку "{0}", а не FormatElement. Сам одинарный апостроф должен быть представлен удвоенными одинарными апострофами '' в пределах String. Например, строка шаблона "'{''}'" интерпретируется как последовательность '{ (начало цитирования и левая фигурная скобка), '' (одинарный апостроф) и }' (правая фигурная скобка и конец цитирования), а не '{' и '}' (цитируемые левая и правая фигурные скобки): представляющие строку "{'}", а не "{}".

SubformatPattern интерпретируется соответствующим подформатом, и применяются правила шаблонов, зависящие от подформата. Например, строка шаблона "{1,number,$'#',##}" (SubformatPattern с подчеркиванием) создаст числовой формат с цитированным знаком фунта, с результатом, таким как: "$#31,45". Обратитесь к документации каждого подкласса Format для получения подробностей.

Любая несовпавшая кавычка обрабатывается как закрытая в конце данного шаблона. Например, строка шаблона "'{0}" обрабатывается как шаблон "'{0}'".

Все фигурные скобки в нецитируемом шаблоне должны быть сбалансированы. Например, "ab {0} de" и "ab '}' de" являются допустимыми шаблонами, но "ab {0'}' de", "ab } de" и "''{''" — нет.

Предупреждение:

Правила использования кавычек в шаблонах формата сообщений, к сожалению, оказались несколько запутанными. В частности, локализующим не всегда очевидно, нужно ли удваивать одинарные кавычки. Убедитесь, что вы информируете локализующих о правилах и указываете (например, с помощью комментариев в исходных файлах ресурсов), какие строки будут обрабатываться MessageFormat. Обратите внимание, что локализующим может потребоваться использовать одинарные кавычки в переведённых строках там, где исходная версия их не имеет.

Информация об использовании

Следующий пример демонстрирует общее использование 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 GregorianCalendar(2053, Calendar.JULY, 3, 12, 30).getTime(), event);

result возвращает следующее:

 At 12:30:00 PM on Jul 3, 2053, there was a disturbance in the Force on planet 7.
 

Для более сложных шаблонов, ChoiceFormat может быть использован с MessageFormat, чтобы создать точные формы для единственного и множественного числа:

MessageFormat msgFmt = new MessageFormat("The disk \"{0}\" contains {1,choice,0#no files|1#one file|1< {1,number,integer} files}.");
Object[] args = {"MyDisk", fileCount};
String result = msgFmt.format(args);

result с различными значениями для fileCount, возвращает следующее:

 The disk "MyDisk" contains no files.
 The disk "MyDisk" contains one file.
 The disk "MyDisk" contains 1,273 files.
 

Примечания: Как видно из предыдущего фрагмента, строка, сгенерированная ChoiceFormat в MessageFormat, обрабатывается как специальная; вхождения '{' используются для указания подформатов и вызывают рекурсию. Если FormatElement определена в шаблоне ChoiceFormat, она будет отформатирована только в соответствии с шаблонами FormatType и FormatStyle. Сопутствующие подформаты верхнего уровня MessageFormat не будут применяться к FormatElement, определённому в шаблоне ChoiceFormat. Если вы создаёте как MessageFormat, так и ChoiceFormat программно (вместо использования строковых шаблонов), будьте осторожны, чтобы не создать формат, который вызывает рекурсию на себя, что приведёт к бесконечной петле.

Форматирование даты и времени

MessageFormat предоставляет шаблоны, поддерживающие форматировщики даты/времени в пакетах java.time.format и java.text. Рассмотрим следующие три примера с датой 16.11.2023:

1) дата FormatType с полным FormatStyle,

Object[] arg = {new GregorianCalendar(2023, Calendar.NOVEMBER, 16).getTime()};
var fmt = new MessageFormat("The date was {0,date,full}");
fmt.format(arg); // returns "The date was Thursday, November 16, 2023"

2) dtf_дата FormatType с полным FormatStyle,

Object[] arg = {LocalDate.of(2023, 11, 16)};
var fmt = new MessageFormat("The date was {0,dtf_date,full}");
fmt.format(arg); // returns "The date was Thursday, November 16, 2023"

3) ISO_LOCAL_DATE FormatType,

Object[] arg = {LocalDate.of(2023, 11, 16)};
var fmt = new MessageFormat("The date was {0,ISO_LOCAL_DATE}");
fmt.format(arg); // returns "The date was 2023-11-16"

Разбор

Когда один аргумент анализируется более одного раза в строке, последняя совпавшая часть будет конечным результатом разбора. Например,

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));
// objs now equals {new String("z")}

Синхронизация

Форматы сообщений не синхронизированы. Рекомендуется создавать отдельные экземпляры форматов для каждого потока. Если к формату обращаются несколько потоков одновременно, необходимо обеспечить внешнюю синхронизацию.

Since:

1.1

См. также:

• Locale
• Format
• NumberFormat
• DecimalFormat
• DecimalFormatSymbols
• ChoiceFormat
• DateFormat
• SimpleDateFormat
• DateTimeFormatter
• Serialized Form