Função Text

Aplica-se a: Aplicações de tela Aplicações de tela Colunas de fórmula do Dataverse Aplicações condicionadas por modelo Power Platform CLI

Converte qualquer valor e formata um valor de número ou data/hora numa cadeia de texto.

Descrição

A função Text formata um número ou um valor de data/hora com base num dos seguintes tipos de argumentos:

  • Um formato de data/hora predefinido que especifica com a enumeração DateTimeFormat. Para datas e horas, esta abordagem é preferencial, uma vez que se ajusta automaticamente ao idioma e à região de cada utilizador.
  • Um formato personalizado, que é composto por uma cadeia de marcadores de posição que definem, por exemplo, se os números mostram um separador decimal e as datas mostram o nome completo do mês, o mês como abreviatura ou o mês como um número. O Power Apps suporta um subconjunto dos marcadores de posição que o Microsoft Excel faz. Nesta cadeia de caracteres, o marcador de posição do idioma especifica o idioma no qual devem ser interpretados os outros marcadores de posição. Se o formato personalizado incluir um ponto, por exemplo, o marcador de posição de formato de idioma especifica se o ponto é um separador decimal (ja-JP) ou um separador de milhar (es-ES).

Consulte Trabalhar com datas e horas, para obter mais informações.

A função Text também pode converter qualquer tipo de dados numa representação de texto utilizando um formato predefinido. Utilize-a para passar valores sem texto para funções baseadas em texto, tais como Len, Right e IsMatch.

Formatos de data/hora predefinidos

Para estes exemplos, a data e a hora utilizadas são terça-feira, 7 de abril de 2020, 8:26:59.180 PM, no fuso horário UTC-7 horas.

Enumeração DateTimeFormat Descrição Exemplos (utilizando en-US)
LongDate Ano com quatro dígitos, nome do mês, dia do mês e dia da semana. Os nomes do mês e o dia da semana não são abreviados. "Terça-feira, 7 de abril de 2020"
LongDateTime Ano com quatro dígitos, nome do mês, dia do mês e dia da semana, mais hora (relógio de 12 horas), minutos, segundos e designação AM/PM. Os nomes do mês e o dia da semana não são abreviados. "Terça-feira, 7 de abril de 2020, 8:26:59 PM"
LongDateTime24 Ano com quatro dígitos, nome do mês, dia do mês e dia da semana, mais hora (relógio de 24 horas), minutos e segundos. Os nomes do mês e o dia da semana não são abreviados. "Terça-feira, 7 de abril de 2020, 20:26:59"
LongTime Hora (relógio de 12 horas), minutos, segundos e designação AM/PM. "8:26:59 PM"
LongTime24 Hora (relógio de 24 horas), minutos, segundos. "20:26:59"
ShortDate Ano de quatro dígitos com mês numérico e dia do mês. "4/7/2020"
ShortDateTime Ano de quatro dígitos com mês numérico e dia do mês, mais hora (relógio de 12 horas), minutos e designação AM/PM. "4/7/2020 8:26 PM"
ShortDateTime24 Ano de quatro dígitos com mês numérico e dia do mês, mais hora (relógio de 24 horas) e minutos. "4/7/2020 20:26"
ShortTime Hora (relógio de 12 horas), minutos e designação AM/PM. "8:26 PM"
ShortTime24 Hora (relógio de 24 horas) e minutos. "20:26"
UTC O valor de data/hora é convertido para UTC, com base no fuso horário do utilizador atual e formatado de acordo com a norma ISO 8601. "2020-04-08T03:26:59.180Z"

Marcadores de posição de números

Marcador de posição Descrição
0 (zero) Mostra zeros insignificantes se existirem menos dígitos num número do que zeros existentes no formato. Por exemplo, utilize o formato #,00 se pretender apresentar 8,9 como 8,90.
# Segue as mesmas regras que 0 (zero). No entanto, a função Text não devolve zeros adicionais se o número tiver menos dígitos em ambos os lados do decimal do que símbolos # no formato. Por exemplo, é apresentado 8,9 se o formato personalizado for #,## e o número a formatar for 8,9.
. (ponto) Apresenta o ponto decimal num número. Depende do idioma do formato personalizado, consulte aplicações globais para obter mais detalhes.
, (vírgula) Apresenta o separador de agrupamento num número, frequentemente utilizado para milhares. A função Text separa os grupos por vírgulas se o formato tiver uma vírgula entre sinais de cardinal (#) ou zeros. Depende do idioma do formato personalizado, consulte aplicações globais para obter mais detalhes.

Se um número tiver mais dígitos à direita da vírgula decimal do que marcadores de posição no formato, o número é arredondado para tantas casas decimais quantos marcadores de posição. Se existirem mais dígitos à esquerda da vírgula decimal do que marcadores de posição, os dígitos adicionais são apresentados. Se o formato tiver apenas sinais de cardinal (#) à esquerda da vírgula decimal, os números inferiores a 1 começam com uma vírgula decimal (por exemplo, ,47).

Marcadores de posição de data e hora

Marcador de posição Descrição
m Apresenta o mês como um número sem um zero à esquerda.
mm Apresenta o mês como um número com um zero à esquerda, quando necessário.
mmm Apresenta o mês como uma abreviatura (jan a dez).
mmmm Apresenta o mês como um nome completo (janeiro a dezembro).
d Apresenta o dia como um número sem um zero à esquerda.
dd Apresenta o dia como um número com um zero à esquerda, quando necessário.
ddd Apresenta o dia como uma abreviatura (dom a sáb).
dddd Apresenta o dia como um nome completo (domingo a sábado).
yy Apresenta o ano como um número de dois dígitos.
yyyy Apresenta o ano como um número de quatro dígitos.
h Apresenta a hora como um número sem um zero à esquerda.
hh Apresenta a hora como um número com um zero à esquerda, quando necessário. Se o formato tiver AM ou PM, a hora é apresentada com base no relógio de 12 horas. Caso contrário, a hora é apresentada com base no relógio de 24 horas.
m Apresenta o minuto como um número sem um zero à esquerda.

Este marcador de posição tem de aparecer imediatamente a seguir ao código h ou hh, ou imediatamente antes do código ss; caso contrário, a função Text devolve o mês, em vez dos minutos.
mm Apresenta o minuto como um número com um zero à esquerda, quando necessário.

Este marcador de posição m ou o mm tem de aparecer imediatamente após o marcador de posição h ou hh, ou imediatamente antes do marcador de posição ss. Caso contrário, Text devolve o mês em vez dos minutos.
s Apresenta o segundo como um número sem um zero à esquerda.
ss Apresenta o segundo como um número com um zero à esquerda, quando necessário.
f Apresenta as frações de segundos.
AM/PM, a/p Apresenta a hora com base no relógio de 12 horas. Text devolve "AM" ou "a" ou "a" para horas da meia-noite ao meio-dia e "PM" ou "p" para horas do meio-dia à meia-noite

Marcadores de posição literais

Pode incluir qualquer um dos carateres seguintes na sua cadeia de formato. Serão apresentados no resultado de Text inalterados. Os carateres adicionais estão reservados para futuros marcadores de posição, pelo que não os deve utilizar.

Caráter Descrição
Qualquer símbolo de moeda Cifrão, símbolo de cêntimos, símbolo de euro, etc.
+ Sinal de adição
( Parêntese esquerdo
: Dois pontos
^ Acento circunflexo
' Apóstrofo
{ Chaveta esquerda
< Sinal menor que
= Sinal de igual
- Sinal de subtração
/ Barra
) Parêntese direito
& "E" comercial
~ Til
} Chaveta direita
> Sinal de maior que
  Caráter de espaço

Aplicações globais

A função Text tem conhecimento global. Para uma grande variedade de idiomas, esta sabe como escrever corretamente datas, horas, moedas e números. Para realizar a sua tarefa, necessita de duas informações:

  • O idioma do formato personalizado: para criadores, como deve ser interpretado um formato personalizado? Os carateres de separador (. e ,) têm significados diferentes em diferentes idiomas. Se especificar um formato personalizado, pode incluir um marcador de posição de idioma ou assumir o valor predefinido, o qual reflete o idioma para o qual o dispositivo está definido. Ainda mais fácil, pode utilizar um dos formatos de data/hora predefinidos, que são independentes de idioma.
  • O idioma do resultado: para os utilizadores, em que idioma deverá aparecer o resultado da função? Os nomes de meses e dias da semana têm de estar no idioma apropriado para o utilizador da aplicação, e pode especificá-los adicionando um terceiro argumento opcional para a função Text.

Para ambos, especifique o idioma utilizando uma etiqueta de idioma. Para ver a lista de tipos de idiomas suportados escreva Text( 1234, "", ) na barra de fórmula ou no separador Avançada do painel do lado direito e, em seguida, percorra a lista das regiões sugeridas para o terceiro argumento.

Marcador de posição de idioma

Para especificar o idioma de formato personalizado, utilize:

Marcador de posição Descrição
[$-LanguageTag] A LanguageTag é uma etiqueta de idioma devolvida da função Language. Pode especificar somente o idioma (como [$-en] para inglês), ou também pode especificar a região (como [$-en-GB] para especificar a Grã-Bretanha).

O marcador de posição de idioma pode aparecer em qualquer lugar no formato personalizado, mas apenas uma vez.

Se especificar um formato personalizado sem um marcador de posição de idioma e o formato for ambíguo de um ponto de vista global, a etiqueta de idioma do idioma atual será inserida automaticamente.

[$-en-US] é assumido se este marcador de posição não estiver presente quando a aplicação é executada.

Nota

Numa versão futura, poderá alterar a sintaxe deste marcador de posição para evitar confusões com um marcador de posição semelhante, mas diferente, que o Excel suporta.

Etiqueta de idioma do resultado

O resultado de Text incluí as cadeias traduzidas para as designações AM/PM, meses e dias da semana, bem como os separadores decimais e de grupo adequados.

Por predefinição, a função Text utiliza o idioma do utilizador que executa a aplicação. A função Language devolve a etiqueta de idioma para o utilizador atual. Pode substituir este valor predefinido ao fornecer uma etiqueta de idioma para o terceiro argumento para Text.

Sintaxe

Text( NumberOrDateTime, DateTimeFormatEnum [, ResultLanguageTag ] )

  • NumberOrDateTime – Obrigatório. O número ou o valor de data/hora a formatar.
  • DateTimeFormat – Obrigatório. Um membro da enumeração DateTimeFormat.
  • ResultLanguageTag – Opcional. A etiqueta de idioma a utilizar para o texto de resultado. Por predefinição, é utilizado o idioma do utilizador atual.

Text( NumberOrDateTime, CustomFormat [, ResultLanguageTag ] )

  • Número – Obrigatório. O número ou o valor de data/hora a formatar.
  • CustomFormat – Obrigatório. Um ou mais marcadores de posição entre aspas duplas.
  • ResultLanguageTag – Opcional. A etiqueta de idioma a utilizar para o texto de resultado. Por predefinição, é utilizado o idioma do utilizador atual.

Text( AnyValue )

  • AnyValue – Obrigatório. Valor a converter para uma representação de texto. É utilizado um formato predefinido.

Text ( Untyped )

  • Sem tipo – Obrigatório. Objeto sem tipo que representa uma cadeia. Os valores aceitáveis dependem do fornecedor sem tipo. Para JSON, se o objeto sem tipo for um número ou booleano, este será convertido em texto.

Exemplos

A menos que especificado em contrário, o utilizador que executa estas fórmulas encontra-se nos Estados Unidos e selecionou inglês como idioma. A função Language está a devolver "en-US".

Número

Fórmula Descrição Resultado
Text( 1234.59, "####.#" ) Formata o número com uma casa decimal. "1234,6"
Text( 8.9, "#.000" ) Preenche a parte decimal do número com zeros à direita, se necessário. "8,900"
Text( 0.631, "0.#" ) Aponta o número inteiro com zeros à esquerda, se necessário. "0,6"
Text( 12, "#.0#" )
Text( 1234.568, "#.0#" )
Preenche a parte decimal do número com zeros para uma casa decimal e inclui uma segunda casa decimal, se fornecida. "12,0"
"1234,57"
Text( 12000, "$ #,###" )
Text( 1200000, "$ #,###" )
Coloca um separador de milhares a cada três dígitos e inclui um símbolo de moeda. "12.000 $"
"1.200.000 $"

Data/Hora

  • Às 2:37:47 PM na segunda-feira, 23 de novembro de 2015
  • Fuso Horário do Pacífico dos Estados Unidos (UTC-8)
Fórmula Descrição Resultado
Text( Now(), DateTimeFormat.LongDate ) Formata como uma cadeia de data longa, no idioma e região do utilizador atual. "Segunda-feira, 23 de novembro de 2015"
Text( Now(), DateTimeFormat.LongDateTime ) Formata como uma cadeia de data e hora longa, no idioma e região do utilizador atual, com um relógio de 12 horas. "Segunda-feira, 23 de novembro de 2015 2:37:47 PM"
Text( Now(), DateTimeFormat.LongTime24 ) Formata como uma cadeia de hora longa, com um relógio de 24 horas. "14:37:47"
Text( Now(), DateTimeFormat.ShortDate ) Formata como uma cadeia de data curta, no idioma e região do utilizador atual. "11/23/2015"
Text( Now(), "d-mmm-yy" ) Formata com carateres de marcador de posição:
  • d para um dia do mês com um ou dois dígitos
  • - como um caráter literal copiado para o resultado
  • mmm para uma abreviatura de três letras do mês
  • - como outro caráter literal copiado para o resultado
  • yy para uma abreviatura de dois dígitos do ano
"23-nov-15"
Text(1448318857*1000, "mmm. dd, aaaa (hh:mm:ss AM/PM") Mostra um valor de data/hora Unix em formato legível por humanos se multiplicar o valor de origem por 1000. "Nov. 23, 2015 (02:47:37 PM)"

Aplicações globais

Fórmula Descrição Resultado
Text(1234567.89, "[$-fr-FR]# ###,## €", "fr-FR") Mostra um espaço como separador de agrupamento, a vírgula como separador decimal e como o símbolo de moeda. "1 234 567,89 €"
Text(1234567,89; "[$-fr-FR]# ###,## €") Se os dados de origem seguirem a personalização francesa de utilizar uma vírgula como separador decimal, tem de alterar a sua localidade para francês e separar os argumentos com um ponto e vírgula em vez de uma vírgula para obter o mesmo resultado que acima. "1 234 567,89 €"
Text( Date(2016,1,31), "dddd mmmm d" ) Devolve o dia da semana, mês e dia do mês no idioma do utilizador atual. Uma vez que nenhum dos marcadores de posição depende do idioma, não é necessária uma etiqueta de idioma do texto de formato. "domingo, 31 de janeiro"
Text( Date(2016,1,31), "dddd mmmm d", "es-ES" ) Devolve o dia da semana, o mês e o dia do mês no idioma "es-ES". "domingo enero 31"

Converter valores em texto

Fórmula Descrição Resultado
Text( 1234567.89 ) Converte um número numa cadeia. Não existem separadores de milhar ou controlo sobre o número de dígitos antes ou depois do separador decimal; para obter mais controlo, forneça marcadores de posição de número como o segundo argumento. "1234567.89"
Text( DateTimeValue( "04/01/2003" ) ) Converte um valor de data/hora numa cadeia de texto. Para controlar a conversão, forneça um membro da enumeração DateTimeFormat ou uma cadeia de formato personalizado. "1/4/2003 12:00 AM"
Text( true ) Converte um valor Booleano numa cadeia. "true"
Text( GUID() ) Converte um valor GUID gerado numa cadeia. "f8b10550-0f12-4f08-9aa3-bb10958bc3ff"
Left( Text( GUID() ), 4 ) Devolve os primeiros quatro caracteres de um GUID gerado. "2d9c"