Strings.Format(Object, String) Método

public static string Format(object Expression, string Style = "");

static member Format : obj * string -> string

Public Function Format (Expression As Object, Optional Style As String = "") As String

Parâmetros

Devoluções

Uma string formatada de acordo com instruções contidas numa expressão de formato String .

Exemplos

Este exemplo mostra várias utilizações da Format função para formatar valores usando tanto String formatos como formatos definidos pelo utilizador. Para o separador de data (/), separador de tempo (:), e os indicadores AM/PM (t e tt), a saída formatada real exibida pelo seu sistema depende das definições de localização que o código está a usar. Quando as horas e datas são apresentadas no ambiente de desenvolvimento, é utilizado o formato de hora e de data abreviado do código da região.

Dim testDateTime As Date = #1/27/2001 5:04:23 PM#
Dim testStr As String
' Returns current system time in the system-defined long time format.
testStr = Format(Now(), "Long Time")
' Returns current system date in the system-defined long date format.
testStr = Format(Now(), "Long Date")
' Also returns current system date in the system-defined long date 
' format, using the single letter code for the format.
testStr = Format(Now(), "D")

' Returns the value of testDateTime in user-defined date/time formats.
' Returns "5:4:23".
testStr = Format(testDateTime, "h:m:s")
' Returns "05:04:23 PM".
testStr = Format(testDateTime, "hh:mm:ss tt")
' Returns "Saturday, Jan 27 2001".
testStr = Format(testDateTime, "dddd, MMM d yyyy")
' Returns "17:04:23".
testStr = Format(testDateTime, "HH:mm:ss")
' Returns "23".
testStr = Format(23)

' User-defined numeric formats.
' Returns "5,459.40".
testStr = Format(5459.4, "##,##0.00")
' Returns "334.90".
testStr = Format(334.9, "###0.00")
' Returns "500.00%".
testStr = Format(5, "0.00%")

Observações

O String.Format método também oferece funcionalidades semelhantes.

Se estiver a formatar uma cadeia numérica não localizada, deve usar um formato numérico definido pelo utilizador para garantir que obtém o aspeto que deseja.

Se tentar formatar um número sem especificar Style, a Format função fornece funcionalidades semelhantes à Str função, embora seja internacionalmente conhecida. No entanto, números positivos formatados como cadeias usando a Format função não incluem um espaço inicial reservado para o sinal do valor; os convertidos usando a Str função mantêm o espaço principal.

Formatos Diferentes para Valores Numéricos Diferentes

Uma expressão de formato definida pelo utilizador para números pode ter de uma a três secções separadas por ponto e vírgula. Se o argumento Style da Format função contiver um dos formatos numéricos predefinidos, apenas uma secção é permitida.

Se utilizar	Este é o resultado
Apenas uma secção	A expressão de formato aplica-se a todos os valores.
Duas secções	A primeira secção aplica-se a valores positivos e zeros; a segunda aplica-se a valores negativos.
Três secções	A primeira secção aplica-se a valores positivos, a segunda aplica-se a valores negativos e a terceira aplica-se a zeros.

O exemplo seguinte tem duas secções: a primeira define o formato para valores positivos e zeros; A segunda secção define o formato para valores negativos. Como o Style argumento da Format função assume uma cadeia, ela está envolvida entre aspas.

Dim style1 As String = "$#,##0;($#,##0)"

Se incluir pontos e vírgulas sem nada entre eles, a secção em falta é impressa usando o formato do valor positivo. Por exemplo, o formato seguinte mostra valores positivos e negativos usando o formato da primeira secção e mostra Zero se o valor for zero.

Dim style2 As String = "$#,##0;;\Z\e\r\o"

Formatos numéricos pré-definidos

A tabela seguinte identifica os nomes de formatos numéricos pré-definidos. Estes podem ser usados pelo nome como argumento Style para a Format função:

Nome do formato	Descrição
General Number, G ou g	Mostra o número sem separador de mil. Por exemplo, Format(&H3FA, "g") retorna 1018.
Currency, C ou c	Exibe o número com separador de mil, se apropriado; mostra dois dígitos à direita do separador decimal. A saída é baseada nas configurações de localidade do sistema. Por exemplo, Format(1234567, "c") retorna $1,234,567.00.
Fixed, F ou f	Exibe pelo menos um dígito à esquerda e dois dígitos à direita do separador decimal. Por exemplo, Format(1234567, "f") retorna 1234567.00.
Standard, N ou n	Mostra o número com o separador mil, pelo menos um dígito à esquerda e dois dígitos à direita do separador decimal. Por exemplo, Format(1234567, "n") retorna 1,234,567.00.
Percent	Exibe o número multiplicado por 100 com um sinal de porcentagem (%) anexado imediatamente à direita; sempre exibe dois dígitos à direita do separador decimal. Por exemplo, Format(0.4744, "Percent") retorna 47.44%.
P, ou p	Mostra o número com o separador de milésimos multiplicado por 100 com um sinal de percentagem (%) acrescentado à direita e separado por um único espaço; Mostra sempre dois dígitos à direita do separador decimal. Por exemplo, Format(0.80345, "p") retorna 80.35 %.
Scientific	Usa notação científica padrão, fornecendo dois dígitos significativos. Por exemplo, Format(1234567, "Scientific") retorna 1.23E+06.
E, ou e	Utiliza notação científica padrão, fornecendo seis dígitos significativos. Por exemplo, Format(1234567, "e") retorna 1.234567e+006.
D, ou d	Mostra o número como uma cadeia que contém o valor do número em formato Decimal (base 10). Esta opção é suportada apenas para tipos integrais (Byte, Short, Integer, Long) Por exemplo, Format(&H7F, "d") retorna 127.
X, ou x	Mostra o número como uma cadeia que contém o valor do número em formato hexadecimal (base 16). Esta opção é suportada apenas para tipos integrais (Byte, Short, Integer, Long) Por exemplo, Format(127, "x") retorna 7f.
Yes/No	Mostra No se o número for 0; caso contrário, mostra Yes. Por exemplo, Format(0, "Yes/No") retorna No.
True/False	Mostra False se o número for 0; caso contrário, mostra True. Por exemplo, Format(1, "True/False") retorna True.
On/Off	Mostra Off se o número for 0; caso contrário, mostra On. Por exemplo, Format(1, "On/Off") retorna On.

Notas do Desenvolvedor de Dispositivos Inteligentes

Os Yes/Noformatos , True/False, e On/Off não são suportados.

User-Defined Formatos Numéricos

A tabela seguinte identifica caracteres que pode usar para criar formatos numéricos definidos pelo utilizador. Estes podem ser usados para construir o Style argumento para a Format função:

Caráter	Descrição
None	Mostra o número sem formatação.
(0)	Marcador de posição digital. Mostra um dígito ou um zero. Se a expressão tiver um dígito na posição onde o zero aparece na cadeia de formato, mostre-o; caso contrário, apresenta um zero nessa posição. Se o número tiver menos dígitos do que houver zeros (de cada lado do decimal) na expressão de formato, mostra os zeros iniciais ou posteriores. Se o número tiver mais dígitos à direita do separador decimal do que zeros à direita do separador decimal na expressão de formato, arredonda o número para tantos números decimais quantos houver zeros. Se o número tiver mais dígitos à esquerda do separador decimal do que houver zeros à esquerda do separador decimal na expressão de formato, mostra os dígitos extra sem modificações.
(#)	Marcador de posição digital. Mostra um dígito ou nada. Se a expressão tiver um dígito na posição onde o # carácter aparece na cadeia de formato, mostra-o; caso contrário, não mostra nada nessa posição. Este símbolo funciona como o 0 marcador de dígitos, exceto que os zeros iniciais e finais não são exibidos se o número tiver menos dígitos do que caracteres # de cada lado do separador decimal na expressão de formato.
(.)	Espaço reservado decimal. O espaço reservado decimal determina quantos dígitos são exibidos à esquerda e à direita do separador decimal. Se a expressão de formato contiver apenas # caracteres à esquerda deste símbolo; números menores que 1 começam com um separador decimal. Para mostrar um zero à esquerda com números fracionários, use o zero como primeiro dígito marcador à esquerda do separador decimal. Em algumas localidades, uma vírgula é usada como separador decimal. O carácter real usado como marcador decimal na saída formatada depende do formato numérico reconhecido pelo seu sistema. Assim, deve usar o ponto como marcador decimal nos seus formatos, mesmo que esteja numa localidade que use uma vírgula como marcador decimal. A cadeia formatada aparecerá no formato correto para a localidade.
(%)	Percentagem de substituição. Multiplica a expressão por 100. O caractere de porcentagem (%) é inserido na posição em que aparece na cadeia de caracteres de formato.
(,)	Separador mil. O separador de milhares separa milhares de centenas dentro de um número que tem quatro ou mais lugares à esquerda do separador decimal. O uso padrão do separador de mil é especificado se o formato contiver um separador de mil cercado por espaços reservados para dígitos (0 ou #). Um separador de mil imediatamente à esquerda do separador decimal (seja ou não especificado um decimal) ou como o carácter mais à direita na cadeia significa "escalar o número dividindo-o por 1.000, arredondando conforme necessário." Números menores que 1.000 mas maiores ou iguais a 500 são apresentados como 1, e números inferiores a 500 são apresentados como 0. Dois mil separadores adjacentes nesta posição aumentam por um fator de 1 milhão, e um fator adicional de 1.000 por cada separador adicional. Separadores múltiplos em qualquer posição que não seja imediatamente à esquerda do separador decimal ou na posição mais à direita na cadeia são tratados simplesmente como especificando o uso de um separador mil. Em algumas localidades, um ponto é usado como separador de mil. O caractere real usado como separador de mil na saída formatada depende do formato de número reconhecido pelo seu sistema. Assim, deve usar a vírgula como separador dos mil nos seus formatos, mesmo que esteja numa localidade que use um ponto como separador dos mil. A cadeia formatada aparecerá no formato correto para a localidade. Por exemplo, considere as seguintes três cadeias de formato: - "#,0.", que usa o separador de milhares para formatar o número 100 milhões como a cadeia "100.000.000". - "#0,.", que utiliza escala por um fator de mil para formatar o número 100 milhões como a cadeia "100000". - "#,0,.", que utiliza o separador de milhares e a escala por mil para formatar o número 100 milhões como a cadeia "100.000".
(:)	Separador de tempo. Em algumas localidades, outros caracteres podem ser usados para representar o separador de tempo. O separador de tempo separa horas, minutos e segundos quando os valores de tempo são formatados. O caractere real usado como separador de tempo na saída formatada é determinado pelas configurações do sistema.
(/)	Separador de data. Em algumas localidades, outros caracteres podem ser usados para representar o separador de data. O separador de data separa o dia, o mês e o ano em que os valores de data são formatados. O caractere real usado como separador de data na saída formatada é determinado pelas configurações do sistema.
(E-``E+``e-``e+)	Formato científico. Se a expressão de formato contiver pelo menos um número reservado (0 ou #) à esquerda de E-, E+, e-, ou e+, o número é apresentado em formato científico e E /ou e é inserido entre o número e o seu expoente. O número de marcadores de dígitos à esquerda determina o número de dígitos no expoente. Use E- ou e- para colocar um sinal menos ao lado de expoentes negativos. Use E+ ou e+ para colocar um sinal menos ao lado dos expoentes negativos e um sinal de mais ao lado dos expoentes positivos. Também deve incluir marcadores de dígitos à direita deste símbolo para obter a formatação correta.
- + $ ( )	Personagens literais. Estes caracteres são exibidos exatamente como digitados na cadeia de formato. Para exibir um caractere diferente de um dos listados, preceda-o com uma barra invertida (\) ou coloque-o entre aspas duplas (" ").
(\)	Mostra o próximo carácter na cadeia de formato. Para exibir um caractere que tenha um significado especial como um caractere literal, preceda-o com uma barra invertida (\). A barra invertida propriamente dita 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 apresentados como caracteres literais são os caracteres de formatação de data e de formato temporal (a, c, d, hm, qpy/swnte :), os caracteres de formatação numérica (#, 0, %, eE, vírgula, e ponto), e os caracteres de formatação de strings (@, &, <, >, e ).!
("``ABC``")	Mostra a cadeia dentro das aspas duplas (" "). Para incluir uma string no argumento de estilo dentro do código, deve usar Chr(34) para incluir o texto (34 é o código de carácter para uma aspas (")).

Exemplo de Código Legado

A tabela seguinte contém algumas expressões de formato de exemplo para números. (Estes exemplos assumem todos que a configuração de localização do seu sistema é Inglês-EUA.) A primeira coluna contém as strings de formato para o Style argumento da Format função; as outras colunas contêm a saída resultante se os dados formatados tiverem o valor indicado nos cabeçalhos das colunas.

Formato (Style)	"5" formatado como	"-5" formatado como	"0.5" formatado como
Zero-length string ("")	5	-5	0.5
0	5	-5	1
0.00	5.00	-5.00	0.50
#,##0	5	-5	1
$#,##0;($#,##0)	$5	($5)	$1
$#,##0.00;($#,##0.00)	$5.00	($5.00)	$0.50
0%	500%	-500%	50%
0.00%	500.00%	-500.00%	50.00%
0.00E+00	5.00E+00	-5.00E+00	5.00E-01
0.00E-00	5.00E00	-5.00E00	5.00E-01

Formatos de Data/Hora Predefinidos

A tabela seguinte identifica os nomes pré-definidos dos formatos de data e hora. Estes podem ser usados pelo nome como argumento de estilo para a Format função:

Nome do formato	Descrição
General Date, ou G	Exibe uma data e/ou hora. Por exemplo, 3/12/2008 11:07:31 AM. A exibição de data é determinada pelo valor de cultura atual do seu aplicativo.
Long Date, Medium Date ou D	Exibe uma data de acordo com o formato de data longa da sua cultura atual. Por exemplo, Wednesday, March 12, 2008.
Short Date, ou d	Exibe uma data usando o formato de data abreviada da cultura atual. Por exemplo, 3/12/2008. O d carácter apresenta o dia num formato de data definido pelo utilizador.
Long Time, Medium Time ou T	Exibe um tempo usando o formato de tempo longo da sua cultura atual; normalmente inclui horas, minutos, segundos. Por exemplo, 11:07:31 AM.
Short Time ou t	Mostra um tempo usando o formato de tempo curto da sua cultura atual. Por exemplo, 11:07 AM. O t carácter é exibido AM ou PM valores para locais que utilizam um relógio de 12 horas num formato de hora definido pelo utilizador.
f	Mostra a data longa e o curto período de acordo com o formato da tua cultura atual. Por exemplo, Wednesday, March 12, 2008 11:07 AM.
F	Mostra a data longa e o longo tempo de acordo com o formato da tua cultura atual. Por exemplo, Wednesday, March 12, 2008 11:07:31 AM.
g	Mostra a data curta e o curto período de acordo com o formato da sua cultura atual. Por exemplo, 3/12/2008 11:07 AM.
M, m	Mostra o mês e o dia de uma data. Por exemplo, March 12. O M carácter apresenta o mês num formato de data definido pelo utilizador. O m carácter apresenta as minutos num formato de tempo definido pelo utilizador.
R, r	Formata a data de acordo com a RFC1123Pattern propriedade. Por exemplo, Wed, 12 Mar 2008 11:07:31 GMT. A data formatada não ajusta o valor da data e hora. Deve ajustar o valor Data/Hora para GMT antes de chamar a Format função.
s	Formata a data e a hora como um índice ordenável. Por exemplo, 2008-03-12T11:07:31. O s carácter mostra os segundos num formato de tempo definido pelo utilizador.
u	Formata a data e hora como um índice ordenável GMT. Por exemplo, 2008-03-12 11:07:31Z.
U	Formata a data e hora com a data longa e o longo prazo como GMT. Por exemplo, Wednesday, March 12, 2008 6:07:31 PM.
Y, y	Formata a data como ano e mês. Por exemplo, March, 2008. Os Y caracteres e y exibem o ano num formato de data definido pelo utilizador.

Para mais informações sobre a cultura atual da aplicação, consulte Como a Cultura Afeta as Strings em Visual Basic.

User-Defined Formatos de Data/Hora

A tabela seguinte mostra caracteres que pode usar para criar formatos de data/hora definidos pelo utilizador. Ao contrário das versões anteriores do Visual Basic, estes caracteres de formato são sensíveis a maiúsculas minúsculas.

Caráter	Descrição
(:)	Separador de tempo. Em algumas localidades, outros caracteres podem ser usados para representar o separador de tempo. O separador de tempo separa horas, minutos e segundos quando os valores de tempo são formatados. O carácter real usado como separador temporal na saída formatada é determinado pelo valor cultural atual da sua aplicação.
(/)	Separador de data. Em algumas localidades, outros caracteres podem ser usados para representar o separador de data. O separador de data separa o dia, o mês e o ano em que os valores de data são formatados. O carácter real usado como separador de data na saída formatada é determinado pela cultura atual da sua aplicação.
(%)	Usado para indicar que o carácter seguinte deve ser lido num formato de letra única, sem consideração por quaisquer letras que terminem. Também é usado para indicar que um formato de uma única letra é lido como um formato definido pelo utilizador. Veja o que se segue para mais detalhes.
d	Mostra o dia como um número sem zero à esquerda (por exemplo, 1). %d Use se este for o único carácter no seu formato numérico definido pelo utilizador.
dd	Apresenta o dia como um número com zero à esquerda (por exemplo, 01).
ddd	Mostra o dia como uma abreviatura (por exemplo, Sun).
dddd	Mostra o dia como nome completo (por exemplo, Sunday).
M	Mostra o mês como um número sem zero à esquerda (por exemplo, janeiro é representado como 1). %M Use se este for o único carácter no seu formato numérico definido pelo utilizador.
MM	Mostra o mês como um número com zero à esquerda (por exemplo, 01/12/01).
MMM	Mostra o mês como uma abreviatura (por exemplo, Jan).
MMMM	Mostra o mês como um nome completo do mês (por exemplo, January).
gg	Mostra a cadeia de período/era (por exemplo, A.D.).
h	Mostra a hora como um número sem zeros à esquerda usando o relógio das 12 horas (por exemplo, 1:15:15 PM). %h Use se este for o único carácter no seu formato numérico definido pelo utilizador.
hh	Apresenta a hora como um número com zeros à esquerda usando o relógio de 12 horas (por exemplo, 01:15:15 PM).
H	Apresenta a hora como um número sem zeros à esquerda usando o relógio de 24 horas (por exemplo, 1:15:15). %H Use se este for o único carácter no seu formato numérico definido pelo utilizador.
HH	Mostra a hora como um número com zeros à esquerda usando o relógio de 24 horas (por exemplo, 01:15:15).
m	Mostra o minuto como um número sem zeros iniciais (por exemplo, 12:1:15). %m Use se este for o único carácter no seu formato numérico definido pelo utilizador.
mm	Apresenta o minuto como um número com zeros à esquerda (por exemplo, 12:01:15).
s	Mostra a segunda como um número sem zeros à esquerda (por exemplo, 12:15:5). %s Use se este for o único carácter no seu formato numérico definido pelo utilizador.
ss	Mostra a segunda como um número com zeros à esquerda (por exemplo, 12:15:05).
f	Mostra frações de segundos. Por exemplo ff , mostra centésimos de segundos, enquanto ffff mostra dez milésimos de segundo. Pode usar até sete f símbolos no seu formato definido pelo utilizador. %f Use se este for o único carácter no seu formato numérico definido pelo utilizador.
t	Utiliza o relógio de 12 horas e mostra uma letra maiúscula A para qualquer hora antes do meio-dia; mostra uma maiúscula P para qualquer hora entre o meio-dia e as 23:59. Use %t se este for o único carácter no seu formato numérico definido pelo utilizador.
tt	Para locais que utilizam um relógio de 12 horas, mostra uma maiúscula AM com qualquer hora antes do meio-dia; mostra uma maiúscula PM com qualquer hora entre o meio-dia e as 23h59. Para locais que usam um relógio de 24 horas, não mostra nada.
y	Mostra o número do ano (0-9) sem zeros à frente. %y Use se este for o único carácter no seu formato numérico definido pelo utilizador.
yy	Apresenta o ano em formato numérico de dois dígitos com um zero inicial, se aplicável.
yyy	Mostra o ano em formato numérico de quatro dígitos.
yyyy	Mostra o ano em formato numérico de quatro dígitos.
z	Mostra o deslocamento do fuso horário sem um zero à esquerda (por exemplo, -8). %z Use se este for o único carácter no seu formato numérico definido pelo utilizador.
zz	Mostra o deslocamento do fuso horário com um zero à esquerda (por exemplo, -08)
zzz	Mostra o deslocamento total do fuso horário (por exemplo, -08:00)

Exemplo de Código Legado

Seguem-se exemplos de formatos de data e hora definidos pelo utilizador para December 7, 1958, 8:50 PM, 35 seconds:

Formato	Ecrãs
M/d/yy	12/7/58
d-MMM	7-Dec
d-MMMM-yy	7-December-58
d MMMM	7 December
MMMM yy	December 58
hh:mm tt	08:50 PM
h:mm:ss t	8:50:35 P
H:mm	20:50
H:mm:ss	20:50:35
M/d/yyyy H:mm	12/7/1958 20:50

Notas do Desenvolvedor de Dispositivos Inteligentes

A resolução temporal mínima de um dispositivo é determinada pelo fabricante. Se a resolução temporal do dispositivo for suficientemente grosseira, o f carácter de formato devolve 0 quando executado nesse dispositivo.

Ver também

• Format(String, Object)
• Str(Object)
• Resumo da Manipulação de Cadeias