Função Format

  • Artigo

Retorna uma Variant (String) contendo uma expressão formatada de acordo com instruções contidas em uma expressão de formato.

Observação

Interessado em desenvolver soluções que ampliem a experiência do Office em várias plataformas? Confira o novo modelo de Suplementos do Office. Os suplementos do Office ocupam um pequeno espaço em comparação com os suplementos e as soluções do VSTO, e você pode criá-los usando quase qualquer tecnologia de programação da Web, como o HTML5, JavaScript, CSS3 e XML.

Sintaxe

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

A sintaxe da função Format tem as seguintes partes.

Parte Descrição
Expressão. Obrigatório. Qualquer expressão válida.
Format Opcional. Uma expressão de formato nomeada ou definida pelo usuário válida.
FirstDayOfWeek Opcional. Uma constante que especifica o primeiro dia da semana.
FirstWeekOfYear Opcional. Uma constante que especifica a primeira semana do ano.

Configurações

O argumento firstdayofweek tem essas configurações.

Constant Valor Descrição
vbUseSystem 0 Use a configuração de API NLS.
vbSunday 1 Domingo (padrão)
vbMonday 2 Segunda-feira
vbTuesday 3 Terça-feira
vbWednesday 4 Quarta-feira
vbThursday 5 Quinta-feira
vbFriday 6 Sexta-feira
vbSaturday 7 Sábado

O argumentofirstweekofyear tem essas configurações.

Constant Valor Descrição
vbUseSystem 0 Use a configuração de API NLS.
vbFirstJan1 1 Comece com a semana em que ocorre 1 de janeiro (padrão).
vbFirstFourDays 2 Inicia na primeira semana do ano a ter pelo menos quatro dias.
vbFirstFullWeek 3 Inicia na primeira semana completa do ano.

Comentários

Para formatar Faça isto
Números Use formatos numéricos nomeados pré-definidos ou crie formatos numéricos definidos pelo usuário.
Datas e horas Use formatos nomeados pré-definidos ou crie formatos data/hora definidos pelo usuário.
Números de série de data e hora Use formatos de data e hora ou formatos numéricos.
Cadeias de caracteres Crie os seus próprios formatos de cadeia de caracteres definidos pelo usuário.

O Formato trunca o formato para 257 caracteres.

Se você tentar formatar um número sem especificar formato, Formato proporcionará uma funcionalidade semelhante à função Str, embora esteja ciente internacionalmente. No entanto, os números positivos formatados como cadeias de caracteres usando formato não incluem um espaço à esquerda reservado para a entrada do valor; aqueles convertidos usando Str mantêm os espaços à esquerda.

Se você estiver formatando uma cadeia de caracteres numérica não localizada, deverá usar um formato numérico definido pelo usuário para garantir que obtém a aparência desejada.

Observação

Se a configuração de propriedadecalendário for Gregorian e oformato especificar a data de formatação, a expressão fornecida deve ser Gregorian. Se a configuração da propriedade Calendário Do Visual Basic for Hijri, a expressão fornecida deverá ser Hijri.

Se o calendário for gregoriano, o significado dos símbolos de expressão de formato é inalterado. Se o calendário for Hijri, todos os símbolos de formato de data (por exemplo, dddd, mmmm, aaaa ), têm o mesmo significado mas se aplicam ao calendário islâmico. Os símbolos de formato permanecerão em inglês; símbolos que resultam na exibição de texto (por exemplo, AM e PM) exibem a cadeia de caracteres (em inglês ou árabe) associada a esse símbolo. O intervalo de determinados símbolos muda quando o calendário islâmico é.

Símbolos de data

Símbolo Intervalo
d 1-31 (dia do mês, sem zero à esquerda)
dd 01 a 31 (dia do mês com zero à esquerda)
w 1 a 7 (dia da semana, começando com domingo = 1)
ww 1-53 (semana do ano, sem zero à esquerda; Início da semana 1 em 1º de janeiro)
m 1 a 12 (mês do ano, sem zero à esquerda, começando com janeiro = 1)
mm 01 a 12 (mês do ano, com zero à esquerda, começando com janeiro = 01)
mmm Exibe nomes de meses abreviados (Nomes de meses Hijri não têm abreviações).
mmmm Exibe nomes de meses completos
y 1 a 366 (dia do ano)
yy 00 – 99 (dois últimos dígitos do ano)
yyyy 100-9999 (três ou quatro dígitos do ano)

Símbolos de tempo

Símbolo Intervalo
h 0 a 23 (1 a 12 com "AM" ou "PM" acrescentado) (hora do dia sem zero à esquerda)
hh 00 a 23 (01 – 12 com "AM" ou "PM" acrescentado) (hora do dia com zero à esquerda)
n 0 a 59 (minuto da hora sem zero à esquerda)
nn 00 a 59 (minuto da hora, com zero à esquerda)
m 0 a 59 (minuto da hora, sem zero à esquerda). Somente se precedida por h ou hh
mm 00 a 59 (minuto da hora com zero à esquerda). Somente se precedida por h ou hh
s 0 a 59 (segundo do minuto, sem zero à esquerda)
ss 00 a 59 (segundo do minuto com zero à esquerda)

Exemplo

Este exemplo mostra usos da função Formato para formatar valores usando formatos nomeados e formatos definidos pelo usuário. Para o separador de data (/), separador de hora (:) e AM / PM literal, a saída formatada real exibida ao seu sistema depende das configurações de localidade no qual o código está em execução. Quando horários e datas são exibidos no ambiente de desenvolvimento, o formato de hora abreviada e o formato de data abreviada da localidade código são usados. Quando exibidos executando o código, o formato de hora abreviada e o formato de data abreviada da localidade do sistema são usados, e podem ser diferentes do local do código. Por exemplo, English/U.S. será considerado. MyTime e MyDate são exibidos no ambiente de desenvolvimento usando a configuração atual de data abreviada e configuração de hora abreviada.

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".

Formatos diferentes para valores numéricos diferentes.

Um formato definido pelo usuário expressão para os números podem ter de uma a quatro seções separadas por ponto e vírgula. Se o formato argumento contém um dos formatos numéricos nomeados, apenas uma seção é permitida.

Se você usar O resultado é
Somente uma seção A expressão de formato se aplica a todos os valores.
Duas seções A primeira seção se aplica a valores positivos e zeros, a segunda a valores negativos.
Três seções A primeira seção se aplica a valores positivos, a segunda a valores negativos e a terceira a zeros.
Quatro seções A primeira seção se aplica a valores positivos, a segunda a valores negativos, a terceira a zeros e a quarta a valores Nulo. 
"$#,##0;($#,##0)"

Se você incluir pontos e vírgulas com nada entre eles, a seção em falta será impressa usando o formato do valor positivo. Por exemplo, o seguinte formato exibe os valores positivos e negativos usando a formatação da primeira seção e exibe "Zero" se o valor é zero.

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

Formatos diferentes para valores de cadeia de caracteres diferentes

Uma expressão de formato para cadeias de caracteres pode conter uma seção ou duas seções separadas por um ponto e vírgula (;).

Se você usar O resultado é
Somente uma seção O formato se aplica a todos os dados de cadeia de caracteres.
Duas seções A primeira seção se aplica a dados de cadeia de caracteres, a segunda a valores Nulo e cadeias de caracteres de comprimento nulo ("").

Formatos de data/hora

A tabela a seguir identifica os nomes de formato de data e hora pré-definidos.

Nome do formato Descrição
General Date Exibir uma data / hora, por exemplo, 3/4/93 05:34PM. Se não houver nenhuma parte fracionária, apenas a data é exibida, por exemplo, 3/4/93. Se não houver nenhuma parte inteira, apenas a hora é exibida, por exemplo, 05:34PM. A exibição da data é determinada pela seus ajustes.
Long Date Exibe uma data de acordo com o formato de data longo do seu sistema.
Medium Date Exibe uma data usando o formato de data média apropriado para a versão de aplicativo host.
Short Date Exibe uma data usando o formato de data curto do seu sistema.
Long Time Exibe uma hora usando o formato de hora longo do seu sistema; inclui horas, minutos e segundos.
Medium Time Exibe a hora no formato de 12 horas usando horas e minutos e o designador AM/PM.
Short Time Exibe uma hora usando o formato de 24 horas, por exemplo, 17:45.

Formatos numéricos definidos

A tabela a seguir identifica os nomes de formatos numéricos pré-definidos.

Nome do formato Descrição
General Number Exibe o número sem o separador de milhar.
Currency Exibe o número com o separador de milhar, se apropriado; exibe dois dígitos à direita do separador decimal.. A saída se baseia no sistema de configurações de localidade.
Fixed Exibe no mínimo um dígito à esquerda e dois dígitos à direita do separador de decimal.
Standard Exibe o número com o separador de milhar, no mínimo um dígito à esquerda e dois dígitos à direita do separador decimal.
Percent Exibe número multiplicado por 100 com um símbolo de percentual (%) à direita; sempre exibe dois dígitos à direita do separador decimal.
Scientific Usa a notação científica padrão.
Yes/No Exibe Não se o número for 0; caso contrário, exibe Sim.
True/False Exibe False se o número for 0; caso contrário, exibe True.
On/Off Exibe Desligado se o número for 0; caso contrário, exibe Ligado.

Formatos definidos pelo usuário

Você pode usar qualquer um dos seguintes caracteres para criar uma expressão de formato para cadeias de caracteres.

Caractere Descrição
@ Espaço reservado para o caractere. Exibe um espaço ou um caractere. Se a cadeia de caracteres tiver um caractere na posição onde o símbolo (@) aparece na cadeia de caracteres formato exiba-o, caso contrário, exiba um espaço nessa posição. Espaços reservados são preenchidos da direita para a esquerda, a menos que haja um caractere de ponto de exclamação (!) na cadeia de caracteres de formato.
& Espaço reservado para o caractere. Exibe um caractere ou nada. Se a cadeia de caracteres tiver um caractere na posição onde o símbolo de E comercial (&) aparece, exibe-o; caso contrário, não exibe nada. Espaços reservados são preenchidos da direita para a esquerda, a menos que haja um caractere de ponto de exclamação (!) na cadeia de caracteres de formato.
< Força minúsculas. Exibe todos os caracteres no formato de minúsculas.
> Forçar letras maiúsculas. Exibe todos os caracteres no formato de maiúsculas.
! Force da esquerda para direita preenchimento espaços reservados. O padrão é preencher espaços reservados da direita para a esquerda.

Formatos de data/hora definidos pelo usuário

A tabela a seguir identifica caracteres que você pode usar para criar formatos de data/hora definidos pelo usuário.

Caractere Descrição
(:) Separador de hora. Em algumas localidades, outros caracteres podem ser usados para representar o separador de hora. O separador de hora separa horas, minutos e segundos quando os valores de tempo são formatados. O caractere usado como separador de hora no formato saída será determinado pelas configurações seu sistema.
(/) Separador de dados. Em alguns locais outros caracteres podem ser usados para representar o separador de data. O separador de data separa o dia, mês e ano quando os valores de data são formatados. O caractere usado como o separador de data no formato de saída será determinado pelas configurações seu sistema.
c Exibe a data como ddddd e exibe a hora como ttttt, nessa ordem. Somente exibe as informações de data se não houver parte fracionada no número de série de data; exibe somente informações de hora se não houver porção de inteiro.
d Exiba o dia como um número sem um zero à frente (1 a 31).
dd Exiba o dia como um número com um zero à frente (01 a 31).
ddd Exiba o dia como uma abreviação (Dom-sáb). Localizar.
dddd Exiba o dia como um nome completo (domingo a sábado). Localizar.
ddddd Exibe a data como data completa (incluindo dia, mês e ano), formatada de acordo com a configuração de formato de data curta do seu sistema. O formato de data abreviada padrão é m/d/yy.
dddddd Exibe um número de série de data como uma data completa (incluindo dia, mês e ano) formatada de acordo com a configuração de formato de data longa reconhecida pelo seu sistema. O formato de data por extenso padrão é mmmm dd, yyyy.
w Exibe o dia da semana como um número (1 para Domingo até 7 para Sábado).
ss Exiba a semana do ano como um número (1 a 54).
m Exiba o mês como um número sem um zero à frente (1 a 12). Se m segue imediatamente h ou hh, o minuto em vez do mês é exibido.
mm Exiba o mês como um número com um zero à frente (01 a 12). Se m segue imediatamente h ou hh, o minuto em vez do mês é exibido.
mmm Exiba o mês como uma abreviação (Jan-Dec). Localizar.
mmmm Exiba o mês como um nome de mês completo (janeiro a dezembro). Localizar.
q Exiba o trimestre do ano como um número (1 a 4).
y Exiba o dia do ano como um número (1 a 366).
yy Exiba o ano como um número de dois dígitos (00 a 99).
aaaa Exiba o ano como um número de 4 dígitos (100 a 9999).
h Exiba a hora como um número sem um zero à frente (0 a 23).
hh Exiba a hora como um número com um zero à frente (00 a 23).
n Exiba o minuto como um número sem um zero à frente (0 a 59).
nn Exiba o minuto como um número com um zero à frente (00 a 59).
s Exiba o segundo como um número sem um zero à frente (0 a 59).
ss Exiba o segundo como um número com um zero à frente (00 a 59).
ttttt Exibe o tempo como tempo completo (incluindo hora, minuto e segundo), formatados com base em um separador de hora definido pelo formato de hora reconhecido pelo seu sistema. Um zero à esquerda é exibido se a opção zero líder for selecionada e a hora for antes das 10h ou da P.M. O formato de tempo padrão é h:mm:ss.
AM/PM Usa o relógio de 12 horas e exibe um AM em maiúsculas em qualquer hora antes do meio-dia; exibe um PM em maiúsculas em qualquer hora entre o meio-dia e 11:59 P.M.
am/pm Usa o relógio de 12 horas e exibe um AM em minúsculas em qualquer hora antes do meio-dia; exibe um PM em minúsculas em qualquer hora entre o meio-dia e 11:59 P.M.
A/P Usa o relógio de 12 horas e exibe um A em maiúsculas em qualquer hora antes do meio-dia; exibe um P em maiúsculas em qualquer hora entre o meio-dia e 11:59 P.M.
a/p Usa o relógio de 12 horas e exibe um A em minúsculas em qualquer hora antes do meio-dia; exibe um P em minúsculas em qualquer hora entre o meio-dia e 11:59 P.M..
AMPM Usa o relógio de 12 horas e exibe o literal de cadeia de caracteres como definido pelo seu sistema em qualquer hora antes do meio-dia; exibe o literal de cadeia de caracteres PM como definido pelo seu sistema em qualquer hora entre o meio-dia e 11:59 P.M. AMPM pode estar em maiúsculas ou minúsculas, mas o caso da cadeia de caracteres exibida corresponde à cadeia de caracteres como definido pelas suas configurações de sistema. O formato padrão é AM/PM. Se o sistema está definido para um relógio de 24 horas, a cadeia de caracteres será configurada como uma cadeia de caracteres de comprimento zero.

Formatos numéricos definidos pelo usuário

A tabela a seguir identifica caracteres que você pode usar para criar formatos de número definidos pelo usuário.

Caractere Descrição
Nenhum Exibe o número sem formatação.
(0) Espaço reservado para dígito. Exibe um dígito ou zero. Se a expressão tem um dígito à posição onde o 0 é exibido na cadeia de caracteres formato exiba-a; caso contrário, exiba um zero nessa posição. Se o número tiver menos dígitos do que zeros (em ambos os lados do decimal) na expressão de formato, exiba zeros à esquerda ou à direita. Se o número tiver mais dígitos à direita do separador decimal do que zeros à direita do separador decimal na expressão de formato, arredonde o número para tantas casas decimais quantas forem zeros. Se o número tiver mais dígitos à esquerda do separador decimal do que os zeros à esquerda do separador decimal na expressão de formato, exiba os dígitos extras sem modificação.
(#) Espaço reservado para dígito. Exibe um dígito ou nada. Se a expressão tiver um dígito na posição onde o # aparece na cadeia de caracteres de formato, exibe-o; caso contrário, não exibe nada nessa posição. Este símbolo funciona como o espaço reservado de dígito 0, com a exceção de que os zeros à esquerda e à direita não são exibidos se o número tiver tantos ou menos dígitos que caracteres # em cada lado do separador decimal na expressão de formato.
(.) Espaço reservado para casas decimais. Em algumas localidades, a vírgula é utilizada como separador decimal. O espaço reservado decimal determina o número de dígitos que é exibido à esquerda e à direita do separador decimal. Se a expressão de formato contiver somente sinais numéricos à esquerda deste símbolo, os números menores que 1 começam com um separador decimal. Para exibir um zero à esquerda exibido com números fracionados, use 0, como o primeiro espaço reservado de dígitos à esquerda do separador decimal. O caractere usado como um espaço reservado decimal na saída formatada depende do formato de número reconhecido pelo sistema.
(%) Espaço reservado para porcentagem. A expressão é multiplicada por 100. O símbolo de porcentagem (%) é inserido na posição onde ele aparece na cadeia de caracteres de formato.
(,) Separador de milhar. Em alguns locais, um ponto é utilizado como separador de milhar. O separador de milhar separa milhares de centenas de um número que tem quatro ou mais locais à esquerda do separador decimal. O uso padrão do separador de milhar é especificado se o formato contiver um separador de milhar delimitado por espaços reservados de dígitos (0 ou # ). Dois milhares de separadores adjacentes ou mil separadores imediatamente à esquerda do separador decimal (se um decimais é ou não especificado) significa "dimensionar o número dividindo-o por 1000, arredondando conforme necessário". Por exemplo, você pode usar a cadeia de caracteres de formato "##0", para representar 100 milhões como 100. Números menores que 1 milhão são exibidos como 0. Dois separadores de milhar adjacentes em qualquer posição que não seja imediatamente à esquerda do separador decimal são tratados simplesmente como especificando o uso de um separador de milhar. O caractere usado como o separador de milhar na saída formatada depende do formato de número reconhecido pelo sistema.
(:) Separador de hora. Em alguns locais, outros caracteres podem ser usados para representar o separador de tempo. O separador de hora separa horas, minutos e segundos quando os valores de tempo são formatados. O caractere usado como separador de hora no formato saída será determinado pelas configurações seu sistema.
(/) Separador de dados. Em alguns locais outros caracteres podem ser usados para representar o separador de data. O separador de data separa o dia, mês e ano quando os valores de data são formatados. O caractere usado como o separador de data no formato de saída será determinado pelas configurações seu sistema.
(E- E+ e- e+) Formato científico. Se a expressão de formato contiver pelo menos um espaço reservado de dígito (0 ou # ) à direita de E-, E +, e ou e +, o número será exibido no formato científico e E ou e será inserido entre o expoente e número. O número de espaços reservados de dígitos à direita determina o número de dígitos no expoente. Use E ou e para colocar um sinal de menos próximo em expoentes negativos. Use + E ou e + para colocar um sinal de menos próximo de expoentes negativos e um sinal de adição ao lado de expoentes positivos.
- + $ ( ) Exibe um caractere literal. Para exibir outro caractere além dos listados, preceda-o de uma barra invertida (\) ou delimite-o entre aspas (" ").
(\) Exibe o próximo caractere na cadeia de caracteres de formato. Para exibir um caractere que tem um significado especial como caractere literal, preceda-o com uma barra invertida (\). Uma barra invertida em si não é exibida. Usar uma barra invertida é o mesmo que colocar o próximo caractere entre aspas duplas. Para exibir uma barra invertida, use duas barras invertidas (\\). Exemplos de caracteres que não podem ser exibidos como caracteres literais são os caracteres de formatação de data e hora (a, c, d, h, m, n, p, q, s, t, w, y, /, e :), os caracteres de formatação numérica (#, 0, %, E, e, vírgula e período) e os caracteres de formatação de cadeia de caracteres (@, &, <, >e !).
("ABC") Exiba a cadeia de caracteres entre aspas duplas (""). Para incluir uma string no formato a partir do código, você deverá usar Chr(34)para delimitar o texto (34 é o código de caractere para uma aspa (")).

Confira também

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.