Comportamento e formato da coluna de data e hora

No Microsoft Dataverse, você pode especificar como os valores de data e hora são mostrados aos usuários e como são ajustados para fusos horários.

Além das propriedades padrão disponíveis com a maioria das colunas, as colunas de data e hora têm duas propriedades extras:

• Ajuste de fuso horário: se os valores devem ser ajustados para fusos horários.
• Formato: se deseja exibir a parte da hora do valor.

Ajuste de fuso horário

O Dataverse armazena todos os valores de data e hora no fuso horário UTC. Quando o aplicativo apresenta valores ou processa valores inseridos pelos usuários, o Dataverse e os aplicativos baseados em modelo podem se ajustar ao fuso horário do usuário com essas opções de Comportamento.

• Local do Usuário: ajusta os valores para o fuso horário do usuário. Este é o comportamento padrão para o formato de Data e hora. Você pode alterar isso uma vez para outro comportamento.
• Independente de fuso horário: nenhuma conversão de fuso horário. Este é o comportamento padrão para o formato Somente data.

Defina o fuso horário do usuário em opções pessoais, não no fuso horário do sistema no Windows, Android, iOS ou macOS. No entanto, o fuso horário do sistema pode afetar scripts de cliente que funcionam com datas JavaScript.

Formato

Todas as colunas de data e hora possuem um componente de horário, exceto quando o comportamento delas é Somente Data. Formato: determina se a parte da hora do valor deve ser exibida.

• Data e hora: exibe a data e hora do valor.
• Somente data: exibe somente a parte da data do valor.

Nota

Os usuários ainda poderão alterar a parte da hora se o Formato for Somente data. Por exemplo, usando chamadas de API Web ou um controle com componente de tempo. Esse comportamento é diferente do Comportamento somente de Data, em que a parte de tempo não é armazenada por completo.

Diretrizes de uso

Use o fuso horário independente quando as informações de fuso horário não forem necessárias, como horários de check-in do hotel. Com essa seleção, os usuários em todos os fusos horários verão o mesmo valor de data e hora.

Use Apenas a data quando as informações sobre a hora do dia e o fuso horário não forem necessárias, como aniversários ou comemorações. Com essa seleção, os usuários em todos os fusos horários verão o mesmo valor exato de data.

Fuso horário independente com Somente Data é praticamente o mesmo que definir a coluna como Somente Data. Use o primeiro se não tiver certeza se precisará da parte da hora no futuro.

Importante

Evite o formato Somente data com o comportamento Local do usuário. Os usuários em fusos horários diferentes podem ver uma data diferente, o que não é pretendido na maioria dos cenários. Quando um usuário define uma data em um aplicativo controlado por modelo, a parte de hora é automaticamente configurada como meia-noite de seu fuso horário. Isso pode fazer com que a data apareça um dia antes ou depois para outros usuários.

Exemplos

Valores de exibição

O Dataverse armazena 2023-10-15T07:30:00Z (ou 2023-10-15 para o comportamento Somente Data). Os usuários no fuso horário UTC-8 veem isso no aplicativo baseado em modelo ou com uma solicitação de API da Web para o valor formatado:

Comportamental	Formato	Valor de exibição
Local do usuário	Data e hora	14 de outubro de 2023, 23h30
Local do usuário	Somente data	14 de outubro de 2023
Independente de fuso horário	Data e hora	15 de outubro de 2023, 7h30
Independente de fuso horário	Somente data	15 de outubro de 2023
Somente data	-	15 de outubro de 2023

Inserir valores em um aplicativo

Os usuários no fuso horário UTC-8 inserem October 14th, 2023, 11:30 pm em um aplicativo baseado em modelo. O valor é salvo no Dataverse como:

Comportamental	Formato	Valor salvo no Dataverse
Local do usuário	Data e hora	2023-10-15T07:30:00Z
Local do usuário	Somente data	2023-10-15T07:30:00Z
Independente de fuso horário	Data e hora	2023-10-14T23:30:00Z
Independente de fuso horário	Somente data	2023-10-14T23:30:00Z
Somente data	-	14-10-2023

Se o usuário inserir apenas a data October 14th, 2023, a parte da hora será considerada 0h.

Comportamental	Formato	Valor salvo no Dataverse
Local do usuário	Somente data	2023-10-14T08:00:00Z
Independente de fuso horário	Somente data	2023-10-14T00:00:00Z
Somente data	-	14-10-2023

Inserir valores inválidos em um aplicativo

Clientes diferentes têm maneiras diferentes de lidar com entradas inválidas. Por exemplo, no fuso horário do Pacífico, o horário de verão começou em 12 de março de 2023 às 2:00 da manhã, movendo o horário de avanço de uma hora para 3:00 da manhã. O horário entre 2h e 3h daquele dia não existe. Quando os usuários tentam inserir um valor nesse intervalo de tempo, os aplicativos poderão fazer o seguinte:

• Alterar para o horário válido anterior ou seguinte.
• Reverter para o último valor conhecido.
• Mostrar uma mensagem de erro.
• Não mostre horários entre 2h e 3h no seletor de horário, para que os usuários não possam selecioná-los em primeiro lugar.

Da mesma forma, clientes diferentes têm maneiras diferentes de lidar com intervalos de tempo repetidos. Por exemplo, no fuso horário do Pacífico, o horário de verão terminou em 5 de novembro de 2023 às 2:00 da manhã, movendo o tempo para trás uma hora para 1:00 am. O horário entre 1h e 2h daquele dia repete-se duas vezes. Um horário como 1h30 pode se referir a qualquer um dos fusos horários. Se você precisar mostrar ou inserir horários nesse intervalo de forma inequívoca, é melhor mudar temporariamente para um fuso horário que não use o horário de verão.

Obter valores brutos com a API Web

O Dataverse armazena 2023-10-15T07:30:00Z (ou 2023-10-15 para o comportamento Somente Data). Os usuários em todos os fusos horários obtêm esses valores com uma solicitação de API Web para o valor:

Comportamental	Formato	Valor bruto
Local do usuário	Data e hora	2023-10-15T07:30:00Z
Local do usuário	Somente data	2023-10-15T07:30:00Z
Independente de fuso horário	Data e hora	2023-10-15T07:30:00Z
Independente de fuso horário	Somente data	2023-10-15T07:30:00Z
Somente data	-	15-10-2023

Obter valores com API do cliente

Os usuários no fuso horário UTC-8 inserem October 14th, 2023, 11:30 pm em um aplicativo baseado em modelo. A API do cliente funciona como formContext.getAttribute(<column name>).getValue() e retorna o valor com ajustes de fuso horário aplicados:

Comportamental	Formato	Javascript dateValue.toUTCString()
Local do usuário	Data e hora	15-10-2023 7h30 (UTC)
Local do usuário	Somente data	15-10-2023 7h30 (UTC)

Para o comportamento Independente de fuso horário, o valor de data do JavaScript está no fuso horário do navegador:

Comportamental	Formato	Javascript dateValue.toString()
Independente de fuso horário	Data e hora	14-10-2023 23h30 (fuso horário do navegador)
Independente de fuso horário	Somente data	14-10-2023 23h30 (fuso horário do navegador)

Os valores de data do JavaScript sempre têm um componente de hora. É por isso que o comportamento Somente data tem um componente de hora de 0h:

Comportamental	Formato	Javascript dateValue.toString()
Somente data	-	15-10-2023 0h (fuso horário do navegador)

Nota

Os valores de data do JavaScript são afetados pelo fuso horário do navegador, que são provenientes das configurações do sistema operacional do dispositivo.

Para o comportamento local do usuário , interprete o resultado da API do Cliente como um valor UTC. Use Date.getUTCDate() ou Date.getUTCHours() para trabalhar com ele. Para obter o que o usuário vê, aplique getTimeZoneOffsetMinutes. Não use Date.getDate() ou Date.getHours() porque essas funções mostram o valor no fuso horário do navegador.

Para o comportamento Independente de fuso horário e Apenas Data, interprete o resultado da API do Cliente como um valor no fuso horário do navegador. Use Date.getDate() ou Date.getHours() para trabalhar com ele. Não use Date.getUTCDate() ou Date.getUTCHours() porque você não precisa se ajustar para nenhum fuso horário.

Alterar o comportamento do local do usuário

A menos que o publicador de uma solução gerenciada impeça a alteração do comportamento do formato local, você pode alterar o comportamento das colunas de data personalizadas existentes do usuário local para somente data ou fuso horário independente. Essa alteração só pode ser feita uma vez.

A alteração do comportamento da coluna afeta os valores da coluna adicionados ou modificados após a alteração do comportamento da coluna. Os valores de coluna existentes permanecem no banco de dados no formato de fuso horário UTC. Para alterar o comportamento dos valores de coluna existentes de UTC para Somente data, você pode precisar da ajuda de um desenvolvedor para converter o comportamento de valores de data e hora existentes no banco de dados.

Aviso

Antes de alterar o comportamento de uma coluna de data e hora existente, verifique todas as dependências da coluna, como regras de negócios, fluxos de trabalho, colunas calculadas ou colunas de rollup, para garantir que não haja problemas como resultado da alteração do comportamento. Depois de alterar o comportamento de uma coluna de data e hora, abra cada regra de negócios, fluxo de trabalho, coluna calculada e coluna cumulativa dependente da coluna alterada, examine as informações e salve-a para garantir que o comportamento e o valor da coluna de data e hora mais recentes sejam usados.

Alteração do comportamento durante a importação de uma solução

Ao importar uma solução que contenha uma coluna Data com Usuário local, você pode alterar o comportamento para Data somente ou Fuso horário independente.

Nota

Você só poderá alterar o comportamento de uma coluna gerenciada existente Somente data ou Data e hora se você for o editor. Para fazer alterações nesses campos, é necessário fazer uma atualização na solução que adicionou a coluna Somente data ou Data e hora. Mais informações: Atualizar ou fazer upgrade de uma solução

Bloqueio da alteração de comportamento

Ao distribuir uma coluna personalizada de data em uma solução gerenciada, você poderá evitar que os usuários da sua solução alterem o comportamento definindo a propriedade gerenciada CanChangeDateTimeBehavior como Falsa. Mais informações: Definir propriedades gerenciadas para colunas

Operadores de consulta de data e hora sem suporte para o comportamento Somente data

Os operadores de consulta relacionados a data e hora a seguir são inválidos para o comportamento Somente data. Um erro de exceção de operador inválido é lançado quando um destes operadores é usado na consulta.

• Anterior a X Minutos
• Anterior a X Horas
• Últimas X Horas
• Próximas X Horas

Consulte também

Solucionar problemas de data e hora em aplicativos baseados em modelo
Criar e editar colunas
Definir colunas calculadas para automatizar cálculos manuais
Propriedades gerenciadas da coluna
Propriedades gerenciadas
Blog: trabalhar com fusos horários no Dataverse
Configurar o comportamento e o formato da coluna de data e hora usando código