Функция Format

Статья
04/07/2023

Возвращает Variant (String), содержащий выражение expression, отформатированное в соответствии с инструкциями, включенными в выражение формата.

Примечание.

Хотите создавать решения, которые расширяют возможности Office на разнообразных платформах? Ознакомьтесь с новой моделью надстроек Office. Надстройки Office занимают меньше места по сравнению с надстройками и решениями VSTO, и вы можете создавать их, используя практически любую технологию веб-программирования, например HTML5, JavaScript, CSS3 и XML.

Синтаксис

Format(Expression, [ Format ], [ FirstDayOfWeek ], [ FirstWeekOfYear ])

Синтаксис функции Format состоит из следующих частей:

Часть	Описание
Expression	Обязательный атрибут. Любое допустимое выражение.
Format	Необязательный атрибут. Допустимое именованное или определяемое пользователем выражение формата.
FirstDayOfWeek	Необязательный атрибут. Константа, задающая первый день недели.
FirstWeekOfYear	Необязательный атрибут. Константа, задающая первую неделю года.

Параметры

Аргумент firstdayofweekимеет эти параметры.

Константа	Значение	Описание
vbUseSystem	0	Использовать настройку API многоязыковой поддержки.
vbSunday	1	Воскресенье (по умолчанию)
vbMonday	2	Понедельник
vbTuesday	3	Вторник
vbWednesday	4	Среда
vbThursday	5	Четверг
vbFriday	6	Пятница
vbSaturday	7	Суббота

Аргумент firstweekofyearимеет эти параметры.

Константа	Значение	Описание
vbUseSystem	0	Использовать настройку API многоязыковой поддержки.
vbFirstJan1	1	Начать с недели, содержащей 1 января (по умолчанию).
vbFirstFourDays	2	Начать с первой недели, в которой имеется по крайней мере четыре дня в данном году.
vbFirstFullWeek	3	Начать с первой полной недели года.

Примечания

Чтобы отформатировать	Сделайте следующее
Числа	Используйте предопределенные именованные числовые форматы или создайте числовые форматы, определяемые пользователем.
Даты и время	Используйте предопределенные именованные форматы даты и времени или создайте числовые форматы, определяемые пользователем.
Даты и время, представленные числами	Используйте именованные форматы даты и времени или создайте числовые форматы.
Строки	Создайте свои собственные определяемые пользователем строковые форматы.

Функция Format усекает format до 257 символов.

Если вы попытаетесь форматировать числа без задания атрибута format, функция Format предоставит функциональность, аналогичную функции Str, хотя и с поддержкой международных форматов. Однако положительные числа, отформатированные как строки с использованием функции Format, не будут включать начальный пробел, зарезервированный для знака или значения; в случае же преобразования с помощью функции Str начальный пробел сохранится.

При форматировании нелокализованных числовых строк, следует использовать определяемый пользователем числовой формат, чтобы обеспечить получение желаемых результатов.

Примечание.

Если свойству Calendar присвоено значение Gregorian и format задает форматирование даты, выдаваемым expression должно быть Gregorian. Если свойство Календарь Visual Basic имеет Hijriзначение , предоставленное выражение должно иметь значение Hijri.

Если используется григорианский календарь, значение символов выражения format не изменяется. Если используется календарь Хиджра, все символы формата даты (например, dddd, mmmm, yyyy) имеют то же значение, но применяются к календарю Хиджра. Символы формата остаются английскими; символы, отображаемые в текстовом виде (например, AM и PM), отображают строку (на английском или арабском языке), связанную с этим символом. Диапазон некоторых символов при использовании календаря Хиджра изменяется.

Символы даты

Символ	Диапазон
d	1–31 (день месяца без нуля в начале)
dd	01–31 (день месяца с нулем в начале)
w	1–7 (день недели, начиная с воскресенья = 1)
ww	1–53 (неделя года без нуля в начале; неделя 1 начинается с 1 января)
m	1–12 (месяц года без нуля в начале, начиная с января = 1)
mm	01–12 (месяц года с нулем в начале, начиная с января = 01)
mmm	Отображает сокращенное название месяца (в названии месяцев Хиджра нет сокращений)
mmmm	Отображает полное название месяца
y	1–366 (день года)
yy	00–99 (последние две цифры года)
yyyy	100–9999 (год из трех или четырех цифр)

Символы времени

Символ	Диапазон
h	0–23 (1–12 с добавлением "AM" или "PM") (час суток без нуля в начале)
hh	00–23 (01–12 с добавлением "AM" или "PM") (час суток с нулем в начале)
n	0–59 (минута часа без нуля в начале)
nn	00–59 (минута часа с нулем в начале)
m	0–59 (минута часа без нуля в начале). Только если находится после h или hh
mm	00–59 (минута часа с нулем в начале). Только если находится после h или hh
s	0–59 (секунда минуты без нуля в начале)
ss	00–59 (секунда минуты с нулем в начале)

Пример

В этом примере показываются различные варианты использования функции Format для форматирования значений с использованием как именованных форматов, так и форматов, определяемых пользователем. Отображение разделителей даты (/), времени (:) и литерала AM/PM зависит от языковых настроек системы, в среде которой выполняется код. При отображении времени и дат в среде разработки используются краткие форматы даты и времени, определяемые настройками языка для кода. При их отображении в процессе выполнения кода используются краткие форматы даты и времени языка системы, которые могут отличаться от настроек языка для кода. В этом примере подразумевается использование языка "Английский (США)". Элементы MyTime и MyDate отображаются в среде разработки с использованием текущих кратких форматов даты и времени языка системы.

Dim MyTime, MyDate, MyStr
MyTime = #17:04:23#
MyDate = #January 27, 1993#

' Returns current system time in the system-defined long time format.
MyStr = Format(Time, "Long Time")

' Returns current system date in the system-defined long date format.
MyStr = Format(Date, "Long Date")

MyStr = Format(MyTime, "h:m:s")    ' Returns "17:4:23".
MyStr = Format(MyTime, "hh:mm:ss am/pm")    ' Returns "05:04:23 pm".
MyStr = Format(MyTime, "hh:mm:ss AM/PM")    ' Returns "05:04:23 PM".
MyStr = Format(MyDate, "dddd, mmm d yyyy")    ' Returns "Wednesday, Jan 27 1993".
' If format is not supplied, a string is returned.
MyStr = Format(23)    ' Returns "23".

' User-defined formats.
MyStr = Format(5459.4, "##,##0.00")    ' Returns "5,459.40".
MyStr = Format(334.9, "###0.00")    ' Returns "334.90".
MyStr = Format(5, "0.00%")    ' Returns "500.00%".
MyStr = Format("HELLO", "<")    ' Returns "hello".
MyStr = Format("This is it", ">")    ' Returns "THIS IS IT".

Различные форматы для различных числовых значений

В определяемом пользователем expression формата для чисел может иметься от одного до четырех разделов, отделяемых друг от друга точками с запятой. Если аргумент формата содержит один из именованных числовых форматов, допускается использование только одного раздела.

Если используется	Результат
Только один раздел	Выражение формата применяется ко всем значениям.
Два раздела	Первый раздел применяется к положительным значениям и нулям, второй — к отрицательным значениям.
Три раздела	Первый раздел применяется к положительным значениям, второй — к отрицательным значениям, третий — к нулям.
Четыре раздела	Первый раздел применяется к положительным значениям, второй — к отрицательным значениям, третий — к нулям, четвертый — к значениям Null.

"$#,##0;($#,##0)"

Если записать знаки точки с запятой без кода между ними, то отсутствующий раздел будет печататься с использованием формата положительного значения. Например, следующий формат отображает положительные и отрицательные значения с использованием формата первого раздела и отображает "Zero", если значением является нуль.

"$#,##0;;\Z\e\r\o"

Различные форматы для различных строковых значений

В expression формата для строк может иметься один раздел или два раздела, отделяемых друг от друга точками с запятой (;).

Если используется	Результат
Только один раздел	Формат применяется ко всем строковым данным.
Два раздела	Первый раздел применяется к строковым данным, второй — к значениям Null и пустым строкам ("").

Именованные форматы даты и времени

В следующей таблице указываются предопределенные имена форматов даты и времени.

Имя формата	Описание
General Date	Отображение даты и/или времени, например 4/3/93 05:34 PM. Если дробная часть отсутствует, отображается только дата, например 4/3/93. Если отсутствует целая часть, отображается только время, например 05:34 PM. Отображение даты определяется параметрами системы.
Long Date	Отображение даты в соответствии с длинным форматом даты, используемым в системе.
Medium Date	Отображение даты с использованием среднего формата даты, соответствующего языковой версии ведущего приложения.
Short Date	Отображение даты в соответствии с кратким форматом даты, используемым в системе.
Long Time	Отображение времени в соответствии с длинным форматом даты, используемым в системе; включает часы, минуты и секунды.
Medium Time	Отображение времени в 12-часовом формате с использованием часов, минут и указателя AM/PM.
Short Time	Отображение времени в 24-часовом формате, например 17:45.

Именованные числовые форматы

В следующей таблице указываются предопределенные имена числовых форматов.

Имя формата	Описание
General Number	Отображение числа без знака разделителя групп разрядов.
Currency	Отображение числа с использованием разделителя групп разрядов, если это необходимо; отображаются две цифры справа от разделителя целой и дробной части. Вывод основывается на языковых настройках системы.
Fixed	Отображение по крайней мере одной цифры слева и двух цифр справа от разделителя целой и дробной части.
Standard	Отображение числа с использованием разделителя групп разрядов; отображаются по крайней мере одна цифра слева и две цифры справа от разделителя целой и дробной части.
Percent	Отображение числа, умноженного на 100 со знаком процента (%), добавляемого справа; всегда отображаются две цифры справа от разделителя целой и дробной части.
Scientific	Используется стандартное экспоненциальное представление.
Yes/No	Отображается "Нет", если число равняется 0; в противном случае отображается "Да".
True/False	Отображается False, если число равняется 0; в противном случае отображается True.
On/Off	Отображается "Вкл", если число равняется 0; в противном случае отображается "Выкл".

Определяемые пользователем строковые форматы

Используйте любой из следующих знаков для создания expression формата для строк.

Знак	Описание
@	Заполнитель для символов. Отображает знак или пробел. Если в строке имеется знак на позиции, в которой в строке форматирования располагается at-символ (@), отображается этот знак; в противном случае на этой позиции отображается пробел. Заполнители заполняются справа налево, если только в строке форматирования не будет представлен восклицательный знак (!).
&	Заполнитель для символов. Отображает знак или ничего не отображает. Если строка содержит символ в позиции, где отображается амперсанд (&), отобразите его; В противном случае ничего не отображать. Заполнители заполняются справа налево, если только в строке форматирования не будет представлен восклицательный знак (!).
<	Принудительное отображение нижнего регистра. Отображение всех знаков в формате нижнего регистра.
>	Принудительное отображение верхнего регистра. Отображение всех знаков в формате верхнего регистра.
!	Принудительное заполнение заполнителей в порядке слева направо. По умолчанию заполнители заполняются справа налево.

Определяемые пользователем форматы даты и времени

В следующей таблице указываются знаки, которые могут использоваться при создании определяемых пользователем форматов даты и времени.

Знак	Описание
(:)	Разделитель компонентов времени. В некоторых языковых стандартах могут использоваться другие знаки для представления разделителя компонентов времени. Этот разделитель отделяет часы, минуты и секунды, когда значения времени форматируются. Символ, используемый в качестве разделителя компонентов времени в отформатированных выходных данных, определяется параметрами системы.
(/)	Разделитель компонентов даты. В некоторых языковых стандартах могут использоваться другие знаки для представления разделителя компонентов даты. Этот разделитель отделяет день, месяц и год, когда значения даты форматируются. Символ, используемый в качестве разделителя компонентов даты в отформатированных выходных данных, определяется параметрами системы.
c	Отображение даты в формате `ddddd` и отображение времени в формате `ttttt` (в этом порядке). Отображение только информации о дате, если отсутствует дробная часть в дате, представленной числом; отображение только информации о времени, если отсутствует целая часть.
d	Отображение дня в виде числа без нуля в начале (1–31).
dd	Отображение дня в виде числа с нулем в начале (01–31).
ddd	Отображение дня в виде сокращения (вс–сб). Локализовано.
dddd	Отображение дня в виде полного имени (с воскресенья по субботу). Локализовано.
ddddd	Отображение даты с использованием полного формата (включая день, месяц и год), соответствующего краткому формату даты в настройках системы. Кратким форматом даты по умолчанию является `m/d/yy`.
dddddd	Отображение числа, представляющего дату, с использованием полного формата (включая день, месяц и год), соответствующего длинному формату даты в настройках системы. Длинным форматом даты по умолчанию является `mmmm dd, yyyy`.
w	Отображение дня недели в виде числа (от 1 для воскресенья и до 7 для субботы).
ww	Отображение недели года в виде числа (1–54).
m	Отображение месяца в виде числа без начального нуля (1–12). Если `m` следует сразу же после `h` или `hh`, отображаться будет не месяц, а минута.
mm	Отображение месяца в виде числа с нулем в начале (01–12). Если `m` следует сразу же после `h` или `hh`, отображаться будет не месяц, а минута.
mmm	Отображение месяца в виде сокращения (январь–декабрь). Локализовано.
mmmm	Отображение месяца в виде полного названия месяца (январь–декабрь). Локализовано.
q	Отображение квартала года в виде числа (1–4).
y	Отображение дня года в виде числа (1–366).
yy	Отображение года в виде двухзначного числа (00–99).
yyyy	Отображение года в виде 4-значного числа (100–9999).
h	Отображение часа в виде числа без нуля в начале (0–23).
hh	Отображение часа в виде числа с нулем в начале (00–23).
n	Отображает минуту в виде числа без начального нуля (0–59).
nn	Отображает минуту в виде числа с нулем в начале (00–59).
s	Отображение второго в виде числа без нуля в начале (0–59).
ss	Отображение второго в виде числа с нулем в начале (00–59).
ttttt	Отображение времени в полном формате (включая час, минуту и секунду) с использованием разделителя компонентов времени, определенного в формате времени, указанного в настройках системы. Начальный нуль отображается, если выбран параметр "Ноль в начале" и время до 10:00 или вечера Формат времени по умолчанию — `h:mm:ss`.
AM/PM	Используется 12-часовой формат и отображается указатель AM в верхнем регистре с любым часом до полудня; отображается указатель PM в верхнем регистре с любым часом между полуднем и 11:59 P.M.
am/pm	Используется 12-часовом формат и отображается указатель AM в нижнем регистре с любым часом до полудня; отображается указатель PM в нижнем регистре с любым часом между полуднем и 11:59 P.M.
A/P	Используется 12-часовом формат и отображается указатель A в верхнем регистре с любым часом до полудня; отображается указатель P в верхнем регистре с любым часом между полуднем и 11:59 P.M.
a/p	Используется 12-часовом формат и отображается указатель A в нижнем регистре с любым часом до полудня; отображается указатель P в нижнем регистре с любым часом между полуднем и 11:59 P.M.
AMPM	Используйте 12-часовые часы и отображайте строковый литерал AM в соответствии с определением вашей системы за любой час до полудня; отображение строкового литерала PM в соответствии с определением вашей системы с любым часом между полуднем и 11:59 P.M. AMPM может быть прописным или нижним регистром, но регистр отображаемой строки соответствует строке, определенной в параметрах системы. Форматом по умолчанию является AM/PM. Если вашей системе установлен 24-часовой формат, эта строка обычно устанавливается пустой.

Определяемые пользователем числовые форматы

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

Знак	Описание
Нет	Отображение числа без форматирования.
(0)	Заполнитель цифры. Отображает цифру или нуль. Если в expression имеется цифра на позиции в строке форматирования, где стоит 0, отображается эта цифра; в противном случае на этой позиции отображается нуль. Если число имеет меньше цифр, чем нулей (по любую сторону от десятичного разделителя) в выражении формата, отображаются нули в начале или в конце. Если число имеет больше цифр, чем нулей справа от разделителя целой и дробной части в выражении формата, число округляется, чтобы число десятичных разрядов соответствовало количеству нулей. Если число имеет больше цифр, чем нулей слева от разделителя целой и дробной части в выражении формата, отображается дополнительное количество цифр без изменения.
(#)	Заполнитель цифры. Отображает цифру или ничего не отображает. Если в выражении имеется цифра на позиции в строке форматирования, где стоит #, отображается эта цифра; в противном случае на этой позиции отображается нуль. Этот символ работает, как заполнитель цифры 0, за исключением того, что нули в начале и в конце не отображаются, если в числе имеется столько же или меньше знаков # по любую сторону от разделителя целой и дробной части в выражении формата.
(.)	Заполнитель десятичного разделителя. В некоторых языковых стандартах в качестве разделителя целой и дробной части используется запятая. Заполнитель десятичного разделителя определяет, сколько цифр отображается слева и справа от разделителя целой и дробной части. Если выражение формата содержит только знаки числа слева от этого символа, то числа меньше 1 начинаются с разделителя целой и дробной части. Чтобы отобразить нуль в начале дробного числа, используйте 0 в качестве заполнителя первой цифры слева от разделителя целой и дробной части. Фактический знак, используемый в качестве заполнителя десятичного разделителя в форматированном выводе значений, зависит от параметра "Числовой формат", заданного в вашей системе.
(%)	Заполнитель процента. Выражение умножается на 100. Знак процента (%) вставляется на позиции, на которой он указан в строке формата.
(,)	Разделитель групп разрядов. В некоторых языковых стандартах в качестве разделителя групп разрядов используется пробел. Разделитель групп разрядов отделяет тысячи от сотен внутри числа, в котором имеется четыре или более цифр слева от разделителя целой и дробной части. Стандарт использования разделителя групп разрядов указывается, если формат содержит разделитель групп разрядов в окружении заполнителей цифр (0 или #). Два смежных разделителя тысячи или тысяча разделителей сразу слева от десятичного разделителя (независимо от того, указана ли десятичная дробь) означает "масштаб числа, разделив его на 1000, округляя по мере необходимости". Например, можно использовать строку формата "##0," для представления 100 миллионов как 100. Числа меньше 1 миллиона отображаются тогда как 0. Два последовательных разделителя групп разрядов, расположенные на любой позиции, но не непосредственно слева от разделителя целой и дробной части, просто указывают на использование разделителя групп разрядов. Фактический знак, используемый в качестве разделителя групп разрядов в форматированном выводе значений, зависит от параметра "Числовой формат", заданного в вашей системе.
(:)	Разделитель компонентов времени. В некоторых языковых стандартах могут использоваться другие знаки для представления разделителя компонентов времени. Этот разделитель отделяет часы, минуты и секунды, когда значения времени форматируются. Символ, используемый в качестве разделителя компонентов времени в отформатированных выходных данных, определяется параметрами системы.
(/)	Разделитель компонентов даты. В некоторых языковых стандартах могут использоваться другие знаки для представления разделителя компонентов даты. Этот разделитель отделяет день, месяц и год, когда значения даты форматируются. Символ, используемый в качестве разделителя компонентов даты в отформатированных выходных данных, определяется параметрами системы.
(E- E+ e- e+)	Экспоненциальный формат. Если выражение формата содержит по крайней мере один заполнитель цифры (0 или #) справа от E-, E+, e- или e+, данное число отображается в экспоненциальном формате и между числом и его показателем степени вставляется знак E или e. Количество заполнителей цифр справа определяет число цифр в показателе степени. Используйте знаки E- или e-, чтобы поместить знак минуса рядом с отрицательными показателями степени. Используйте знаки E+ или e+, чтобы поместить знак плюса рядом с положительными показателями степени.
- + $ ( )	Отображение знака литерала. Чтобы отобразить знак, отличный от указанных здесь, запишите перед ним знак обратной косой черты (`\`) или заключите его в двойные кавычки (" ").
(\)	Отображение знака, стоящего после него в строке формата. Чтобы отобразить какой-либо знак, имеющий специальное значение, как знак литерала, запишите перед ним знак обратной косой черты (`\`). Сам знак обратной косой черты при этом не отображается. Использование знака обратной косой черты аналогично по своему действию заключению соответствующего знака в двойные кавычки. Чтобы отобразить обратную косую черту, необходимо записать два таких знака (`\\`). Примерами символов, которые не могут отображаться в виде литеральных символов, являются символы форматирования даты и времени (a, c, d, h, m, n, p, q, s, t, w, y, /, и :), символы форматирования чисел (#, 0, %, %, E, e, запятая и точка) и символы форматирования строк (@, &, <, , >и !).
("ABC")	Отображение строки в двойных кавычках (" "). Чтобы включить строку в *format* непосредственно из кода, необходимо использовать Chr(34), чтобы заключить текст (34 — это код знака для знака кавычки (")).

См. также

Функции (Visual Basic для приложений)

Поддержка и обратная связь

Есть вопросы или отзывы, касающиеся Office VBA или этой статьи? Руководство по другим способам получения поддержки и отправки отзывов см. в статье Поддержка Office VBA и обратная связь.