Funções DateAdd, DateDiff e TimeZoneOffset
Aplica-se a:
Aplicações de tela Colunas de fórmula do Dataverse Fluxos de ambiente de trabalho Aplicações condicionadas por modelo Power Platform CLI
Adiciona ou localiza a diferença nos valores de data/hora e converte entre a hora local e a UTC.
Descrição
A função DateAdd adiciona um número de unidades a um valor de data/hora. O resultado é um novo valor de data/hora. Também pode subtrair um número de unidades a um valor de data/hora ao especificar um valor negativo.
A função DateDiff devolve a diferença entre dois valores de data/hora. O resultado é um número inteiro de unidades.
Para ambas as funções, as unidades podem ser em TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Por predefinição, ambas as funções utilizam TimeUnit.Days como unidades.
A função TimeZoneOffset devolve o número de minutos entre a hora local do utilizador e a UTC (Hora Universal Coordenada).
Pode utilizar a função DateAdd com a TimeZoneOffset para converter entre a hora local do utilizador e a UTC (Hora Universal Coordenada). A adição da TimeZoneOffset converterá uma hora local em UTC e sua subtração (adição do negativo) converterá a UTC em hora local.
Consulte também Tipos de dados DateTime, Date e Time e como trabalhar com datas e horas para obter mais informações.
Sintaxe
DateAdd( DateTime, Addition [, Unidades ] )
- DateTime – Necessário. Valor Data/hora a utilizar.
- Addition – Obrigatório. Número, em Unidades, a adicionar à DateTime.
- Unidades – Opcional. O tipo de Unidades a adicionar: TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Se não for especificado, são utilizados TimeUnit.Days.
DateDiff( StartDateTime, EndDateTime [, Unidades ] )
- StartDateTime – Obrigatório. Valor de data/hora de início.
- EndDateTime – Obrigatório. Valor de data/hora de fim.
- Unidades – Opcional. O tipo de Unidades a subtrair: TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Se não for especificado, são utilizados TimeUnit.Days.
TimeZoneOffset( [ DateTime ] )
- DateTime – Opcional. Valor de data/hora cujo desvio deve ser devolvido. Por predefinição, é utilizada a data/hora atual.
Exemplos
Em todos estes exemplos, vamos assumir 15 de julho de 2013, 13:02 como data e hora atuais.
DateAdd simples
| Fórmula | Descrição | Resultado |
|---|---|---|
| Text( DateAdd( Now(), 3 ), "dd-mm-aaaa hh:mm" ) |
Adiciona três dias (unidades predefinidas) à data e hora atuais. | “18-07-2013 13:02” |
| Text( DateAdd( Now(), 4, TimeUnit.Hours ), "dd-mm-aaaa hh:mm" ) |
Adiciona quatro horas à data e hora atuais. | "15-07-2013 17:02" |
| Text( DateAdd( Today(), 1, TimeUnit.Months ), "dd-mm-aaaa hh:mm" ) |
Adiciona um mês à data atual, sem hora, já que Today não devolve nenhum componente de hora. | "15-08-2013 00:00" |
| Text( DateAdd( Now(), ‑30, TimeUnit.Minutes ), "dd-mm-aaaa hh:mm" ) |
Subtrai 30 minutos à data e hora atuais. | "15-07-2013 12:32" |
DateDiff simples
| Fórmula | Descrição | Resultado |
|---|---|---|
| DateDiff( Now(), DateValue("1/1/2014") ) | Devolve a diferença entre as duas unidades nas unidades predefinidas de TimeUnit.Days | 170 |
| DateDiff( Now(), DateValue("1/1/2014"), TimeUnit.Months ) | Devolve a diferença entre os dois valores em TimeUnit.Months | 6 |
| DateDiff( Now(), Today(), TimeUnit.Minutes ) | Devolve a diferença entre a data/hora atual e a data atual apenas (não hora) em minutos. Uma vez que Now é posterior a Today, o resultado será negativo. | -782 |
Diferença de datas com resultados fracionários
A função DateDiff apenas obtém um número inteiro das unidades a serem subtraídas e a precisão é dada na unidade especificada. Para calcular a diferença com uma maior precisão, utilize uma unidade mais pequena e converta o resultado adequadamente, 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, a diferença baseia-se no tempo até à hora. | 1 |
| DateDiff( TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Minutes )/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 os segundos são usados na diferença; o resultado é dividido por 3600 para ter a diferença em horas. | 0.51 |
Converter em UTC
Para converter em UTC (Hora Universal Coordenada), adicione TimeZoneOffset para o período de tempo especificado.
Por exemplo, imagine que a atual data e hora é 15 de julho de 2013, 13:02 na Hora de Verão do Pacífico (PDT, UTC-7). Para determinar a hora atual em UTC, utilize:
- DateAdd( Now(), TimeZoneOffset(), TimeUnit.Minutes )
TimeZoneOffset está predefinido para a hora atual, por isso não terá de o transmitir como argumento.
Para ver o resultado, utilize a função Text com o formato dd-mm-yyyy hh:mm, que irá devolver 15-07-2013 20:02.
Converter da UTC
Para converter da UTC, subtraia o TimeZoneOffset (ao adicionar o negativo) para o período de tempo especificado.
Por exemplo, imagine que a data e hora UTC 15 de julho de 2013, 20:02 é armazenada numa variável designada StartTime. Para ajustar a hora ao fuso horário do utilizador, utilize:
- DateAdd( StartTime, −TimeZoneOffset( StartTime ), TimeUnit.Minutes )
Tenha em atenção o sinal negativo antes do TimeZoneOffset para subtrair o desvio em vez de o adicionar.
Para ver o resultado, utilize a função Text com o formato dd-mm-yyyy hh:mm, o que irá resultar em 15-07-2013 13:02 se estiver na Hora de Verão do Pacífico.