Техническая статья

Временные метки документов Excel в Delphi: FILETIME и UTC

Книга, сгенерированная в 09:30 на build-машине в Шанхае, открывается в Excel, и File > Info сообщает, что создана она в 17:30. Юнит-тест, породивший файл, прошёл: он присвоил 09:30, сохранил, переоткрыл и прочёл обратно ровно 09:30. Оба чтения берутся из одних и тех же байтов. Файл держит 09:30 с меткой UTC, Excel уважает метку и прибавляет восемь часов, а тест вообще не смотрел на метку. Метки времени документов в файлах Excel — UTC на диске, значение, с которым работает программа, — локальное время, и каждая конверсия между ними обязана использовать правила летнего времени той самой даты метки

Ошибка в один день, которую round-trip не видит

В файле .xls время создания и сохранения — значения FILETIME: 64-битный счёт тиков по 100 наносекунд с 1601-01-01 UTC ([MS-DTYP] §2.3.3). Delphi-TDateTime считает дни с 1899-12-30 — тот же серийный ноль, разобранный в статье о серийных датах Excel в Delphi и системах 1900 и 1904. Конверсия между ними требует одной константы — числа дней между двумя эпохами, — и это число 109205. Есть быстрый способ проверить его без календаря. Эпоха Unix — это 25569 как TDateTime и 134774 дня после эпохи FILETIME, а 25569 + 109205 = 134774

Посчитаете дни вручную и включите обе граничные даты — получите 109206. Писатель и читатель, построенные на той константе, идеально согласованы друг с другом. Каждая метка создания и сохранения уходит в файл на день позже и выходит обратно на день раньше, так что тест «сохранил и переоткрыл» видит ровно присвоенное значение, а Excel, или любой читатель с правильной эпохой, показывает завтра

const
  // дни от эпохи FILETIME (1601-01-01) до эпохи TDateTime (1899-12-30)
  // проверка: 25569 + 109205 = 134774, эпоха Unix в днях FILETIME
  FileTimeDayBias = 109205;

function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
  // Сначала округлите до целых миллисекунд, затем масштабируйте в тики по 100 нс.
  // Прямое масштабирование Double в тики превращает 04:00 в 03:59:59.9999
  Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
Хронология HotXLS: эпоха FILETIME 1601-01-01, эпоха TDateTime 1899-12-30 и эпоха Unix 1970 года, показывающая смещение в 109205 дней за UtcDateTimeToFileTimeTicks и то, как смещение 109206 записало бы каждую метку CreatedDate на день позже и прочитало её на день раньше
Набросок UtcDateTimeToFileTimeTicks держит смещение там, где неверная константа гасит сама себя, — симметричный тест «сохранил и переоткрыл» видит присвоенное значение, а панель Info в Excel показывает завтра

Комментарий про округление в том наброске тоже важен. Дробная часть TDateTime — двоичный Double, и прямое умножение на 864 000 000 000 тиков в сутки вталкивает ошибку представления в младшие разряды, так что метка ровно в 04:00 читается обратно как 03:59:59.9999 и отображается как 03:59. HotXLS сначала округляет до целых миллисекунд и лишь затем масштабирует в тики. Значения на ровный час выживают. Набросок нарочно берёт вход в UTC; шаг с часовым поясом дальше, и это более трудная половина

Какие property ID SummaryInformation держат даты?

Набор свойств \005SummaryInformation, определённый [MS-OLEPS], держит время создания под property ID $0C (PIDSI_CREATE_DTM), время последнего сохранения под $0D (PIDSI_LASTSAVE_DTM) и суммарное время редактирования под $0A (PIDSI_EDITTIME). ID сразу после метки сохранения, $0E, — это PIDSI_PAGECOUNT. Положите туда время сохранения, и у Excel не окажется даты сохранения для показа, зато будет свойство счётчика страниц, держащее FILETIME. HotXLS пишет метку сохранения под $0D, а читая файл, где $0D отсутствует, но $0E несёт VT_FILETIME, берёт то значение как время последнего сохранения. Строка или любой другой тип, сидящие под одним из этих ID в уродливом файле, пропускаются, а не прочитываются как дата неверно. Чтобы взглянуть на сырые потоки своими глазами, см. статью чтение составных файлов OLE2 в Delphi без COM IStorage

PIDSI_EDITTIME — белая ворона. Он типизирован VT_FILETIME, но держит длительность: сырой счёт прошедших тиков по 100 нс без всякой добавленной эпохи. Обращайтесь с ним как с остальными двумя — конвертируйте EditTimeMinutes / 1440 через арифметику эпох — и 125 минут редактирования превратятся в значение длиной лет в 299. HotXLS пишет сырой счёт тиков (минуты × 600 000 000). На Windows читатель вдобавок ловит кодировку в форме даты по размеру, ведь никакая настоящая сессия редактирования не тянется три века: у любого времени редактирования от 109206 дней и больше это смещение отнимается перед заполнением EditTimeMinutes

Карта property set 005SummaryInformation в HotXLS, где PIDSI_CREATE_DTM на $0C держит время создания, PIDSI_LASTSAVE_DTM на $0D — метку сохранения, PIDSI_EDITTIME на $0A — сырую длительность вместо даты, а $0E PIDSI_PAGECOUNT — слот счётчика страниц, который не должен держать метки времени
PIDSI_EDITTIME — ловушка внутри ловушки: типизирован как VT_FILETIME, но держит прошедшие тики без эпохи, поэтому обращение с ним как с датой превращает 125 минут редактирования примерно в 299 лет — это узнаёт проверка читателя по размеру

Задание меток .xls через TXLSWorkbook

TXLSWorkbook.CreatedDate и TXLSWorkbook.LastSavedDate принимают локальные TDateTime, и HotXLS конвертирует их в UTC FILETIME при сохранении книги. RevisionNumber и EditTimeMinutes сидят в том же потоке. Нулевое значение значит «не включай это свойство», и так же вычищаются все четыре: очистите их, и следующее сохранение не запишет ни одного. HotXLS не проставляет Now в LastSavedDate сам. Что присвоили, то и уйдёт в файл, и это правильное умолчание для библиотеки. Пакетное задание, перегенерирующее прошлогодние отчёты, обычно хочет прошлогодние даты, а автоматический штамп тихо перезаписал бы их

var
  Book: TXLSWorkbook;
begin
  Book := TXLSWorkbook.Create;
  try
    Book.Title := 'Q3 settlement';
    // значения API — локальное время; в файле лежат UTC FILETIME
    Book.CreatedDate := EncodeDate(2026, 1, 15) + EncodeTime(9, 30, 0, 0);
    Book.LastSavedDate := Now;     // пишется как присвоено, автоматически не проставляется
    Book.RevisionNumber := 7;
    Book.EditTimeMinutes := 125;   // длительность, хранится как сырые тики
    if Book.SaveAs('settlement.xls') <> 1 then
      raise Exception.Create('Save failed');
  finally
    Book.Free;
  end;
end;

Открытие файла заполняет те же четыре свойства обратно, конвертируя их в локальное время машины, которая читает. Сервис в UTC и десктоп в Токио отчитаются разными CreatedDate для одной книги, в девять часов разницы, и оба правы. Если двум системам надо сравнивать метки, конвертируйте в UTC на своей стороне перед сравнением или храните значение UTC рядом

Почему даты XLSX уезжают ровно на смещение часового пояса

Даты XLSX выходят смещёнными на зону, когда писатель штампует локальное время и подписывает его UTC. В docProps/core.xml dcterms:created и dcterms:modified — значения W3CDTF по модели core properties ECMA-376 Part 2, и обычная форма кончается Z. Отформатировать Now и дописать Z — очевидная строка кода. На машине в UTC+8 она превращает 09:30 в 09:30:00Z, и Excel на той же машине показывает 17:30 — вводный пример, буквально. Пользовательские свойства дат, хранимые как vt:filetime, следуют тому же правилу, как и двоичные FILETIME в .xls. HotXLS конвертирует на всех трёх путях перед записью: TXLSXWorkbook.Created, TXLSXWorkbook.Modified и даты, добавленные через CustomProperties.AddDate, локальны на стороне API и UTC с Z в файле

То, какая функция Windows делает конверсию, оказывается важнее, чем ожидают. LocalFileTimeToFileTime применяет смещение, действующее прямо сейчас. Сконвертируйте январскую метку в июле в любой зоне с летним временем — она уедет на час. HotXLS использует TzSpecificLocalTimeToSystemTime на записи и SystemTimeToTzSpecificLocalTime на чтении, и оба выбирают стандартное или летнее время по конвертируемой дате, а не по сегодняшнему дню. Незаданное нулевое значение проходит насквозь нетронутым в обе стороны, поэтому пустое свойство никогда не станет датой 30 декабря 1899, сдвинутой на пару часов

Пути конверсии из локального времени в UTC в HotXLS для январской метки 17:00 CET, сохраняемой в июле: LocalFileTimeToFileTime применяет сегодняшнее летнее смещение и попадает на час мимо, в 15:00Z, а TzSpecificLocalTimeToSystemTime берёт смещение с даты самой метки и пишет корректные 16:00Z
Смещение зоны принадлежит дате самой метки, а не текущим правилам машины: один Windows API выбирает верную сторону перехода на летнее время, другой тихо двигает январские метки, сконвертированные в июле, на час
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');
    // На машине с Central European Time core.xml теперь содержит
    // <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
    // (UTC+2 в июле), тогда как ApprovedOn записывается как 16:00Z (UTC+1 в январе)
  finally
    Book.Free;
  end;
end;

Вне Windows та же конверсия идёт через поддержку часовых поясов в RTL. В Delphi это TTimeZone.Local, и два неудобных часа в году получают там фиксированный ответ: локальное время внутри весеннего прыжка не существует, поэтому записывается неизменным, а осенний час, случающийся дважды, берётся как наступление по стандартному времени

Чтение меток W3CDTF, записанных другими генераторами

Excel пишет Z, другие генераторы не всегда, и читатель, проверяющий только Z на 20-й позиции, ошибается на двух частых формах. У 2026-07-01T01:30:00.5Z в пути дробная часть, а у 2026-07-01T09:30:00+08:00 явное смещение. Наивный парсер прочитает оба как локальное время без поправки. Читатель HotXLS для Created, Modified и пользовательских свойств с датами принимает дробные секунды любой длины, Z и смещения +hh:mm / -hh:mm; он конвертирует момент из данного смещения в UTC, затем в локальное время. Метка только с датой вроде 2026-07-01 читается как та дата в полночь, а метка, не разбирающаяся вовсе, возвращается как ноль

Единственный случай, который спецификации оставляют открытым, — время без всякого маркера зоны, например 2026-07-01T09:30:00. Профиль W3CDTF требует указателя зоны всякий раз, когда есть время, а ECMA-376 Part 2 правила для метки без него не даёт. HotXLS читает такое значение как локальное время, без изменений. Трактовать его как UTC было бы на бумаге столь же защитимо, но вероятнейший источник метки без зоны — инструмент, записавший локальное время и оставшийся без маркера, а сдвиг тех значений двигал бы каждую метку того инструмента на смещение зоны

Противоположную ошибку не спасёт ни один читатель. Метка, записанная как локальное время и носящая Z, выглядит точь-в-точь как корректная, поэтому HotXLS, Excel и любой другой читатель, следующий формату, сдвигают её на смещение зоны. Только кодировка edit-time и размещение в $0E в .xls имеют сигнатуру, которую читатель может распознать

Тестирование против байтов, которые ваш код не писал

Каждая ловушка выше проходит проверку «сохранил и переоткрыл», потому что симметричная ошибка невидима для симметричного теста. Эталон должен прийти откуда-то ещё. Для .xlsx распакуйте сохранённый файл и ассерьте литеральный текст dcterms:created; для .xls питоновский пакет olefile читает поток SummaryInformation независимо через get_metadata(), сообщает время редактирования в секундах и трактует $0E как счётчик страниц, так что обе ловушки .xls видны разом. Другое направление — книга, сохранённая самим Excel, прочитанная через API и сравнённая с тем, что показывает File > Info

uses
  System.SysUtils, System.DateUtils;

procedure CheckExcelReference;
var
  Book: TXLSXWorkbook;
  Expected: TDateTime;
begin
  // Значение, которое File > Info в Excel показывает для этого файла на тестовой машине
  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');
    // Ваша проверка, не API HotXLS: допускаем одну секунду на округление
    if Abs(Book.Created - Expected) > OneSecond then
      raise Exception.CreateFmt('Created reads as %s',
        [DateTimeToStr(Book.Created)]);
  finally
    Book.Free;
  end;
end;

Прогоните тот набор на машине с зоной, заметно отличной от UTC, с одной тестовой датой по каждую сторону перехода на летнее время. Build-агент, оставленный в UTC, полностью прячет ошибку смещения зоны, а единственная летняя тестовая дата прячет ошибку LocalFileTimeToFileTime; 20 января и 1 июля в Central European Time ловят обе

Системы учёта, поисковые индексы и журналы аудита сортируют по этим меткам, и дата, уехавшая на день или восемь часов, наносит больше вреда, чем отсутствующая, потому что её никто не заподозрит. С компонентом электронных таблиц HotXLS для Delphi константа эпохи, property ID и конверсия UTC с учётом летнего времени обрабатываются для обоих форматов, .xls и .xlsx, так что код приложения присваивает и читает обычные локальные TDateTime. По остальной части набора свойств, от заголовка и автора до пользовательских свойств, сопутствующая статья о задании свойств документов Excel в Delphi покрывает оставшиеся поля