Funções DateAdd, DateDiff e TimeZoneOffset

  • Artigo
Function Aplica-se ao
DataAdicionar Colunas Dataverse de fórmula de aplicativos de tela Fluxos de área de trabalho CLI de aplicativos Power Platform orientados por modelo
DataDiff Colunas Dataverse de fórmula de aplicativos de tela Fluxos de área de trabalho CLI de aplicativos Power Platform orientados por modelo
TimeZoneOffset Aplicativos de tela Fluxos de área de trabalho CLI de aplicativos Power Platform orientados por modelo

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,Adição [, Unidades ] )

  • DateTime - Obrigatório. Valor Data/hora a utilizar.
  • Adição - 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
Texto( DateAdd( Now(), 3 ),
"dd-mm-aaaa hh:mm" )		 Adiciona três dias (unidades predefinidas) à data e hora atuais. “18-07-2013 13:02”
Texto( 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"
Texto( 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( Agora(), DateValue("01/01/2014") ) Devolve a diferença entre as duas unidades nas unidades predefinidas de TimeUnit.Days 170
DateDiff( Now(), DateValue("01/01/2014"), TimeUnit.Months ) Devolve a diferença entre os dois valores em TimeUnit.Months 6
DateDiff( Agora(), Hoje(), 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( Agora(), TimeZoneOffset(), TimeUnit.Minutes )

TimeZoneOffset assume como padrão a hora atual, portanto, você não precisa passar um 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.