Article technique

Horodatages Excel en Delphi : FILETIME, UTC et DST

Un classeur généré à 09:30 sur une machine de build à Shanghai s'ouvre dans Excel, et Fichier > Infos signale une création à 17:30. Le test unitaire qui a produit le fichier est passé : il a affecté 09:30, enregistré, rouvert et relu 09:30 directement. Les deux lectures viennent des mêmes octets. Le fichier porte 09:30 marqué UTC, Excel honore la marque et ajoute huit heures, et le test n'a jamais regardé la marque. Les horodatages de documents dans les fichiers Excel sont en UTC sur disque, la valeur avec laquelle un programme travaille est en heure locale, et chaque conversion entre les deux doit employer les règles d'heure d'été de la date propre de l'horodatage

L'erreur d'un jour qu'un aller-retour ne peut pas voir

Dans un fichier .xls, les heures de création et de sauvegarde sont des valeurs FILETIME : un comptage 64 bits de pas de 100 nanosecondes depuis le 1601-01-01 UTC ([MS-DTYP] §2.3.3). Un TDateTime Delphi compte les jours depuis le 1899-12-30, la même origine sérielle que couvre les numéros de série de dates Excel en Delphi et les systèmes 1900 vs 1904. Convertir entre les deux demande une constante, le nombre de jours entre les deux époques, et ce nombre est 109205. Il y a un moyen rapide de le vérifier sans calendrier. L'époque Unix vaut 25569 comme TDateTime et 134774 jours après l'époque FILETIME, et 25569 + 109205 = 134774

Comptez les jours à la main en incluant les deux dates de fin, et vous obtenez 109206. Un écrivain et un lecteur bâtis sur cette constante se comprennent parfaitement. Chaque horodatage de création et de sauvegarde entre dans le fichier un jour trop tard et ressort un jour trop tôt, si bien qu'un test de sauvegarde-réouverture voit exactement la valeur affectée, tandis qu'Excel, ou tout lecteur qui emploie la bonne époque, affiche demain

const
  // jours de l'époque FILETIME (1601-01-01) à l'époque TDateTime (1899-12-30)
  // vérification : 25569 + 109205 = 134774, l'époque Unix en jours FILETIME
  FileTimeDayBias = 109205;

function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
  // Arrondir d'abord en millisecondes entières, puis passer aux pas de 100 ns.
  // Passer le Double directement aux pas transforme 04:00 en 03:59:59.9999
  Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
Chronologie HotXLS de l'époque FILETIME 1601-01-01, de l'époque TDateTime 1899-12-30 et de l'époque Unix 1970, montrant le biais de 109205 jours derrière UtcDateTimeToFileTimeTicks et comment un biais de 109206 écrirait chaque horodatage CreatedDate un jour trop tard et le lirait un jour trop tôt
Le croquis UtcDateTimeToFileTimeTicks garde le biais là où une constante fausse s'annule elle-même — un test symétrique de sauvegarde-réouverture voit la valeur qu'il a affectée tandis que le volet Informations d'Excel affiche demain

Le commentaire d'arrondi de ce croquis compte aussi. Une fraction de TDateTime est un Double binaire, et la multiplier directement par 864 000 000 000 pas par jour pousse l'erreur de représentation dans les chiffres du bas, si bien qu'un horodatage à exactement 04:00 se relit en 03:59:59.9999 et s'affiche en 03:59. HotXLS arrondit d'abord en millisecondes entières et seulement ensuite passe aux pas. Les valeurs à l'heure ronde survivent. Le croquis prend une entrée UTC à dessein ; l'étape de fuseau horaire vient plus tard et c'est la moitié la plus difficile

Quels ID de propriétés SummaryInformation portent les dates ?

Le jeu de propriétés \005SummaryInformation défini par [MS-OLEPS] garde l'heure de création sous l'ID de propriété $0C (PIDSI_CREATE_DTM), l'heure de dernière sauvegarde sous $0D (PIDSI_LASTSAVE_DTM) et le temps d'édition total sous $0A (PIDSI_EDITTIME). L'ID juste après l'horodatage de sauvegarde, $0E, est PIDSI_PAGECOUNT. Mettez-y une heure de sauvegarde et Excel n'a plus de date de sauvegarde à afficher, plus une propriété de comptage de pages portant un FILETIME. HotXLS écrit l'horodatage de sauvegarde sous $0D, et quand il lit un fichier où $0D est absent mais $0E porte un VT_FILETIME, il prend cette valeur comme heure de dernière sauvegarde. Une chaîne ou tout autre type garé sous l'un de ces IDs dans un fichier mal formé est sauté plutôt que mal lu comme une date. Pour voir les flux bruts eux-mêmes, voyez la lecture de fichiers composés OLE2 en Delphi sans COM IStorage

PIDSI_EDITTIME est l'intrus. Il est typé VT_FILETIME mais porte une durée : le compte brut des pas de 100 ns écoulés, sans époque ajoutée. Traitez-le comme les deux autres, convertissez EditTimeMinutes / 1440 par la math d'époque, et 125 minutes d'édition se transforment en une valeur d'environ 299 ans. HotXLS écrit le compte de pas brut (minutes × 600 000 000). Sous Windows, le lecteur attrape aussi le codage en forme de date à sa taille, comme aucune vraie session d'édition ne s'étend sur trois siècles : tout temps d'édition de 109206 jours ou plus se voit retrancher cet offset avant que EditTimeMinutes soit rempli

Carte HotXLS du jeu de propriétés 005SummaryInformation où PIDSI_CREATE_DTM en $0C porte l'heure de création, PIDSI_LASTSAVE_DTM en $0D l'horodatage de sauvegarde, PIDSI_EDITTIME en $0A une durée brute plutôt qu'une date, et $0E PIDSI_PAGECOUNT, un emplacement de comptage de pages qui ne doit pas porter d'horodatages
PIDSI_EDITTIME est le piège dans le piège — typé VT_FILETIME mais portant des pas écoulés sans époque, si bien que le traiter comme une date transforme 125 minutes d'édition en environ 299 ans, ce qu'un contrôle de lecture basé sur la taille sait reconnaître

Régler les horodatages .xls avec TXLSWorkbook

TXLSWorkbook.CreatedDate et TXLSWorkbook.LastSavedDate prennent des valeurs TDateTime locales, et HotXLS les convertit en FILETIME UTC quand le classeur est enregistré. RevisionNumber et EditTimeMinutes logent dans le même flux. Une valeur zéro signifie « laisse cette propriété de côté », ce qui est aussi la façon de supprimer les quatre : videz-les et le prochain enregistrement n'en écrit aucun. HotXLS ne tamponne pas Now dans LastSavedDate de lui-même. Ce que vous affectez est ce qui entre dans le fichier, et c'est le bon défaut pour une bibliothèque. Un traitement par lots qui régénère les rapports de l'an dernier veut d'habitude les dates de l'an dernier, et un tampon automatique les écraserait en silence

var
  Book: TXLSWorkbook;
begin
  Book := TXLSWorkbook.Create;
  try
    Book.Title := 'Q3 settlement';
    // les valeurs de l'API sont en heure locale ; le fichier stocke des FILETIME UTC
    Book.CreatedDate := EncodeDate(2026, 1, 15) + EncodeTime(9, 30, 0, 0);
    Book.LastSavedDate := Now;     // écrit tel qu'affecté, jamais tamponné automatiquement
    Book.RevisionNumber := 7;
    Book.EditTimeMinutes := 125;   // une durée, stockée en pas bruts
    if Book.SaveAs('settlement.xls') <> 1 then
      raise Exception.Create('Save failed');
  finally
    Book.Free;
  end;
end;

Ouvrir un fichier remplit les quatre propriétés dans l'autre sens, converties à l'heure locale de la machine qui lit. Un service tournant en UTC et un poste de bureau à Tokyo rapporteront des valeurs CreatedDate différentes pour le même classeur, séparées de neuf heures, et toutes deux correctes. Si deux systèmes doivent comparer des horodatages, convertissez en UTC de votre côté avant la comparaison, ou stockez la valeur UTC à côté

Pourquoi les dates XLSX sont-elles décalées d'exactement l'offset de fuseau ?

Les dates XLSX sortent décalées de l'offset de fuseau quand un écrivain tamponne l'heure locale en l'étiquetant UTC. Dans docProps/core.xml, dcterms:created et dcterms:modified sont des valeurs W3CDTF sous le modèle de propriétés principales d'ECMA-376 Partie 2, et la forme habituelle se termine par un Z. Formater Now et ajouter un Z est la ligne de code évidente. Sur une machine en UTC+8, cela transforme 09:30 en 09:30:00Z, et Excel sur cette même machine affiche 17:30 — l'exemple d'ouverture, exactement. Les propriétés de dates personnalisées stockées en vt:filetime suivent la même règle, tout comme les FILETIME binaires des .xls. HotXLS convertit sur les trois chemins avant d'écrire : TXLSXWorkbook.Created, TXLSXWorkbook.Modified et les dates ajoutées via CustomProperties.AddDate sont locales côté API et UTC avec un Z dans le fichier

Quelle fonction Windows fait la conversion s'avère compter plus qu'on ne l'attend. LocalFileTimeToFileTime applique l'offset en vigueur à l'instant présent. Convertissez un horodatage de janvier en juillet dans n'importe quelle zone à heure d'été et il atterrit avec une heure d'écart. HotXLS emploie TzSpecificLocalTimeToSystemTime à l'écriture et SystemTimeToTzSpecificLocalTime à la lecture, et toutes deux choisissent heure standard ou heure d'été d'après la date convertie, pas d'après aujourd'hui. Une valeur non fixée de zéro passe intacte dans les deux sens, si bien qu'une propriété vide ne devient jamais une date du 30 décembre 1899 décalée de quelques heures

Chemins de conversion local vers UTC de HotXLS pour un horodatage de janvier 17:00 CET sauvegardé en juillet : LocalFileTimeToFileTime applique l'offset d'été d'aujourd'hui et atterrit avec une heure d'écart à 15:00Z, tandis que TzSpecificLocalTimeToSystemTime prend l'offset de la date propre de l'horodatage et écrit le bon 16:00Z
L'offset de fuseau appartient à la date propre de l'horodatage, pas aux règles actuelles de la machine — une API Windows choisit le bon côté d'un changement d'heure d'été, l'autre décale tranquillement d'une heure les horodatages de janvier convertis en juillet
var
  Book: TXLSXWorkbook;
begin
  Book := TXLSXWorkbook.Create;
  try
    if Book.Open('report-template.xlsx') <> 1 then
      raise Exception.Create('Template not available');
    Book.Created := EncodeDate(2026, 7, 1) + EncodeTime(9, 30, 0, 0);
    Book.Modified := Now;
    Book.CustomProperties.AddDate('ApprovedOn',
      EncodeDate(2026, 1, 20) + EncodeTime(17, 0, 0, 0));
    if Book.SaveAs('report.xlsx') <> 1 then
      raise Exception.Create('Save failed');
    // Sur une machine réglée sur l'heure d'Europe centrale, core.xml détient désormais
    // <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
    // (UTC+2 en juillet), tandis que ApprovedOn est écrit 16:00Z (UTC+1 en janvier)
  finally
    Book.Free;
  end;
end;

Hors de Windows, la même conversion passe par la gestion des fuseaux de la RTL. Dans Delphi, c'est TTimeZone.Local, et les deux heures gênantes de l'année y reçoivent une réponse fixe : une heure locale à l'intérieur du trou du passage à l'heure d'été n'existe pas, donc elle est écrite inchangée, et une heure d'automne qui arrive deux fois est prise comme l'occurrence en heure standard

Lire des horodatages W3CDTF écrits par d'autres générateurs

Excel écrit un Z, d'autres générateurs ne le font pas toujours, et un lecteur qui ne vérifie qu'un Z au caractère 20 se trompe sur deux formes courantes. 2026-07-01T01:30:00.5Z a une fraction en travers, et 2026-07-01T09:30:00+08:00 a un offset explicite. Un analyseur naïf lit les deux comme heure locale sans ajustement. Le lecteur HotXLS de Created, Modified et des propriétés personnalisées de valeur date accepte des secondes fractionnaires de toute longueur, le Z, et les offsets +hh:mm / -hh:mm ; il convertit l'instant depuis l'offset donné vers UTC puis vers l'heure locale. Un horodatage date seule tel que 2026-07-01 se lit comme cette date à minuit, et un horodatage qui ne s'analyse pas du tout revient en zéro

Le seul cas que les spécifications laissent ouvert est une heure sans marqueur de zone du tout, telle que 2026-07-01T09:30:00. Le profil W3CDTF exige un désignateur de zone dès qu'une heure est présente, et ECMA-376 Partie 2 ne donne aucune règle pour un horodatage qui l'omet. HotXLS lit une telle valeur comme heure locale, inchangée. La traiter comme UTC aurait été tout aussi défendable sur le papier, mais la source la plus probable d'un horodatage sans zone est un outil qui a écrit l'heure locale en oubliant la marque, et décaler ces valeurs déplacerait tous les horodatages de cet outil de l'offset de fuseau

Aucun lecteur ne peut sauver l'erreur inverse. Un horodatage écrit en heure locale et portant un Z ressemble exactement à un correct, si bien que HotXLS, Excel et tout autre lecteur qui suit le format le décalent de l'offset de fuseau. Seuls le codage du temps d'édition et le placement en $0E dans le .xls ont une signature qu'un lecteur peut détecter

Tester contre des octets que votre code n'a pas écrits

Chaque piège ci-dessus passe un contrôle de sauvegarde puis réouverture, car une erreur symétrique est invisible à un test symétrique. La référence doit venir d'ailleurs. Pour le .xlsx, dézippez le fichier enregistré et assertez le texte littéral de dcterms:created ; pour le .xls, le paquet olefile de Python lit le flux SummaryInformation indépendamment avec get_metadata(), rapporte le temps d'édition en secondes et traite $0E comme un comptage de pages, ce qui rend les deux pièges du .xls visibles d'un coup. L'autre direction est un classeur enregistré par Excel lui-même, lu via l'API et comparé à ce que Fichier > Infos affiche

uses
  System.SysUtils, System.DateUtils;

procedure CheckExcelReference;
var
  Book: TXLSXWorkbook;
  Expected: TDateTime;
begin
  // La valeur que Fichier > Infos d'Excel affiche pour ce fichier sur la machine de test
  Expected := EncodeDate(2026, 1, 20) + EncodeTime(17, 0, 0, 0);
  Book := TXLSXWorkbook.Create;
  try
    if Book.Open('excel-saved-reference.xlsx') <> 1 then
      raise Exception.Create('Reference file missing');
    // Votre propre contrôle, pas une API HotXLS : accordez une seconde pour l'arrondi
    if Abs(Book.Created - Expected) > OneSecond then
      raise Exception.CreateFmt('Created reads as %s',
        [DateTimeToStr(Book.Created)]);
  finally
    Book.Free;
  end;
end;

Lancez cette suite sur une machine réglée sur une zone bien loin d'UTC, avec une date de test de chaque côté d'un changement d'heure d'été. Un agent de build laissé en UTC cache complètement l'erreur d'offset de fuseau, et une seule date de test estivale cache celle de LocalFileTimeToFileTime ; le 20 janvier et le 1er juillet en heure d'Europe centrale attrapent les deux

Les systèmes de gestion de dossiers, les index de recherche et les pistes d'audit trient d'après ces horodatages, et une date fausse d'un jour ou de huit heures fait plus de dégâts qu'une date manquante, car personne ne la conteste. Avec le composant tableur HotXLS Delphi, la constante d'époque, les ID de propriétés et la conversion UTC consciente de l'heure d'été sont gérés pour le .xls comme pour le .xlsx, si bien que le code applicatif affecte et lit d'ordinaires valeurs TDateTime locales. Pour le reste du jeu de propriétés, du titre et de l'auteur aux propriétés personnalisées, l'article compagne sur la définition des propriétés de documents Excel en Delphi couvre les champs restants