Funções DateAdd, DateDiff e TimeZoneOffset

Função	Aplica-se a
DateAdd	Aplicativos de tela Colunas de fórmula do Dataverse Fluxos da área de trabalho Aplicativos baseados em modelo Power Platform CLI
DateDiff	Aplicativos de tela Colunas de fórmula do Dataverse Fluxos da área de trabalho Aplicativos baseados em modelo Power Platform CLI
TimeZoneOffset	Aplicativos de tela Fluxos da área de trabalho Aplicativos baseados em modelo 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( DateTime, 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 [, Units ] )

• 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( [ DateTime ] )

• 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
Text( DateAdd( Now(), 3 ), "dd-mm-yyyy hh:mm" )	Adiciona três dias (unidades padrão) à data e hora atuais.	"18-07-2013 13:02"
Text( DateAdd( Now(), 4, TimeUnit.Hours ), "dd-mm-yyyy hh:mm" )	Adiciona quatro horas à data e hora atuais.	"15-07-2013 17:02"
Text( DateAdd( Today(), 1, TimeUnit.Months ), "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"
Text( DateAdd( Now(), ‑30, TimeUnit.Minutes ), "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( Now(), DateValue("1/1/2014") )	Retorna a diferença entre as duas unidades nas unidades padrão de TimeUnit.Days	170
DateDiff( Now(), DateValue("1/1/2014"), TimeUnit.Months )	Retorna a diferença entre os dois valores em TimeUnit.Months	6
DateDiff( Now(), Today(), TimeUnit.Minutes )	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.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 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( Now(), TimeZoneOffset(), TimeUnit.Minutes )

O padrão de TimeZoneOffset é a hora atual; então não é necessário 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( StartTime, −TimeZoneOffset( StartTime ), TimeUnit.Minutes )

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.