Funções DateAdd, DateDiff e TimeZoneOffset
| Função | Aplica-se a |
|---|---|
| DataAdicionar |  Aplicativos Canvas Dataverse colunas de fórmula Fluxos de desktop Aplicativos orientados a modelos Power Platform CLI |
| Diferença de data | Aplicativos Canvas Dataverse colunas de fórmula Fluxos de desktop Aplicativos orientados a modelos Power Platform CLI |
| Deslocamento de fuso horário | Aplicativos Canvas Fluxos de desktop Aplicativos orientados a modelos Power Platform CLI |
Adiciona ou encontra a diferença em valores de data/hora e converte entre hora local e UTC.
Descrição
A função DateAdd adiciona várias unidades a um valor de data/hora. O resultado é um novo valor de data/hora. Também é possível subtrair várias unidades de um valor de data/hora especificando um valor negativo.
A função DateDiff retorna a diferença entre dois valores de data/hora. O resultado é um número inteiro de unidades.
Para as duas funções, as unidades podem ser TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Por padrão, ambas as funções usam TimeUnit.Days como unidades.
A função TimeZoneOffset retorna o número de minutos entre a hora local do usuário e o UTC (Horário Coordenado Universal).
É possível usar o DateAdd com o TimeZoneOffset para converter entre a hora local do usuário e o UTC. A adição de TimeZoneOffset converterá a hora local em UTC e sua subtração (adicionando o negativo) converterá de UTC em hora local.
Consulte também tipos de dados Date, Time e DateTime e como trabalhar com datas e horas para obter mais informações.
Sintaxe
DateAdd( DataHora, Adição [, Unidades ] )
- DateTime - Obrigatório. Valor de data/hora no qual operar.
- Adição - Obrigatório. O número, em Unidades, a ser adicionado a DateTime.
- Unidades - Opcional. Os tipos de Unidades para adicionar: TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Se não for especificado, TimeUnit.Days será usado.
DateDiff( StartDateTime, EndDateTime [, Unidades ] )
- StartDateTime - Obrigatório. Valor de data/hora de início.
- EndDateTime - Obrigatório. Valor de data/hora de término.
- Unidades - Opcional. Os tipos de Unidades para subtrair: TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Se não for especificado, TimeUnit.Days será usado.
TimeZoneOffset( [ DataHora ] )
- DateTime - Opcional. O valor de data/hora para o qual a diferença será retornada. Por padrão, a data/hora atual é usada.
Exemplos
Em todos esses exemplos, suponha que a data e hora atual seja 15 de julho de 2013, 13:02.
DateAdd Simples
| Fórmula | Descrição | Resultado |
|---|---|---|
| Texto(DataAdd(Agora(), 3), "dd-mm-yyyy hh:mm" ) |
Adiciona três dias (unidades padrão) à data e hora atuais. | "18-07-2013 13:02" |
| Texto(DataAdd(Agora(), 4, TimeUnit.Hours), "dd-mm-yyyy hh:mm" ) |
Adiciona quatro horas à data e hora atuais. | "15-07-2013 17:02" |
| Texto(DataAdd(Hoje(), 1, TimeUnit.Meses), "dd-mm-yyyy hh:mm" ) |
Adiciona um mês à data atual, sem hora, pois Today não retorna um componente de tempo. | "15-08-2013 00:00" |
| Texto(DataAdd(Agora(), ‑30, TimeUnit.Minutos), "dd-mm-yyyy hh:mm" ) |
Subtrai 30 minutos da data e hora atuais. | "15-07-2013 12:32" |
DateDiff Simples
| Fórmula | Descrição | Resultado |
|---|---|---|
| DateDiff( Agora(), DateValue("1/1/2014") ) | Retorna a diferença entre as duas unidades nas unidades padrão de TimeUnit.Days | 170 |
| DateDiff( Agora(), DateValue("1/1/2014"), TimeUnit.Meses ) | Retorna a diferença entre os dois valores em TimeUnit.Months | 6 |
| DateDiff(Agora(), Hoje(), TimeUnit.Minutos) | Retorna a diferença entre a data/hora atual e apenas a data atual (sem hora) em minutos. Como Now é posterior a Today, o resultado será negativo. | -782 |
Diferença de datas com resultados fracionários
A função DateDiff retorna apenas um número inteiro das unidades sendo subtraídas e a precisão é fornecida na unidade especificada. Para calcular a diferença com uma precisão maior, use uma unidade menor e converta o resultado de forma adequada, como nos exemplos abaixo.
| Fórmula | Descrição | Resultado |
|---|---|---|
| DateDiff(TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Hours ) | Os minutos/segundos são ignorados, e a diferença é baseada no tempo até a hora. | 1 |
| DateDiff(TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Minutos )/60 | Os minutos são usados na diferença, e o resultado é dividido por 60 para ter a diferença em horas. | 0.5 |
| DateDiff(TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Seconds )/3600 | Os minutos e segundos são usados na diferença, e o resultado é dividido por 3600 para ter a diferença em horas. | 0.51 |
Conversão para o UTC
Para converter em UTC (Tempo Universal Coordenado), adicione TimeZoneOffset à hora determinada.
Por exemplo, imagine que a data e hora atual é 15 de julho de 2013, 13:02 no Horário de Verão do Pacífico (PDT, UTC-7). Para determinar a hora atual em UTC, use:
- DateAdd(Agora(), TimeZoneOffset(), TimeUnit.Minutos)
TimeZoneOffset assume como padrão a hora atual, então você não precisa passar um argumento para ele.
Para ver o resultado, use a função Text com o formato dd-mm-yyyy hh:mm, que retornará 15-07-2013 20:02.
Conversão do UTC
Para converter do UTC, subtraia o TimeZoneOffset (adicionando o negativo) para a hora determinada.
Por exemplo, imagine que a data e hora do UTC 15 de julho de 2013, 20:02 está armazenada em uma variável chamada StartTime. Para ajustar a hora para o fuso horário do usuário, utilize:
- DateAdd(HoraInício, −TimeZoneOffset(HoraInício), TimeUnit.Minutos)
Observe o sinal negativo antes de TimeZoneOffset para subtrair a diferença, em vez de adicioná-la.
Para ver o resultado, use a função Text com o formato dd-mm-yyyy hh:mm, o que resultará em 15-07-2013 13:02 se você estiver no Horário de Verão do Pacífico.