Класс MessageFormat

public class MessageFormat extends Format

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

В эталонной реализации ограничение ArgumentIndex составляет 10 000.

Shows how FormatType and FormatStyle values map to Format instances

Тип формата	Стиль формата	Создаваемый подформат
(нет)	(нет)	null
number	(нет)	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	(нет)	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	(нет)	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	(нет)	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)	(нет)	Значения pre-defined DateTimeFormatter(s) используются в качестве 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	(нет)	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	(нет)	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	(нет)	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, обрабатывается особым образом: вхождения «{» используются для обозначения подформатов и вызывают рекурсивную обработку. Если в шаблоне ChoiceFormat определён FormatElement, он будет отформатирован только в соответствии с предоставленными шаблонами FormatType и FormatStyle. Связанные подформаты объекта MessageFormat верхнего уровня не будут применены к FormatElement, определённому в шаблоне ChoiceFormat. Если вы создаёте программно и MessageFormat, и ChoiceFormat (вместо использования строковых шаблонов), следите за тем, чтобы не создать формат, рекурсивно ссылающийся на себя, поскольку это приведёт к бесконечному циклу.

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

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

1) шаблон date FormatType с параметром full 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_date FormatType с параметром full 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")}

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

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

Появился в версии:

1.1

См. также:

• Locale
• Format
• NumberFormat
• DecimalFormat
• DecimalFormatSymbols
• ChoiceFormat
• DateFormat
• SimpleDateFormat
• DateTimeFormatter
• Сериализованная форма