Tipos de dados

As informações fluem por meio 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 de 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 das pessoas, mas o sistema os manipula da mesma maneira. Nesse caso, Date é um exemplo de tipo de dados.

Este artigo explica cada tipo de dados no Power Fx, como eles funcionam e como eles 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 de Hiperlink 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 usado em bancos de dados para esse conceito.

Use 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 . Substitua possíveis valores em branco por valores não em branco usando a função Coalesce.

Como todos os tipos de dados dão suporte em branco, os tipos de dados boolianos e de duas opções têm três valores possíveis.

Text, Hyperlink, Image e Media

Todos esses quatro tipos de dados são baseados em uma cadeia de caracteres de texto Unicode.

Texto inserido

As cadeias de caracteres de texto inseridas em uma fórmula são colocadas entre aspas duplas. Use duas aspas duplas juntas para representar uma única aspas duplas na cadeia de caracteres de texto. Por exemplo, usando a fórmula a seguir na propriedade OnSelect de um controle Button:

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

Resulta em uma faixa quando o botão é pressionado, em que as primeiras e últimas aspas duplas são omitidas (como delimitam a cadeia de caracteres de texto) e as aspas duplas repetidas ao redor de Hello, World! são substituídas por uma única aspa dupla:

As aspas simples são usadas para nomes identificadores que contêm caracteres especiais e não têm significado especial em uma cadeia de caracteres de texto.

Interpolação de cadeia de caracteres

Use a interpolação de cadeias de caracteres para inserir fórmulas em uma cadeia de caracteres de texto. Esta abordagem geralmente é mais fácil de trabalhar e visualizar a saída do que usar a função Concatenate ou o operador &.

Prefixe a cadeia de caracteres de texto com um cifrão $ e coloque a fórmula a ser inserida entre chaves { }. Para incluir uma chave na cadeia de caracteres de texto, use chaves repetidas: {{ ou }}. A interpolação de cadeias de caracteres pode ser usada em qualquer lugar em que uma cadeia de caracteres de texto padrão possa ser usada.

Por exemplo, considere esta fórmula com as variáveis globais Apples definida como 3 e Banana definida como 4:

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

Esta fórmula retorna a string de texto We have 3 apples, 4 bananas, yielding 7 fruit total. As variáveis Apples e Bananas são inseridas no texto substituindo as chaves, juntamente com o resultado da fórmula matemática Apples+Bananas. Espaços e outros caracteres ao redor das chaves são preservados como estão.

As fórmulas inseridas 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 caracteres de texto. Por exemplo, esta fórmula insere NickName se for fornecido, ou, caso contrário, o FirstName, em uma saudação:

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

Se NickName estiver definido como "Joe", essa fórmula produzirá a cadeia de caracteres de texto Welcome Joe, it's great to meet you! (Bem-vindo Joe, é um prazer conhecê-lo!). Mas se NickName for blank e FirstName for "Joseph", então a fórmula gera Dear Joseph, great to meet you!.

A interpolação de cadeias de caracteres pode incluir cadeias de caracteres de texto padrão na fórmula inserida. Por exemplo, se nem NickName nem FirstName foram fornecidos, ainda poderíamos fornecer "Friend" como substituto:

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

As interpolações de cadeias de caracteres podem até ser aninhadas. Considere este exemplo, onde First, Middle e Last são combinados em uma saudação. Mesmo que um ou dois desses valores estejam em branco, o número correto de espaços é mantido entre as partes do nome. Se nenhuma das partes for fornecida, a interpolação da cadeia de caracteres interna será reduzida a uma cadeia de caracteres vazia e será substituída pela função Coalesce por "Friend".

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

Novas linhas

As cadeias de caracteres de texto inseridas podem conter novas linhas. Por exemplo, considere configurar a propriedade Text de um controle Label para o seguinte:

"Line 1
Line 2
Line 3"

Esta fórmula acima resulta em três linhas mostradas no controle de rótulo:

Novas linhas também têm suporte com interpolação de cadeias de caracteres:

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

Que resulta na mesma saída:

Recursos de imagem e mídia

Por meio do menu Arquivo, você pode adicionar arquivos de imagem, vídeo e áudio como recursos de aplicativo. O nome do arquivo importado se torna o nome do recurso no aplicativo. Neste gráfico, o logotipo da Northwind Traders, chamado nwindlogo, foi adicionado ao aplicativo:

Para usar esse recurso em um aplicativo, especifique-o na propriedade Image de um controle Image:

URIs para imagens e outras mídias

Você pode se aprofundar um pouco nesse último exemplo, definindo a propriedade Text de um controle Label como nwindlogo. O rótulo mostra uma cadeia de caracteres de texto:

Os aplicativos Canvas referenciam cada imagem ou outro arquivo de mídia, seja na nuvem ou adicionado como recurso de aplicativo, por uma cadeia de caracteres de texto URI.

Por exemplo, a propriedade Image de um controle de imagem aceita não apenas recursos de aplicativo, mas também links para imagens na web, como "https://northwindtraders.com/logo.jpg". A propriedade também aceita imagens embutidas que usam o esquema de URI de dados, como neste exemplo:

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

Esse URI exibe uma versão ampliada de dois diamantes roxos:

Você pode mostrar a imagem mais recente capturada em um controle Camera se você definir a propriedade Image de um controle de imagem para a propriedade Photo do controle da câmera. O aplicativo mantém a imagem na memória, e a propriedade Photo do controle da câmera retorna uma referência de URI para a imagem. Por exemplo, você poderia tirar uma foto, e a propriedade Photo da câmera poderia retornar "appres://blobmanager/7b12ffa2ea4547e5b3812cb1c7b0a2a0/1".

Você usa um URI para fazer referência a uma imagem ou outro arquivo de mídia armazenado em um banco de dados. Dessa forma, o aplicativo não recupera os dados reais até que sejam necessários. Por exemplo, um anexo em uma tabela do Microsoft Dataverse pode retornar "appres://datasources/Contacts/table/..." Como no exemplo da câmera, você pode exibir esta imagem definindo a propriedade Image de um controle de imagem para essa referência, que recupera os dados binários.

Quando você salva um tipo de dados de mídia, como uma imagem, em um banco de dados, o aplicativo envia a imagem ou dados de mídia reais, não a referência do URI.

Limites de tamanho

Como cadeias de caracteres de texto e URIs, esses tipos de dados não têm limite predefinido em seu comprimento.

Os dados binários aos quais esses tipos de dados se referem também não têm limite predefinido de tamanho. Por exemplo, uma imagem capturada pelo controle da câmera, agora referenciada como "appres://..." pode ter a resolução grande e alta que a câmera do dispositivo pode reunir. A resolução, taxa de quadros e outros atributos dos arquivos de mídia não são limitados pelo tipo de dados, mas os controles específicos para reproduzir e capturar mídia podem ter suas próprias limitações.

No entanto, todos os tamanhos de dados estão sujeitos à quantidade de memória disponível no aplicativo. Os navegadores executados em um computador desktop geralmente oferecem suporte a mais de 100 megabytes de dados. No entanto, a quantidade de memória disponível em um dispositivo como um telefone pode ser muito menor, geralmente na faixa de 30 a 70 megabytes. Para determinar se seu aplicativo é executado dentro desses limites, teste cenários comuns em todos os dispositivos nos quais ele deve ser executado.

Como prática recomendada, mantenha os dados na memória apenas pelo tempo necessário. Carregue imagens em um banco de dados assim que puder; baixe imagens apenas quando o usuário do aplicativo as solicitar.

Números

O Power Fx é compatível com dois tipos de números: Decimal e Flutuante (com sinônimos Número e Moeda).

Decimal é melhor para a maioria dos cálculos de negócios. Ele pode representar com precisão números na base 10, o que significa que 0.1 pode ser representado exatamente e evitará erros de arredondamento durante os cálculos. Possui 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 padrão para a maioria dos hosts do Power Fx, usado se alguém simplesmente escreve 2*2.

Flutuante é melhor para cálculos científicos. Ele pode representar números em um intervalo maior, até 10³⁰⁸. A precisão é limitada a 15 casas decimais e a matemática é baseada na base 2, portanto, não pode representar alguns valores decimais comuns precisamente. O Float também tem um desempenho mais alto e é favorecido se esse é um fator e a precisão não é crítica.

Números decimais

O tipo de dados Decimal geralmente usa o tipo de dados decimal .NET. Alguns hosts, como colunas de fórmula do Dataverse que são executadas no SQL Server, usam o tipo de dados decimais do SQL Server.

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

O intervalo é de positivo 79.228.162.514.264.337.593.543.950.335 para negativo 79.228.162.514.264.337.593.543.950.335. O separador decimal pode ser colocado em qualquer lugar dentro desses números, fornecendo até 28 dígitos de precisão e ainda assim 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 ponto flutuante

O tipo de dados Flutuante, também conhecido como Número ou Moeda, usa o Padrão de ponto flutuante de precisão dupla IEEE 754. Esse padrão fornece um intervalo muito grande de números para trabalhar, de –1,79769 x 10³⁰⁸ a 1,79769 x 10³⁰⁸. O menor valor 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. Esse intervalo é maior do que os tipos de dados inteiros de 32 bits (ou 4 bytes) que os bancos de dados normalmente usam. No entanto, os aplicativos de tela não podem representar tipos de dados inteiros de 64 bits (ou 8 bytes). Convém armazenar o número em um campo de texto ou usar uma coluna calculada para fazer uma cópia do número em um campo de texto, para que seja mapeado para um tipo de dados de Texto no aplicativo de tela. Dessa maneira, você pode manter, exibir e inserir esses valores e compará-los para determinar se são iguais; no entanto, você não pode realizar cálculos numéricos neles neste formulário.

A aritmética de ponto flutuante é aproximada e, portanto, às vezes pode dar resultados inesperados com muitos exemplos documentados. Você pode esperar que a fórmula 55 / 100 * 100 retorne exatamente 55 e (55 / 100 * 100) - 55 retorne exatamente zero. No entanto, a última fórmula retorna 7,1054 x 10^–15, que é muito pequeno, mas não é zero. Essa pequena diferença normalmente não causa um problema, e o aplicativo a arredonda ao mostrar o resultado. No entanto, pequenas diferenças podem se agravar nos cálculos subsequentes e parecem dar a resposta errada.

Os sistemas de banco de dados geralmente armazenam moedas e realizam cálculos usando matemática decimal, que oferece um intervalo menor, mas maior controle sobre a precisão. Por padrão, os aplicativos de tela mapeiam as moedas dentro e fora dos valores de ponto flutuante; portanto, o resultado pode diferir dos cálculos feitos em um tipo de dados decimal nativo. Dependendo das necessidades de precisão do seu aplicativo, talvez você queira trabalhar com esses valores como Texto, conforme descrito para inteiros grandes anteriormente.

Padrões e conversões

A maioria dos hosts Power Fx usa Decimal por padrão. Ter esse padrã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 retorna um resultado Decimal.
• Função Value. Value( "1.234" ) retorna um valor Decimal. Por exemplo, na fórmula Value( "1.234" ) * 2, a função Valor interpreta o conteúdo da cadeia de texto "1.234" como um Decimal.

Para trabalhar com valores Flutuantes, a função Float é usada. Estender nosso exemplo, Float( 1.234 ) converte o Decimal1.234 em Flutuante. Flutuante também pode ser usado como um substituto para Valor para converter uma string contendo um número de ponto flutuante, como Float( "1.234" ) para um valor flutuante , que será obrigatório se o número não puder ser representado como um decimal.

Em resumo:

Misturando tipos numéricos

Valores Flutuantes e Decimais podem ser misturados livremente. Quando misturados, os valores Decimais são convertidos em valores Flutuantes devido ao intervalo maior. Como essa conversão pode resultar em uma 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 cálculo a seguir usando pac power-fx repl após instalar a Power Platform CLI. Como ambos os números são Decimais, o cálculo é feito em Decimal 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 então todo o cálculo seria feito em Flutuante e a minúscula parte fracionária seria perdida:

>> 1.0000000000000000000000000001 * Float(2)
2

Date, Time e DateTime

Fusos horários

Os valores Date/time se enquadram nestas categorias:

• Local do usuário: esses valores são armazenados em UTC (Horário Universal Coordenado), mas o fuso horário do usuário do aplicativo afeta como o aplicativo mostra esses valores e como o usuário os especifica. Como exemplo, o mesmo momento aparece de maneira diferente para um usuário no Canadá e para um usuário no Japão.
• Independente do fuso horário: o aplicativo mostra esses valores da mesma maneira e o usuário do aplicativo os especifica da mesma maneira, independentemente do fuso horário. O mesmo momento aparece da mesma maneira para um usuário no Canadá e para um usuário no Japão. Os autores de aplicativos que não esperam que seus aplicativos sejam executados em fusos horários diferentes usam esses valores porque, em geral, são mais simples.

Esta tabela mostra alguns exemplos:

Para datas/horas do Local do usuário, os aplicativos de tela usam o fuso horário do navegador ou dispositivo, mas os aplicativos baseados em modelo usam a configuração do usuário no Dataverse. Essas configurações normalmente correspondem, mas os resultados diferem se essas configurações forem diferentes.

Use as funções DateAdd e TimeZoneInformation para converter a hora local em UTC e vice-versa. Veja os exemplos no final da documentação para essas funções.

Equivalentes numéricos

Os aplicativos de tela retêm e calculam todos os valores de data/hora, independentemente de Local do usuário ou Independente do fuso horário em UTC. O aplicativo converte os valores com base no fuso horário do usuário ao mostrá-los e quando o usuário os especifica.

Quando um aplicativo de tela lê um valor Independente do fuso horário de uma fonte de dados ou grava esse valor em um fonte de dados, o aplicativo ajusta automaticamente o valor para compensar o fuso horário do usuário do aplicativo. O aplicativo trata o valor como um valor UTC, consistente com todos os outros valores de data/hora no aplicativo. Devido a essa compensação, o valor original de Independente do fuso horário aparece quando o aplicativo ajusta o valor UTC para o fuso horário do usuário do aplicativo.

Você pode observar esse comportamento mais de perto usando a função Value para acessar o valor numérico subjacente para um valor de data/hora. Esta função retorna o valor de data/hora como o número de milissegundos desde 1º de janeiro de 1970 00:00:00.000 UTC.

Como todos os valores de data/hora são mantidos em UTC, a fórmula Value( Date( 1970, 1, 1 ) ) não retornará zero na maior parte do mundo porque a função Date retorna uma data em UTC. Por exemplo, a fórmula retornaria 28.800.000 em um fuso horário com uma diferença de oito horas para UTC. Esse número reflete o número de milissegundos em oito horas.

Voltando ao nosso exemplo:

Conversão de horas em Unix

As horas no Unix refletem o número de segundos desde 1º de janeiro de 1970 00:00:00 UTC. Como os aplicativos de tela usam milissegundos em vez de segundos, é possível converter entre os dois multiplicando ou dividindo por 1.000.

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

No entanto, essa função retorna Sábado, 8 de setembro de 2001 18:46:40 se você usar o formato DateTimeFormat.LongDateTime24 em um fuso horário com desvio 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 um hora do Unix, divida o resultado de Value por 1.000:
RoundDown( Value( UnixTime ) / 1000, 0 )

Se você precisar da hora do Unix em um valor Date para cálculos adicionais ou exibição no Power Apps, use esta fórmula:
DateAdd( Date( 1970,1,1 ), UnixTime, Seconds )

SQL Server

O SQL Server tem Datetime, Datetime2 e outros tipos de dados date/time que não incluem um deslocamento de fuso horário e não indicam em que fuso horário estão. Os aplicativos de tela assumem que esses valores são armazenados em UTC e os tratam como Local do usuário. Se os valores forem independentes do fuso horário, corrija as traduções de UTC usando a função TimeZoneOffset.

Os aplicativos de tela usam as informações de fuso horário incluídas nos campos Datetimeoffset ao converter um valor na representação UTC interna do aplicativo. Os aplicativos sempre usam UTC como o fuso horário (deslocamento de fuso horário zero) quando escrevem dados.

Os aplicativos de tela leem e gravam valores do tipo de dados Time no SQL Server como cadeias de caracteres de texto no formato de duração ISO 8601. Por exemplo, você deve analisar esse formato de cadeia de caracteres e usar a função Time para converter a cadeia de caracteres de texto "PT2H1M39S" em um valor Time:

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)

Como mesclar informações de data e hora

Date, Time e DateTime têm nomes diferentes, mas todos possuem as mesmas informações sobre datas e horas.

Um valor Date pode incluir informações de hora, geralmente à meia-noite. Um valor Time pode conter informações de data, que geralmente é 1º de janeiro de 1970. O Dataverse também armazena informações de hora com um campo Somente Data mas mostra apenas as informações de data por padrão. Da mesma forma, os aplicativos de tela às vezes distinguem esses tipos de dados para determinar os formatos e controles padrão.

Não é recomendável adicionar e subtrair valores de data e hora diretamente, porque o fuso horário e outras conversões podem causar resultados confusos. Ou use a função Value para converter valores de data/hora em milissegundos primeiro e leve em consideração o fuso horário do usuário do aplicativo, ou use as funções DateAdd e DateDiff para adicionar ou subtrair um desses valores.

Opções e Sim/Não

Opções e tipos de dados de duas opções oferecem duas ou mais opções para um usuário de aplicativo selecionar. Por exemplo, uma opção Status do Pedido pode oferecer as opções Novo, Enviado, Faturado e Fechado. O tipo de dados de duas opções fornece apenas duas opções.

Ambos os tipos de dados mostram seus rótulos como texto. Por exemplo, um controle de rótulo mostrará uma das opções de status do pedido se a propriedade Text do controle for definida como uma fórmula que faz referência a essa opção. Os rótulos de opção podem ser localizados para usuários de aplicativos em locais diferentes.

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 uma maneira independente do idioma. Uma opção em uma opção é 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 booliano.

Os rótulos são somente para exibição. Você não pode comparar os rótulos diretamente porque eles são específicos de um idioma. Em vez disso, cada opção tem uma enumeração que funciona com o número subjacente ou valor booliano. Por exemplo, você não pode usar esta fórmula:

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

Mas você pode usar esta fórmula:

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

Para escolhas globais (que tabelas compartilham), o nome da enumeração option-set corresponde ao nome da escolha global. Para opções locais (que têm escopo para 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 Accounts pode ter uma opção OrderStatus, e seu nome pode ser OrderStatus (Accounts). Esse nome tem espaços e parênteses, portanto, você precisará cercá-lo com aspas simples se fizer referência a ele em uma fórmula.

Valores de duas opções também se comportam como valores boolianos. Por exemplo, um valor de duas opções chamado TaxStatus pode ter os rótulos Taxable e Non-Taxable, 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, ...