Compartilhar via


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.