Comportamento e formato da coluna de data e hora
No Microsoft Dataverse, você pode especificar como os valores de data e hora serão mostrados aos usuários e como eles serão ajustados para os fusos horários.
Duas opções estão disponíveis para as colunas de data e hora.
- Comportamento: se deseja ajustar os valores para os fusos horários.
- Formato: se deseja exibir a parte da hora do valor.
Comportamental
O Dataverse armazena todos os valores de data e hora no fuso horário UTC. Quando seu aplicativo exibe 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 estas opções de Comportamento.
- Local do Usuário: ajusta os valores para o fuso horário do usuário. Esse é o comportamento padrão. Você pode alterar isso uma vez para outro comportamento.
- Independente de fuso horário: nenhuma conversão de fuso horário.
- Somente data: nenhuma conversão de fuso horário. Diferente de Independente de fuso horário, a parte da hora não será armazenada.
O fuso horário do usuário é definido em opções pessoais, não o 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 têm uma parte de hora, a menos que seu comportamento seja 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.
Observação
Os usuários ainda poderão alterar a parte da hora se o Formato for Somente data. Por exemplo, com chamadas à API Web ou usando um controle que tenha a parte da hora. Isso é diferente do Comportamento Somente data, em que a parte da hora não é armazenada.
Diretrizes de uso
Use o comportamento Independente de fuso horário quando as informações de fuso horário não forem necessárias, como horários de check-in de hotel. Com essa seleção, os usuários em todos os fusos horários verão o mesmo valor de data e hora.
Use o comportamento Somente data quando as informações sobre a hora do dia e o fuso horário não são necessárias, como em aniversários ou em datas especiais. Com essa seleção, os usuários em todos os fusos horários verão o mesmo valor exato de data.
O comportamento Independente de fuso horário com o formato Somente data é praticamente igual ao comportamento 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 baseado em modelo, a parte da hora será definida automaticamente para meia-noite do 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). 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 2h, avançando uma hora para 3h. 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 2h, retrocedendo uma hora para 1h. 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). Usuários em todos os fusos horários obtêm isso com uma solicitação de API da 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) |
Observação
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, o resultado da API do Cliente deve ser interpretado como um valor UTC. Use Date.getUTCDate(), Date.getUTCHours() etc. para trabalhar com ele. Para obter o que o usuário vê, aplique getTimeZoneOffsetMinutes. Não use Date.getDate(), Date.getHours() etc. porque eles mostrarão o valor no fuso horário do navegador.
Para o comportamento Independente de fuso horário e Somente data, o resultado da API do Cliente deve ser interpretado como um valor no fuso horário do navegador. Use Date.getDate(), Date.getHours() etc. para trabalhar com ele. Não use Date.getUTCDate(), Date.getUTCHours() e assim por diante porque você não precisa ajustar nenhum fuso horário.
Alterar o comportamento do local do usuário
Exceto se o editor de uma solução gerenciada impedir isso, você poderá alterar o comportamento das colunas personalizadas de data de Local do usuário para Somente data ou Independente de fuso horário. 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 mudar o comportamento de uma coluna existente de data e hora, revise todas as dependências dela, como regras de negócios, fluxos de trabalho, colunas calculadas ou colunas cumulativas, para garantir que não haverá problemas como resultado da alteração no 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 contém uma coluna Data com o comportamento Local do usuário, você poderá alterar o comportamento para Somente data ou Independente de fuso horário.
Observação
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
Confira 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: Trabalhando com fusos horários no Dataverse
Configurar o comportamento e o formato da coluna de data e hora usando código
Observação
Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)
A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).