Função Text
Aplica-se a:
Aplicativos de tela Aplicativos de tela Colunas de fórmula do Dataverse Aplicativos baseados em modelo Power Platform CLI
Converte qualquer valor e formata um número ou valor de data/hora em uma cadeia de caracteres de texto.
Descrição
A função Text formata um número ou um valor de data/hora com base em um dos tipos de argumentos a seguir:
- Um formato de data/hora predefinido, especificado usando a enumeração DateTimeFormat. Essa é a abordagem preferencial para datas e horas, pois se ajusta automaticamente ao idioma e região de cada usuário.
- Um formato personalizado, que consiste em uma cadeia de espaços reservados 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 uma abreviação ou o mês como um número. O Power Apps oferece suporte a um subconjunto dos espaços reservados que o Microsoft Excel faz. Nessa cadeia de caracteres, o espaço reservado de idioma especifica o idioma no qual os outros espaços reservados são interpretados. Se o formato personalizado incluir um ponto, por exemplo, o espaço reservado de formato de idioma especifica se o período é 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 em uma representação de texto usando um formato padrão. Use isso para passar valores não texto para funções baseadas em texto, como Len, Right e IsMatch.
Formatos de data/hora predefinidos
Para esses exemplos, a data e a hora usadas são terça-feira, 7 de abril de 2020 8:26:59.180 PM, no fuso horário UTC-7 horas.
| DateTimeFormat enum | Descrição | Exemplos (usando en-US) |
|---|---|---|
| LongDate | Ano de quatro dígitos, nome do mês, dia do mês e dia da semana. Os nomes do mês e do dia da semana não são abreviados. | "Terça-feira, 7 de abril de 2020" |
| LongDateTime | Ano de quatro dígitos, nome do mês, dia do mês e dia da semana, mais de hora (relógio de 12 horas), minutos, segundos e designação AM/PM. Os nomes do mês e do dia da semana não são abreviados. | "Terça-feira, 7 de abril de 2020 8:26:59 PM" |
| LongDateTime24 | Ano de quatro dígitos, mês, dia do mês e dia da semana, mais de hora (relógio de 24 horas), minutos e segundos. Os nomes do mês e do 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 | Horas (relógio de 24 horas), minutos e 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, além de 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, além de 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 usuário atual e formatado de acordo com o padrão ISO 8601. | "2020-04-08T03:26:59.180Z" |
Espaços reservados em formato de número
| Espaço reservado | Descrição |
|---|---|
| 0 (zero) | Exibe zeros não significativos se um número tiver menos dígitos do que zeros no formato. Por exemplo, use o formato #.00 para exibir 8.9 como 8.90. |
| # | Siga as mesmas regras do 0 (zero). No entanto, a função Text não retorna zeros adicionais quando o número tem menos dígitos em ambos os lados da casa decimal do que símbolos # no formato. Por exemplo, 8.9 será exibido se o formato personalizado for #.## e o número para formatar for 8.9. |
| . (ponto) | Exibe o ponto decimal em um número. Depende do idioma do formato personalizado; consulte aplicativos globais para obter mais detalhes. |
| , (vírgula) | Exibe o separador de agrupamento em um número, geralmente usado para milhares. A função Text separa grupos por vírgulas se o formato contiver uma vírgula entre sinais numéricos (#) ou zeros. Depende do idioma do formato personalizado; consulte aplicativos globais para obter mais detalhes. |
Se um número tiver mais dígitos à direita da vírgula decimal do que espaços reservados no formato, ele será arredondado para a quantidade de casas decimais definida pelos espaços reservados. Se houver mais dígitos à esquerda da vírgula decimal do que espaços reservados, os dígitos adicionais serão exibidos. Se o formato contiver apenas sinais numéricos (#) à esquerda da vírgula decimal, números inferiores a 1 começarão com uma vírgula decimal (por exemplo, .47).
Espaços reservados de data e hora
| Espaço reservado | Descrição |
|---|---|
| m | Exibe o mês como um número sem um zero à esquerda. |
| mm | Exibe o mês como um número com um zero à esquerda. |
| mmm | Exibe o mês como uma abreviação (jan a dez). |
| mmmm | Exibe o mês como um nome completo (janeiro a dezembro). |
| d | Exibe o dia como um número sem um zero à esquerda. |
| dd | Exibe o dia como um número com um zero à esquerda. |
| ddd | Exibe o dia como uma abreviatura (Sun a Sat). |
| dddd | Exibe o dia como um nome completo (domingo a sábado). |
| yy | Exibe o ano como um número de dois dígitos. |
| yyyy | Exibe o ano como um número de quatro dígitos. |
| h | Exibe a hora como um número sem um zero à esquerda. |
| hh | Exibe a hora como um número com um zero à esquerda. Se o formato contiver AM ou PM, a hora será mostrada com base no relógio de 12 horas. Caso contrário, a hora será mostrada com base no relógio de 24 horas. |
| m | Exibe o minuto como um número sem um zero à esquerda. Esse espaço reservado deve aparecer imediatamente após o código h ou hh ou imediatamente antes do código ss; caso contrário, o Text retornará o mês em vez de minutos. |
| mm | Exibe o minuto como um número com um zero à esquerda quando apropriado. Esse espaço reservado deve aparecer imediatamente após o espaço reservado h ou hh ou imediatamente antes do espaço reservado ss. Caso contrário, a função Text retornará o mês em vez dos minutos. |
| s | Exibe o segundo como um número sem um zero à esquerda. |
| ss | Exibe o segundo como um número com um zero à esquerda quando apropriado. |
| f | Exibe as frações de segundos. |
| AM/PM, a/p | Exibe a hora com base em um relógio de 12 horas. O Text retorna "AM" ou "a" para os horários da meia-noite até o meio-dia e "PM" ou "p" para os horários do meio-dia até a meia-noite |
Espaços reservados literais
É possível incluir esses caracteres na cadeia de formato. Eles aparecerão nos resultados da função Text como são. Caracteres adicionais estão reservados para futuros espaços reservados, portanto, você não deve usá-los.
| Caractere | Descrição |
|---|---|
| Qualquer símbolo de moeda | Símbolos do dólar, euro, de centavos etc. |
| + | Sinal de adição |
| ( | Parêntese esquerdo |
| : | Dois-pontos |
| ^ | Acento circunflexo |
| ' | Apóstrofo |
| { | Chave à esquerda |
| < | Sinal de menor que |
| = | Sinal de igual |
| - | Sinal de subtração |
| / | Barra |
| ) | Parêntese direito |
| & | E comercial |
| ~ | Til |
| } | Chave à direita |
| > | Sinal de maior que |
| Caractere de espaço |
Aplicativos globais
A função Text tem sensibilidade global. Ela escreve corretamente datas, horas, moedas e números em uma ampla variedade de idiomas. Para que ela funcione, são necessárias duas informações:
- O idioma do formato personalizado: para criadores, como um formato personalizado deve ser interpretado? Os caracteres separadores (. e ,) têm significados diferentes entre os idiomas. Se você especificar um formato personalizado, poderá incluir um espaço reservado de idioma ou obter o valor padrão, que reflete o idioma no qual o dispositivo está definido. Ainda mais fácil, você pode usar um dos formatos de data/hora predefinidos, que são independentes de idioma.
- O idioma do resultado: para os usuários, em qual idioma o resultado da função deve aparecer? Os nomes de meses e dias da semana devem estar no idioma apropriado para o usuário do aplicativo, que você pode especificar adicionando um terceiro argumento opcional à função Text.
Para ambos, você especifica o idioma usando uma marca de idioma. Para ver a lista de idiomas com suporte, digite Text( 1234, "", ) na barra de fórmulas ou na guia Avançado do painel à direita e, em seguida, percorra a lista de localidades sugeridas para o terceiro argumento.
Espaço reservado de idioma
Para especificar o idioma do formato personalizado, use:
| Espaço reservado | Descrição |
|---|---|
| [$-LanguageTag] | LanguageTag é uma marca de idioma, conforme retornado pela função Language. Ele pode especificar apenas o idioma (como [$-en] para inglês) ou também pode especificar a região (como [$-en-GB] para especificar ainda mais a Grã-Bretanha). |
O espaço reservado de idioma pode aparecer em qualquer lugar no formato personalizado, mas apenas uma vez.
Se você especificar um formato personalizado sem um espaço reservado de idioma e o formato for ambíguo de um ponto de vista global, a marca de idioma para seu idioma atual será inserida automaticamente.
Adota-se o [$-en-US] se o espaço reservado não estiver presente ao executar o aplicativo.
Nota
Em uma versão futura, a sintaxe desse espaço reservado pode ser alterada para evitar confusão com um espaço reservado semelhante, mas diferente, compatível com o Excel.
Marca de idioma de resultado
O resultado do Text inclui cadeias de caracteres traduzidas para meses, dias da semana e designações AM/PM, bem como o grupo e os separadores decimais apropriados.
Por padrão, a função Text usa o idioma do usuário que executa o aplicativo. A função Language retorna a marca de idioma para o usuário atual. Você pode substituir esse valor padrão fornecendo uma marca 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 para o formato.
- DateTimeFormat - obrigatório. Membro da enumeração DateTimeFormat.
- ResultLanguageTag - opcional. A marca de idioma a ser usada para o texto do resultado. Por padrão, o idioma do usuário atual é utilizado.
Text( NumberOrDateTime, CustomFormat [, ResultLanguageTag ] )
- Number - obrigatório. O número ou o valor de data/hora para o formato.
- CustomFormat - obrigatório. Um ou mais espaços reservados entre aspas duplas.
- ResultLanguageTag - opcional. A marca de idioma a ser usada para o texto do resultado. Por padrão, o idioma do usuário atual é utilizado.
Text( AnyValue )
- AnyValue - obrigatório. Valor a ser convertido em uma representação de texto. Um formato padrão é usado.
Text ( Untyped )
- Untyped - obrigatório. Objeto sem tipo que representa uma cadeia de caracteres. Os valores aceitáveis dependem do provedor sem tipo. Em JSON, se o objeto sem tipo for um número ou booliano, ele será convertido em texto.
Exemplos
A menos que especificado de outra forma, o usuário que executa essas fórmulas está localizado na Estados Unidos e selecionou inglês como seu idioma. A função Language está retornando "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.#" ) | Preenche a parte inteira do número 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 ) | Formatos como uma cadeia de data por extenso, no idioma e a localidade do usuário atual. | "Segunda-feira, 23 de novembro de 2015" |
| Text( Now(), DateTimeFormat.LongDateTime ) | Formatos como uma cadeia de data e hora por extenso, no idioma e a localidade do usuário atual, com um relógio de 12 horas. | "Segunda-feira, 23 de novembro de 2015 2:37:47 PM" |
| Text( Now(), DateTimeFormat.LongTime24 ) | Formatos como uma cadeia de hora completa, com um relógio de 24 horas. | "14:37:47" |
| Text( Now(), DateTimeFormat.ShortDate ) | Formatos como uma cadeia de data abreviada, no idioma e localidade do usuário atual. | "11/23/2015" |
| Text( Now(), "d-mmm-yy" ) | Formatos usando caracteres de espaço reservado:
|
"23-Nov-15" |
| Text(1448318857*1000, "mmm. dd, yyyy (hh:mm:ss AM/PM)") | Mostra um valor de data/hora do UNIX no formato legível por humanos se você multiplicar o valor de origem por 1.000. | "23 de novembro, 2015 (02:47:37 PM)" |
Aplicativos globais
| Fórmula | Description | Result |
|---|---|---|
| Text(1234567.89, "[$-fr-FR]# ###,## €", "fr-FR") | Mostra um espaço como um separador de agrupamento, a vírgula como um separador decimal e € como o símbolo de moeda. | "1 234 567,89 €" |
| Text(1234567,89; "[$-fr-FR]# ###,## €") | Se os dados de origem seguirem o personalizado francês do uso de uma vírgula como separador decimal, você deverá alterar 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 mostrado acima. | "1 234 567,89 €" |
| Text( Date(2016,1,31), "dddd mmmm d" ) | Retorna o dia da semana, mês e dia do mês no idioma do usuário atual. Como nenhum dos espaços reservados são dependentes do idioma, não há necessidade de uma marca de idioma de texto de formato de idioma. | "Domingo,31de janeiro" |
| Text( Date(2016,1,31), "dddd mmmm d", "es-ES" ) | Retorna o dia da semana, mês e dia do mês no idioma "es-ES". | "domingo enero 31" |
Conversão de valores em texto
| Fórmula | Descrição | Resultado |
|---|---|---|
| Text( 1234567.89 ) | Converte um número em uma cadeia de caracteres. Não há nenhum separador de milhares ou controle sobre o número de dígitos antes ou depois do separador decimal; para obter mais controle, forneça espaços reservados de número como o segundo argumento. | "1234567.89" |
| Text( DateTimeValue( "01/04/2003" ) ) | Converte um valor de data/hora em uma cadeia de texto. Para controlar a conversão, forneça um membro da enumeração DateTimeFormat ou uma cadeia de caracteres de formato personalizado. | "1/4/2003 12:00 AM" |
| Text( true ) | Converte um valor booliano em uma cadeia de caracteres. | "true" |
| Text( GUID() ) | Converte um valor GUID gerado em uma cadeia de caracteres. | "f8b10550-0f12-4f08-9aa3-bb10958bc3ff" |
| Left( Text( GUID() ), 4 ) | Retorna os quatro primeiros caracteres de um GUID gerado. | "2d9c" |