Tipos de dados

As informações fluem através do Power Fx em valores pequenos e discretos, como as células de uma planilha. Por exemplo, os dados em um campo Aniversário e um campo Aniversário fluem como um valor de Data que inclui o ano, o mês e o dia. O Power Fx formata esses valores, restringe a entrada ao que é apropriado para cada um e compartilha os valores com um banco de dados. Aniversários e aniversários podem ser diferentes para as pessoas, mas o sistema lida com eles da mesma maneira. Neste caso, Data é um exemplo de um tipo de dados.

Este artigo explica cada tipo de dados no Power Fx, como funcionam e como são mapeados para fontes de dados externas.

Muitos desses tipos de dados são semelhantes e têm a mesma representação subjacente, como um campo Hyperlink sendo tratado como Texto. Os tipos de dados extras oferecem melhores experiências padrão em formulários e outros controles.

Blank

Todos os tipos de dados podem ter um valor em branco (sem valor). O termo "nulo" é frequentemente utilizado em bases de dados para este conceito.

Utilize a função Blank com a função Set ou Patch para definir uma variável ou um campo como em branco. Por exemplo, set( x, Blank() ) remove o valor na variável global x.

Teste um valor em branco com a função IsBlank . Substituir possíveis valores em branco por valores não em branco utilizando a função Coalesce.

Como todos os tipos de dados oferecem suporte em branco, os tipos de dados Boolean e Two option têm três valores possíveis.

Texto, Hiperligação, Imagem e Multimédia

Todos os quatro tipos de dados são baseados numa cadeia de texto Unicode.

Texto incorporado

As cadeias de texto incorporadas numa fórmula são colocadas entre aspas. Utilize duas aspas duplas em conjunto para representar uma única aspa dupla na cadeia de texto. Por exemplo, utilizar a seguinte fórmula na popriedade OnSelect de um controlo de Button:

Notify( "Jane said ""Hello, World!""" )

Resulta em um banner quando o botão é pressionado, onde a primeira e a última aspas duplas são omitidas (pois delimitam a cadeia de texto) e as aspas duplas repetidas em torno de Olá, Mundo! são substituídas por uma única aspa dupla:

As aspas são utilizadas em nomes de identificador que contêm caracteres especiais e que não têm nenhum significado especial dentro de uma cadeia de texto.

Interpolação de cadeias

Utilize a interpolação de cadeias para incorporar fórmulas numa cadeia de texto. Esta abordagem é, muitas vezes, mais fácil trabalhar com e de visualizar os resultados do que utilizar a função Concatenate ou o operador &.

Atribua um prefixo à cadeia de texto com um sinal de dólar $ e coloque a fórmula a ser incorporada entre chavetas {}. Para incluir uma chaveta na cadeia de texto, utilize chavetas repetidas: {{ ou }}. A interpolação de cadeias pode ser utilizada em qualquer ponto onde possa ser utilizada uma cadeia de texto padrão.

Por exemplo, considere esta fórmula com as variáveis globais Maçãs definida como 3 e Bananas definida como 4:

$"We have {Apples} apples, {Bananas} bananas, yielding {Apples+Bananas} fruit total."

Esta fórmula obtém a cadeia de texto Temos 3 maçãs, 4 bananas, resultando num total de 7 peças de fruta. As variáveis Maçãs e Bananas são inseridas no texto que substitui as chavetas, juntamente com o resultado da fórmula matemática Maçãs+Bananas. Os espaços e outros carateres à volta das chavetas são preservados tal como estão.

As fórmulas incorporadas podem incluir quaisquer funções ou operadores. Tudo o que é necessário é que o resultado da fórmula possa ser coagido a uma cadeia de texto. Por exemplo, esta fórmula insere NickName, se for fornecido, senão irá inserir FirstName numa saudação:

$"Welcome {Coalesce( NickName, FirstName )}, it's great to meet you!"

Se NickName estiver definido como "Joe", esta fórmula produz a cadeia de texto Bem-vindo Joe, é um prazer conhecê-lo!. No entanto, se Alcunha estiver em branco e Nome próprio for "Joseph", esta fórmula produz Caro Joseph, muito prazer em conhecê-lo! em vez disso.

A interpolação de carateres pode incluir cadeias de texto padrão na fórmula incorporada. Por exemplo, se NickName ou FirstName não forem fornecidos, conseguiríamos, ainda assim, produzir "Amigo" como substituição:

$"Welcome {Coalesce( NickName, FirstName, "Friend" )}!"

As interpolações de cadeias podem até ser aninhadas. Considere este exemplo onde os nomes próprio, do meio e último são combinados numa saudação. Mesmo que um ou dois destes valores estejam em branco, o número correto de espaços é mantido entre as partes do nome. Se não for fornecida nenhuma das partes, a interpolação da cadeia interna irá fechar-se numa cadeia vazia e será substituída pela função Coalesce por "Amigo".

$"Welcome {Coalesce( Trim( $"{First} {Middle} {Last}"}), "Friend" )}!"

Linhas novas

As cadeias de texto incorporadas podem conter linhas novas. Por exemplo, considere definir a propriedade Text de um controlo Label para o seguinte:

"Line 1
Line 2
Line 3"

Esta fórmula resulta em três linhas mostradas no controlo de etiqueta:

As novas linhas também são suportadas com a interpolação de cadeias:

$"Line {1}
Line {1+1}
Line {1+1+1}"

O que resulta na mesma saída:

Recursos de imagem e multimédia

Através do menu Ficheiro, pode adicionar imagens, vídeos e ficheiros de áudio como recursos de aplicação. O nome do ficheiro importado passa a ser o nome do recurso na aplicação. Neste gráfico, o logótipo da Northwind Traders, denominado nwindlogo, foi adicionado à aplicação:

Para utilizar este recurso numa aplicação, especifique-o na propriedade Image de um controlo de Image:

URIs para imagens e outras tipos de multimédia

Pode aprofundar-se um pouco mais no último exemplo definindo a propriedade Text de um controlo de Label como nwindlogo. A etiqueta mostra uma cadeia de texto:

As aplicações de tela referenciam cada imagem ou outro ficheiro de multimédia, quer seja na nuvem ou adicionados como um recurso de aplicação, por uma cadeia de texto URI.

Por exemplo, a propriedade Image de um controlo aceita não apenas recursos de aplicação, mas também ligações para imagens na Web, tal como "https://northwindtraders.com/logo.jpg"". A propriedade também aceita imagens inline que utilizam o esquema URI de dados, tal como neste exemplo:

"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAkAAAAFAQMAAACtnVQoAAAABlBMVEUAAAB0J3UMNU6VAAAAAXRSTlMAQObYZgAAABRJREFUCNdjUGJgCGVg6GgAkkA2AA8/AffqCEBsAAAAAElFTkSuQmCC"

Esse URI apresenta uma versão escalada de dois diamantes roxos:

Pode mostrar a imagem mais recente capturada num controlo de Camera se definir a propriedade Image de um controlo image para a propriedade Photo do controlo da câmara. A aplicação contém a imagem na memória e a propriedade Photo do controlo camera devolve uma referência de URI para a imagem. Por exemplo, poderá tirar uma foto e a propriedade Photo da câmara poderá devolver "appres://blobmanager/7b12ffa2ea4547e5b3812cb1c7b0a2a0/1".

Utiliza um URI para referenciar uma imagem ou outro ficheiro de multimédia armazenado numa base de dados. Desta forma, a aplicação não obtém os dados reais até que seja necessário. Por exemplo, um anexo numa tabela Microsoft Dataverse pode devolver "appres://datasources/Contacts/table/..." Como no exemplo da câmara, pode exibir esta imagem definindo a propriedade Image de um controlo image para esta referência, que recupera os dados binários.

Quando guarda um tipo de dados de multimédia, tal como uma imagem, numa base de dados, a aplicação envia a imagem real ou os dados de multimédia, e não a referência URI.

Limites de tamanho

Como cadeias de texto e URIs, estes tipos de dados não têm limite predefinido quanto ao respetivo comprimento.

Os dados binários que estes tipos de dados referenciam também não têm limite de predefinição ao tamanho. Por exemplo, uma imagem capturada através do controlo camera que é referenciado como "appres://..." pode ter uma resolução tão grande e alta quanto a câmara do dispositivo o permite. A resolução, a velocidade de fotogramas e outros atributos dos ficheiros de multimédia não estão limitados pelo tipo de dados, mas os controlos específicos para reprodução e captura de multimédia podem ter as suas próprias limitações.

No entanto, todos os tamanhos de dados estão sujeitos à quantidade de memória disponível na aplicação. Os browsers em execução num computador de secretária suportam, normalmente, mais de 100 megabytes de dados. No entanto, a quantidade de memória disponível num dispositivo, tal como um telemóvel, poderá ser muito inferior, normalmente entre 30 a 70 megabytes. Para determinar se a sua aplicação é executada nestes limites, teste cenários comuns em todos os dispositivos em que esta deverá ser executada.

Como melhor prática, mantenha os dados na memória durante o tempo necessário. Carregue imagens numa base de dados assim que puder; transfira imagens apenas quando o utilizador da aplicação as solicitar.

Números

O Power Fx suporta dois tipos de número: Decimal e Flutuante (com os sinónimos Número e Moeda).

Decimal é melhor para a maioria dos cálculos de negócios. Pode representar com precisão os números na base 10, o que significa que 0.1 pode ser representado com precisão e evitará erros de arredondamento durante os cálculos. Tem um alcance grande o suficiente para qualquer necessidade de negócios, até 10²⁸ com até 28 dígitos de precisão. Decimal é o tipo de dados numérico predefinido para a maioria dos anfitriões do Power Fx, sendo utilizado se alguém simplesmente escreve 2*2.

Flutuante é mais indicado para cálculos científicos. Pode representar números num intervalo maior, até 10³⁰⁸. A precisão é limitada a 15 casas decimais e a matemática é baseada na base 2, por isso não pode representar alguns valores decimais comuns com precisão. Float também tem maior desempenho e é favorecido se esse for um fator e a precisão não for crítica.

Números decimais

O tipo de dados Decimal utiliza com frequência o tipo de dados decimal .NET. Alguns hosts, como colunas de fórmula Dataverse que são executadas no SQL Server, usam o tipo de dados decimal do SQL Server.

Decimal faz a matemática da maneira que aprendeu na escola, usando a base de 10 dígitos, importante para evitar erros de arredondamento de diferenças muito pequenas que podem acumular-se ao usar a matemática de base 2 (como usado por Flutuante).

O intervalo varia entre positivo 79,228,162,514,264,337,593,543,950,335 e negativo 79,228,162,514,264,337,593,543,950,335. O separador decimal pode ser colocado em qualquer lugar desses números, fornecendo até 28 dígitos de precisão, e ainda ser representado com precisão. Por exemplo, 79,228,162,514,264.337593543950335 pode ser representado com exatidão, assim como 7.9228162514264337593543950335.

Números de vírgula flutuante

O tipo de dados Flutuante, também conhecido como Número ou Moeda, utiliza a norma de vírgula flutuante de precisão dupla IEEE 754. Esta norma fornece um intervalo muito grande de números em que trabalhar, de –1,79769 x 10³⁰⁸ a 1,79769 x 10³⁰⁸. O valor mínimo que pode ser representado é 5 x 10^–324.

Flutuante pode representar exatamente números inteiros entre –9.007.199.254.740.991 (–(2⁵³ – 1)) e 9.007.199.254.740.991 (2⁵³ – 1), inclusive. Este intervalo é superior ao dos tipos de dados de número inteiro de 32 bits (ou 4 bytes) que as bases de dados utilizam normalmente. No entanto, as aplicações de tela não podem representar tipos de dados inteiros de 64 bits (ou 8 bytes). Poderá pretender armazenar o número num campo de texto ou utilizar uma coluna calculada para fazer uma cópia do número num campo de texto, para que seja mapeado para um tipo de dados de Texto na aplicação de tela. Desta forma, pode manter, apresentar e introduzir estes valores, e compará-los para determinar se são iguais; no entanto, não é possível realizar cálculos numéricos sobre eles desta forma.

A aritmética de vírgula flutuante é aproximada, pelo que pode, por vezes, fornecer resultados inesperados com muitos exemplos documentados. Poderá esperar que a fórmula 55 / 100 * 100 devolva exatamente 55 e (55 / 100 * 100) - 55 devolva exatamente zero. No entanto, a última fórmula devolve 7,1054 x 10^–15, o que é muito pequeno, mas não zero. Essa pequena diferença normalmente não causa problema, sendo que a aplicação a arredonda ao mostrar o resultado. No entanto, as pequenas diferenças podem ser compostas em cálculos subsequentes e parecem dar a resposta errada.

Os sistemas de base de dados frequentemente armazenam moedas e efetuam cálculos utilizando matemática decimal, que oferece um intervalo menor, mas maior controlo sobre a precisão. Por predefinição, as aplicações de tela mapeiam as moedas dentro e fora de valores de vírgula flutuante; consequentemente, o resultado poderá ser diferente dos cálculos efetuados num tipo de dados de casas decimais nativas. Dependendo das necessidades de precisão do seu aplicativo, convém trabalhar com esses valores como Texto, conforme descrito anteriormente para inteiros grandes.

Predefinições e conversões

A maioria dos anfitriões do Power Fx utiliza Decimal por predefinição. Ter esta predefinição significa:

• Números literais em fórmulas. O número 1.234 é interpretado como um valor Decimal. Por exemplo, a fórmula 1.234 * 2 interpreta o 1.234 e 2 como Decimal e devolve um resultado Decimal.
• Função Value. Value( "1.234" ) regressa um valor Decimal. Por exemplo, na fórmula Value( "1.234" ) * 2, a função Value interpreta o conteúdo da cadeia de texto "1.234" como um Decimal.

Para trabalhar com valores Flutuantes, utilização a função Float. Expandir o nosso exemplo, Float( 1.234 ) converte o Decimal1.234 para Flutuante. A função Float também pode ser utilizada para substituir a função Value para converter uma cadeia que contém um número de vírgula flutuante, tal como Float( "1.234" ), num valor Flutuante, o que é necessário se não for possível representar o número como Decimal.

Em resumo:

Misturar tipos numéricos

Os valores Flutuantes e Decimais podem ser misturados livremente. Quando estão misturados, os valores Decimais são convertidos em valores Flutuantes devido ao intervalo maior. Como essa conversão pode resultar em perda de precisão, é importante não misturar os dois desnecessariamente. Como Decimal é o tipo de dados literal padrão e a maioria das funções numéricas preserva o tipo, é relativamente fácil evitar mover para Float sem desejá-lo.

Por exemplo, considere o seguinte cálculo utilizando pac power-fx repl após a instalação da CLI do Power Platform. Como ambos os números são Decimais, o cálculo é feito em Decimais e o resultado mantém a precisão total:

>> 1.0000000000000000000000000001 * 2
2.0000000000000000000000000002

Se, em vez disso, o segundo operando fosse alterado para Flutuante, todo o cálculo seria efetuado no tipo Flutuante e a pequena parte fracionária seria perdida:

>> 1.0000000000000000000000000001 * Float(2)
2

Data, Hora e DateTime

Fusos horários

Os valores de data/hora encaixam-se nestas categorias:

• Região do utilizador: estes valores são armazenados em UTC (Hora Universal Coordenada), mas o fuso horário do utilizador da aplicação afeta o modo como a aplicação mostra estes valores e a forma como o utilizador da aplicação especifica os mesmos. Como exemplo, o mesmo momento é apresentado de forma diferente a um utilizador no Canadá do que para um utilizador no Japão.
• Independente de fuso horário: a aplicação mostra estes valores da mesma forma e o utilizador da aplicação especifica-os da mesma forma, independentemente do fuso horário. O mesmo momento é apresentado da mesma forma a um utilizador no Canadá como para um utilizador no Japão. Os autores de aplicações que não esperam que as suas aplicações sejam executadas em fusos horários diferentes utilizam estes valores porque são mais simples.

Esta tabela mostra alguns exemplos:

Para a data/horas da Região do utilizador, as aplicações de tela utilizam o fuso horário do browser ou dispositivo, mas as aplicações condicionadas por modelo utilizam a definição do utilizador no Dataverse. Essas configurações geralmente correspondem, mas os resultados diferem se forem diferentes.

Utilize as funções DateAdd e TimeZoneInformation para converter a hora local em UTC e reverter. Consulte os exemplos no fim da documentação para estas funções.

Equivalentes numéricos

As aplicações de tela mantêm e calculam todos os valores de data/hora, quer sejam de Região do utilizador ou Independente de fuso horário em UTC. A aplicação converte os valores com base no fuso horário do utilizador da aplicação quando os mostra e quando o utilizador da aplicação os especifica.

Quando uma aplicação de tela lê um valor Independente de fuso horário a partir de uma origem de dados ou escreve tal valor numa origem de dados, a aplicação ajusta automaticamente o valor para compensar o fuso horário do utilizador da aplicação. A aplicação, em seguida, trata o valor como um valor UTC, consistente com todos os outros valores de data/hora na aplicação. Devido a esta compensação, o valor Independente de fuso horário original é apresentado quando a aplicação ajusta o valor UTC para o fuso horário do utilizador da aplicação.

Pode observar este comportamento mais detalhadamente utilizando a função Value para aceder ao valor numérico subjacente para um valor de data/hora. Esta função devolve o valor de data/hora como o número de milissegundos desde 1 de janeiro de 1970, 00:00:00.000 UTC.

Dado que cada valor de data/hora é mantido em UTC, o fórmula Value( Date( 1970, 1, 1 ) ) não retornará zero na maioria das regiões do mundo porque a função Date devolve uma data em UTC. Por exemplo, a fórmula retorna 28 800 000 num fuso horário que está deslocado de UTC por oito horas. Esse número reflete o número de milissegundos em oito horas.

Regressando ao nosso exemplo:

Converter horas Unix

As horas Unix refletem o número de segundos desde 1 de janeiro de 1970, 00:00:00 UTC. Visto que as aplicações de tela utilizam milissegundos em vez de segundos, pode converter entre os dois multiplicando ou dividindo por 1000.

Por exemplo, o hora Unix mostra 9 de setembro de 2001 às 01:46:40 UTC como 1.000.000.000. Para mostrar esse valor de data/hora numa aplicação de tela, multiplique esse número por 1000 para convertê-lo em milissegundos e, em seguida, utilize-o numa função Text. A fórmula Text( 1000000000 * 1000, DateTimeFormat.UTC ) devolve a cadeia de caracteres 2001-09-09T01:46:40.000Z.

No entanto, essa função devolve sábado, 8 de setembro de 2001, 18:46:40 se utilizar o formato DateTimeFormat.LongDateTime24 num fuso horário que tenha uma diferença de -7 horas do UTC (7 horas a oeste do UTC). Este resultado mostra o valor DateTime corretamente com base no fuso horário local.

Para converter para uma hora Unix, divida o resultado a partir de Valor por 1000:
RoundDown( Valor( UnixTime ) / 1000, 0 )

Se necessitar da hora Unix num valor Data para cálculos adicionais ou apresentar no Power Apps, utilize esta fórmula:
DateAdd( Data( 1970,1,1 ), UnixTime, Segundos )

SQL Server

O SQL Server tem DateTime, Datetime2 e outros tipos de dados de data/hora que não incluem um deslocamento de fuso horário e que não indicam o fuso horário em que se encontra. As aplicações de tela assumem que estes valores são armazenados em UTC e tratam-nos como Região do utilizador. Se os valores se destinarem a ser independentes de fuso horário, corrija as traduções UTC utilizando a função TimeZoneOffset.

As aplicações de tela utilizam as informações de fuso horário incluídas nos campos Datetimeoffset ao converterem um valor na representação UTC interna da aplicação. As aplicações utilizam sempre UTC como fuso horário (deslocamento de fuso horário zero) quando gravam dados.

As aplicações de tela lêem e escrevem valores dos tipos de dados Hora no SQL Server como cadeias de texto no formato de duração ISO 8601. Por exemplo, tem de analisar este formato de cadeia de caracteres e utilizar a função Time para converter a cadeia de texto "PT2H1M39S" num valor Hora:

With(
    Match( "PT2H1M39S", "PT(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ),
    Time( Value( hours ), Value( minutes ), Value( seconds ) )
)
// Result: 2:01 AM (as shown in a label control, use the Text function to see the seconds)

Misturar informações de data e hora

Data, Hora e DateTime têm nomes diferentes, mas contêm as mesmas informações sobre datas e horas.

Um valor de Data pode incluir informações de hora com ele, que é normalmente meia-noite. Um valor de Hora pode transportar informações de data, normalmente, 1 de janeiro de 1970. O Dataverse também armazena informações de hora com um campo Apenas Data, mas mostra apenas as informações de data por predefinição. Da mesma forma, as aplicações de tela distinguem entre estes tipos de dados para determinar os formatos e controlos predefinidos.

Adicionar e subtrair valores de data e hora diretamente não é recomendado porque o fuso horário e outras conversões poderiam causar resultados confusos. Utilize a função Value para converter os valores de data/hora em milissegundos primeiro e tenha em conta o fuso horário do utilizador da aplicação ou utilize as funções DateAdd e DateDiff para adicionar ou subtrair um destes valores.

Escolhas e Sim/Não

Opções e tipos de dados de duas opções oferecem duas ou mais opções para um usuário do aplicativo selecionar. Por exemplo, uma escolha do Estado da Ordem pode oferecer as escolhas Novas, Enviadas, Faturadas e Fechadas. O tipo de dados de duas opções oferece apenas duas opções.

Ambos os tipos de dados mostram seus rótulos como texto. Por exemplo, um controlo de etiqueta mostra uma das opções de estado de encomenda se a propriedade Text do controlo estiver definida para uma fórmula que faz referência a essa escolha. Os rótulos de opções podem ser localizados para usuários de aplicativos em diferentes locais.

Quando um usuário do aplicativo seleciona uma opção e salva a alteração, o aplicativo envia os dados para o banco de dados, que os armazena de forma independente do idioma. Uma opção em uma escolha é enviada e armazenada como um número, e uma opção em um tipo de dados de duas opções é enviada e armazenada como um valor booleano.

As etiquetas são apenas para exibição. Não é possível comparar os rótulos diretamente porque eles são específicos de um idioma. Em vez disso, cada escolha tem uma enumeração que funciona com o número subjacente ou o valor booleano. Por exemplo, não pode utilizar esta fórmula:

If( ThisItem.OrderStatus = "Active", ...

Mas pode utilizar esta fórmula:

If( ThisItem.OrderStatus = OrderStatus.Active, ...

Para as escolhas globais (que as tabelas partilham), o nome da enumeração do conjunto de opções corresponde ao nome da escolha global. Para opções locais (que têm como escopo uma tabela), o nome pode incluir o nome da tabela. Esse comportamento evita conflitos se várias tabelas tiverem opções com o mesmo nome. Por exemplo, a tabela Contas pode ter uma escolha OrderStatus e o seu nome pode ser OrderStatus (Contas). Esse nome tem espaços e parênteses, então você precisa envolvê-lo com aspas simples se fizer referência a ele em uma fórmula.

Os valores de duas opções também se comportam como valores booleanos. Por exemplo, um valor de duas opções chamado TaxStatus pode ter os rótulos Tributável e Não Tributável, que correspondem a true e false. Para mostrar isso, use esta fórmula:

If( ThisItem.Taxable = TaxStatus.Taxable, ...

Você também pode usar esta fórmula:

If( ThisItem.Taxable, ...