Tipos de dados

As informações fluem por um aplicativo em valores pequenos e discretos, muito parecidos com as células de uma planilha. Por exemplo, dados em um campo Aniversário e um campo Data Especial fluiriam como um valor Date que inclui o ano, o mês e o dia. O aplicativo sabe como formatar esses valores, restringir a entrada ao que é apropriado para cada um e compartilhar os valores com um banco de dados. Os aniversários diferem das datas especiais para as pessoas, mas o sistema os trata exatamente da mesma maneira. Nesse caso, Date é um exemplo de tipo de dados.

Este artigo fornece detalhes para os tipos de dados com que os aplicativos de tela são compatíveis. Quando um aplicativo se conecta a um fonte de dados externo, cada tipo de dados nessa origem é mapeado para um tipo de dados para aplicativos de tela.

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

Blank

Todos os tipos de dados podem ter um valor de em branco (em outras palavras, 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 todos os valores da variável global x.

Teste se há um valor em branco usando 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 a em branco, os tipos de dados Boolean e Two option efetivamente 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 um banner quando o botão é pressionado, em que a primeira e a última aspas duplas são omitidas (uma vez que delimitam a string de texto) e as aspas duplas repetidas em torno 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. Isso geralmente é mais fácil de trabalhar e visualizar a saída do que usar a função Concatenar 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 forçado a uma cadeia de caracteres de texto. Por exemplo, esta fórmula irá inserir 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 estará 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"

A 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, conforme mostrado abaixo:

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

A fórmula acima 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 a um 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 realmente 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 será 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 comerciais. Ele pode representar com precisão números na base 10, o que significa que 0.1 pode ser representado com exatidão e não estará sujeito a 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 dado numérico padrão para a maioria dos Power Fx hosts, usado se alguém simplesmente escrever 2*2.

Float é melhor para cálculos científicos. Pode representar números em um intervalo muito maior, até 10³⁰⁸. A precisão é limitada a 15 casas decimais e a matemática é baseada na base 2, portanto, não pode representar com precisão alguns valores decimais comuns. Float também tem desempenho superior e é favorecido se esse for um fator e a precisão não for 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 executadas no SQL Server, usam o tipo de dados decimais do SQL Server.

Decimal faz matemática do jeito que você aprendeu na escola, usando dígitos de base 10. Isso é muito importante para evitar erros de arredondamento de diferenças muito pequenas que podem se acumular ao usar matemática de 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.

Float pode representar exatamente números inteiros (ou 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 Text no aplicativo de tela. Dessa maneira, você pode manter, exibir e inserir esses valores, além de compará-los para determinar se são iguais; no entanto, você não pode executar cálculos numéricos 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. Se esse tipo de discrepância causar problemas, convém trabalhar com esses valores como Text, assim como você pode com números inteiros grandes descritos anteriormente nesta seção.

Padrões e conversões

A maioria dos hosts Power Fx usa Decimal por padrão. Isso impacta:

• Números literais em fórmulas. O número 1.234 será interpretado como um valor Decimal. Por exemplo, a fórmula 1.234 * 2 interpretará 1.234 e 2 como Decimal e retornará um Resultado decimal.
• Função Value. Value( "1.234" ) retornará um valor Decimal . Por exemplo, a fórmula Value( "1.234" ) * 2 a função Valor interpretará o conteúdo da string de texto "1.234" como um Decimal.

Para trabalhar com valores Flutuantes, a função Float é usada. Estendendo o exemplo acima, Float( 1.234 ) converterá Decimal1.234 para Flutuante. Float também pode ser usado como um substituto para Value para converter uma string contendo um número de ponto flutuante, como Float( "1.234" ) para um valor Float , o que é necessá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 isso 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 preservará o tipo, é relativamente fácil evitar a mudança para Flutuante sem desejar.

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 Float 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:

• Usuário local: Esses valores são armazenados em UTC (Tempo Universal Coordenado), mas o fuso horário do usuário do aplicativo afeta como o aplicativo mostra esses valores e como o usuário do aplicativo 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 de 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 serão diferentes 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 anterior:

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(Valor(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(Data(1970,1,1), UnixTime, Segundos)

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

Data, Hora e DataHora têm nomes diferentes, mas todos contêm 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

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

Ambos os tipos de dados mostram seus rótulos em um contexto de cadeia de caracteres de 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 das opções podem estar localizados para usuários de aplicativos em diferentes locais.

Quando um usuário do aplicativo seleciona uma opção e salva essa alteração, o aplicativo transmite os dados para o banco de dados, que armazena esses dados em uma representação independente do idioma. Uma opção em uma escolha é transmitida e armazenada como um número, e uma opção em um tipo de dados de duas opções é transmitida e armazenada como um valor booliano.

Os rótulos são apenas para fins de exibição. Você não pode realizar comparações diretas com os rótulos, porque eles são específicos para 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 como escopo uma tabela), o nome poderá conter o nome da tabela. Esse comportamento evitará 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 contém um ou mais espaços e parênteses e, portanto, você deve colocá-lo entre aspas simples se fizer referência a uma fórmula.

Além disso, os valores de duas opções também podem se comportar 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, respectivamente. Para demonstrar, , você pode usar esta fórmula:

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

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

If( ThisItem.Taxable, ...