Fonctions DateAdd, DateDiff et TimeZoneOffset
S'applique à :
Applications Canvas Colonnes de formule Dataverse Flux de bureau Applications pilotées par modèle CLI Power Platform
Modifie une valeur de date/heure ou détermine la différence entre des valeurs de date/heure, et opère la conversion entre l’heure locale et l’heure UTC.
Description
La fonction DateAdd ajoute un nombre d’unités à une valeur de date/heure. Le résultat est une nouvelle valeur de date/heure. Vous pouvez également soustraire un nombre d’unités d’une valeur de date/heure en spécifiant une valeur négative.
La fonction DateDiff retourne la différence entre deux valeurs de date/heure. Le résultat est un nombre entier d’unités.
Pour les deux fonctions, les unités peuvent être TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Par défaut, les deux fonctions utilisent TimeUnit.Days en tant qu’unités.
La fonction TimeZoneOffset retourne le nombre de minutes entre l’heure locale et l’heure UTC (temps universel coordonné) de l’utilisateur.
Vous pouvez utiliser DateAdd avec TimeZoneOffset pour opérer une conversion entre l’heure locale et l’heure UTC (temps universel coordonné) de l’utilisateur. L’ajout de TimeZoneOffset convertit une heure locale en heure UTC, et sa soustraction (en ajoutant la valeur négative) convertit une heure UTC en heure locale.
Consultez également Types de données Date, Time et DateTime et Utilisation des dates et des heures pour plus d’informations.
Syntaxe
DateAdd( DateTime, Addition [, Units ] )
- DateHeure : obligatoire. Valeur de date/heure à utiliser.
- Addition : obligatoire. Nombre, exprimé en Unités, à ajouter à la valeur DateTime.
- Units : facultatif. Le type d’Unités à ajouter : TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Si les unités ne sont pas spécifiées, TimeUnit.Days est utilisée.
DateDiff( StartDateTime, EndDateTime [, Units ] )
- StartDateTime : obligatoire. Valeur de date/heure de début.
- EndDateTime : obligatoire. Valeur de date/heure de fin.
- Units : facultatif. Le type d’Unités à retirer : TimeUnit.Milliseconds, TimeUnit.Seconds, TimeUnit.Minutes, TimeUnit.Hours, TimeUnit.Days, TimeUnit.Months, TimeUnit.Quarters ou TimeUnit.Years. Si les unités ne sont pas spécifiées, TimeUnit.Days est utilisée.
TimeZoneOffset( [ DateTime ] )
- DateTime : facultatif. Valeur de date/heure pour laquelle retourner le décalage. Par défaut, la date/heure actuelle est utilisée.
Exemples
Dans tous ces exemples, supposons que la date et l’heure sont 15 juillet 2013, 13:02.
DateAdd simple
| Formule | Description | Résultat |
|---|---|---|
| Text( DateAdd( Now(), 3 ), "dd-mm-yyyy hh:mm" ) |
Ajoute trois jours (unités par défaut) à la valeur de date/heure actuelle. | "18-07-2013 13:02" |
| Text( DateAdd( Now(), 4, TimeUnit.Hours ), "dd-mm-yyyy hh:mm" ) |
Ajoute quatre heures à la valeur de date/heure actuelle. | "15-07-2013 17:02" |
| Text( DateAdd( Today(), 1, TimeUnit.Months ), "dd-mm-yyyy hh:mm" ) |
Ajoute un mois à la date actuelle, sans l’heure, car Today ne renvoie pas de composant d’heure. | "15-08-2013 00:00" |
| Text( DateAdd( Now(), ‑30, TimeUnit.Minutes ), "dd-mm-yyyy hh:mm" ) |
Soustrait 30 minutes de la valeur de date/heure actuelle. | "15-07-2013 12:32" |
DateDiff simple
| Formule | Description | Résultat |
|---|---|---|
| DateDiff( Now(), DateValue("1/1/2014") ) | Retourne la différence entre les deux unités, exprimée en unités par défaut de TimeUnit.Days | 170 |
| DateDiff( Now(), DateValue("1/1/2014"), TimeUnit.Months ) | Retourne la différence entre les deux valeurs de TimeUnit.Months | 6 |
| DateDiff( Now(), Today(), TimeUnit.Minutes ) | Retourne la différence entre la date/heure actuelle et la date actuelle (sans heure) en minutes. Étant donné que la valeur Now est postérieure à la valeur Today, le résultat est négatif. | -782 |
Différence de dates avec des résultats fractionnaires
La fonction DateDiff renvoie uniquement le nombre entier des unités soustraites et la précision est donnée dans l’unité spécifiée. Pour calculer la différence avec une précision plus élevée, utilisez une unité plus petite et convertissez le résultat de manière appropriée, comme dans les exemples ci-dessous.
| Formule | Description | Résultat |
|---|---|---|
| DateDiff( TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Hours ) | Les minutes/secondes sont ignorées, la différence est basée sur le temps jusqu’à l’heure. | 1 |
| DateDiff( TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Minutes )/60 | Les minutes sont utilisées dans la différence et le résultat est divisé par 60 pour avoir la différence en heures. | 0.5 |
| DateDiff( TimeValue("09:45:00"), TimeValue("10:15:36"), TimeUnit.Seconds )/3600 | Les minutes et les secondes sont utilisées dans la différence et le résultat est divisé par 3600 pour avoir la différence en heures. | 0.51 |
Conversion en heure UTC
Pour convertir au format UTC (temps universel coordonné), ajoutez la valeur TimeZoneOffset pour l’heure indiquée.
Par exemple, imaginez que la valeur de date/heure soit 15 juillet 2013, 13:02 en heure d’été du Pacifique (UTC-7). Pour déterminer l’heure en heure UTC, utilisez la formule :
- DateAdd( Now(), TimeZoneOffset(), TimeUnit.Minutes )
TimeZoneOffset indiquant par défaut l’heure actuelle, vous n’avez pas besoin de le passer en tant qu’argument.
Pour afficher le résultat, utilisez la fonction Text avec le format dd-mm-yyyy hh:mm, qui retournera 15-07-2013 20:02.
Conversion de l’heure UTC
Pour convertir l’heure UTC, soustrayez TimeZoneOffset (en ajoutant le signe négatif) de l’heure indiquée.
Par exemple, imaginez que la valeur de date/heure UTC 15 juillet 2013, 20:02 est stockée dans une variable nommée StartTime. Pour régler l’heure en fonction du fuseau horaire de l’utilisateur, utilisez la formule :
- DateAdd( StartTime, −TimeZoneOffset( StartTime ), TimeUnit.Minutes )
Notez le signe négatif devant TimeZoneOffset, qui indique de soustraire le décalage au lieu de l’ajouter.
Pour afficher le résultat, utilisez la fonction Text avec le format dd-mm-yyyy hh:mm, qui retourne 15-07-2013 13:02 si vous êtes dans le fuseau horaire Pacifique (heure d’été).