Skoroszyt wygenerowany o 09:30 na maszynie buildowej w Szanghaju otwiera się w Excelu, a File > Info raportuje, że powstał o 17:30. Test jednostkowy, który wyprodukował ten plik, przeszedł: przypisał 09:30, zapisał, otworzył ponownie i prosto z powrotem odczytał 09:30. Oba odczyty pochodzą z tych samych bajtów. Plik trzyma 09:30 oznaczone jako UTC, Excel honoruje ten znacznik i dodaje osiem godzin, a test nigdy nie spojrzał na oznaczenie. Znaczniki czasu dokumentów w plikach Excel są na dysku w UTC, wartość, z którą pracuje program, jest czasem lokalnym, a każda konwersja między nimi musi używać reguł czasu letniego obowiązujących w dniu samego znacznika
Błąd o jeden dzień, którego round-trip nie widzi
W pliku .xls czasy utworzenia i zapisu to wartości FILETIME: 64-bitowy licznik tików po 100 nanosekund od 1601-01-01 UTC ([MS-DTYP] §2.3.3). Delphi TDateTime liczy dni od 1899-12-30 — tego samego początku serialu, który opisuje artykuł o serialach dat Excela w Delphi i systemach 1900 vs 1904. Konwersja między nimi potrzebuje jednej stałej, liczby dni między epokami, i ta liczba to 109205. Jest szybki sposób, by to sprawdzić bez kalendarza. Epoka Unixa to 25569 jako TDateTime i 134774 dni po epoce FILETIME, a 25569 + 109205 = 134774
Policz dni ręcznie i uwzględnij obie daty brzegowe, a wyjdzie 109206. Zapisujący i czytnik zbudowane na tej stałej zgadzają się ze sobą perfekcyjnie. Każdy znacznik utworzenia i zapisu wchodzi do pliku dzień za późno i wychodzi dzień za wcześnie, więc test zapisz-i-otwórz widzi dokładnie wartość, którą przypisał, podczas gdy Excel albo jakikolwiek czytnik z poprawną epoką pokazuje jutro
const
// dni od epoki FILETIME (1601-01-01) do epoki TDateTime (1899-12-30)
// sprawdź: 25569 + 109205 = 134774, epoka Unixa w dniach FILETIME
FileTimeDayBias = 109205;
function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
// Najpierw zaokrąglij do pełnych milisekund, potem przeskaluj do tików po 100 ns.
// Bezpośrednie skalowanie Double do tików zamienia 04:00 w 03:59:59.9999
Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
Komentarz o zaokrąglaniu w tym szkicu też ma znaczenie. Ułamek TDateTime to binarny Double i przemnożenie go wprost przez 864 000 000 000 tików na dzień wpycha błąd reprezentacji w najniższe cyfry, więc znacznik dokładnie 04:00 czyta się z powrotem jako 03:59:59.9999 i wyświetla jako 03:59. HotXLS najpierw zaokrągla do pełnych milisekund i dopiero potem skaluje do tików. Wartości równo-na-godzinę przeżywają. Szkic celowo bierze wejście UTC; krok strefy czasowej przychodzi później i jest trudniejszą połową
Które identyfikatory właściwości SummaryInformation trzymają daty?
Zestaw właściwości \005SummaryInformation zdefiniowany przez [MS-OLEPS] trzyma czas utworzenia pod identyfikatorem właściwości $0C (PIDSI_CREATE_DTM), czas ostatniego zapisu pod $0D (PIDSI_LASTSAVE_DTM), a łączny czas edycji pod $0A (PIDSI_EDITTIME). ID zaraz za znacznikiem zapisu, $0E, to PIDSI_PAGECOUNT. Wstaw tam czas zapisu, a Excel nie ma daty zapisu do pokazania, za to ma właściwość liczby stron trzymającą FILETIME. HotXLS zapisuje znacznik zapisu pod $0D, a gdy czyta plik, w którym $0D nie istnieje, ale $0E niesie VT_FILETIME, bierze tę wartość jako czas ostatniego zapisu. Łańcuch albo jakikolwiek inny typ siedzący pod jednym z tych ID w zniekształconym pliku jest pomijany, zamiast być odczytanym błędnie jako data. Spojrzenie na same surowe strumienie to czytanie plików złożonych OLE2 w Delphi bez COM IStorage
PIDSI_EDITTIME jest dziwakiem. Ma typ VT_FILETIME, a trzyma czas trwania: surową liczbę upływających tików po 100 ns, bez dodanej epoki. Potraktuj go jak pozostałe dwie, przepuść EditTimeMinutes / 1440 przez arytmetykę epok, a 125 minut edycji zamieni się w wartość liczącą około 299 lat. HotXLS zapisuje czystą liczbę tików (minuty × 600 000 000). Po stronie Windows czytnik dodatkowo łapie kodowanie w kształcie daty po rozmiarze, bo żadna prawdziwa sesja edycji nie rozciąga się na trzy stulecia: każdemu czasowi edycji wynoszącemu 109206 dni albo więcej jest odejmowane tamto przesunięcie, zanim wypełnione zostanie EditTimeMinutes
Ustawianie znaczników .xls przez TXLSWorkbook
TXLSWorkbook.CreatedDate i TXLSWorkbook.LastSavedDate biorą lokalne wartości TDateTime, a HotXLS konwertuje je na UTC FILETIME przy zapisie skoroszytu. RevisionNumber i EditTimeMinutes siedzą w tym samym strumieniu. Wartość zero znaczy "pomiń tę właściwość" — tak samo zdejmuje się wszystkie cztery: wyczyść je, a następny zapis nie napisze żadnej. HotXLS nie stempluje sam z siebie Now do LastSavedDate. Co przypiszesz, to idzie do pliku, i to jest właściwy domyślny stan dla biblioteki. Zadanie wsadowe, które regeneruje raporty sprzed roku, zwykle chce dat sprzed roku, a automatyczne stemplowanie cicho by je nadpisało
var
Book: TXLSWorkbook;
begin
Book := TXLSWorkbook.Create;
try
Book.Title := 'Q3 settlement';
// wartości API to czas lokalny; plik trzyma UTC FILETIME
Book.CreatedDate := EncodeDate(2026, 1, 15) + EncodeTime(9, 30, 0, 0);
Book.LastSavedDate := Now; // zapisywane tak, jak przypisano, nigdy automatycznie stemplowane
Book.RevisionNumber := 7;
Book.EditTimeMinutes := 125; // czas trwania, zapisany jako surowe tiki
if Book.SaveAs('settlement.xls') <> 1 then
raise Exception.Create('Save failed');
finally
Book.Free;
end;
end;
Otwarcie pliku wypełnia te same cztery właściwości z powrotem, przeliczone na czas lokalny maszyny, która czyta. Serwis biegnący w UTC i biurko w Tokio zgłoszą różne wartości CreatedDate dla tego samego skoroszytu, dziewięć godzin od siebie, i obie są poprawne. Jeśli dwa systemy muszą porównywać znaczniki, przelicz na UTC po swojej stronie przed porównaniem albo przechowuj wartość UTC obok
Dlaczego daty XLSX mylą się dokładnie o przesunięcie strefy?
Daty XLSX wychodzą przesunięte o strefę, gdy zapisujący stempluje czas lokalny i podpisuje go jako UTC. W docProps/core.xml dcterms:created i dcterms:modified to wartości W3CDTF z modelu właściwości podstawowych ECMA-376 Part 2, a zwykła postać kończy się Z. Sformatowanie Now i doklejenie Z to oczywisty jednolinijkowiec. Na maszynie w UTC+8 zamienia 09:30 w 09:30:00Z, a Excel na tej samej maszynie pokazuje 17:30 — dokładnie przykład otwierający. Właściwości dat niestandardowych zapisywane jako vt:filetime podlegają tej samej regule, podobnie jak binarne FILETIME w .xls. HotXLS konwertuje na wszystkich trzech ścieżkach przed zapisem: TXLSXWorkbook.Created, TXLSXWorkbook.Modified i daty dodawane przez CustomProperties.AddDate są lokalne po stronie API i UTC z Z w pliku
Która funkcja Windows robi konwersję, okazuje się ważniejsza, niż ludzie oczekują. LocalFileTimeToFileTime stosuje przesunięcie obowiązujące w tej chwili. Przelicz styczniowy znacznik w lipcu w dowolnej strefie z czasem letnim, a wyląduje z błędem godziny. HotXLS używa TzSpecificLocalTimeToSystemTime przy zapisie i SystemTimeToTzSpecificLocalTime przy odczycie, a oba wybierają czas standardowy albo letni na podstawie konwertowanej daty, nie dzisiejszej. Nieustawiona wartość zero przechodzi nietknięta w obu kierunkach, więc pusta właściwość nigdy nie zamienia się w datę 30 grudnia 1899 przesuniętą o kilka godzin
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');
// Na maszynie ustawionej na czas środkowoeuropejski core.xml trzyma teraz
// <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
// (UTC+2 w lipcu), a ApprovedOn zapisuje się jako 16:00Z (UTC+1 w styczniu)
finally
Book.Free;
end;
end;
Poza Windows ta sama konwersja idzie przez obsługę stref czasowych RTL. W Delphi to TTimeZone.Local, i dwie niewygodne godziny w roku dostają tam ustaloną odpowiedź: lokalny czas wewnątrz wiosennej luki nie istnieje, więc jest zapisywany bez zmian, a jesienna godzina występująca dwa razy jest brana jako wystąpienie standardowe
Czytanie znaczników W3CDTF zapisanych przez inne generatory
Excel pisze Z, inne generatory nie zawsze, a czytnik sprawdzający wyłącznie Z na dwudziestym znaku myli się w dwóch częstych postaciach. 2026-07-01T01:30:00.5Z ma ułamek w drodze, a 2026-07-01T09:30:00+08:00 jawne przesunięcie. Naiwny parser czyta oba jako czas lokalny bez korekty. Czytnik HotXLS dla Created, Modified i właściwości niestandardowych z wartościami dat przyjmuje ułamkowe sekundy dowolnej długości, Z oraz przesunięcia +hh:mm / -hh:mm; przelicza chwilę z podanego przesunięcia na UTC, a potem na czas lokalny. Znacznik tylko z datą, jak 2026-07-01, czyta się jako ta data o północy, a znacznik, który w ogóle się nie parsuje, wraca jako zero
Jeden przypadek specyfikacje zostawiają otwarty: czas bez żadnego oznaczenia strefy, jak 2026-07-01T09:30:00. Profil W3CDTF wymaga oznaczenia strefy, ilekroć czas jest obecny, a ECMA-376 Part 2 nie daje reguły dla znacznika, który go pomija. HotXLS czyta taką wartość jako czas lokalny, bez zmian. Potraktowanie jej jako UTC byłoby na papierze równie uzasadnione, ale najbardziej prawdopodobnym źródłem znacznika bez strefy jest narzędzie, które zapisało czas lokalny i zostawiło marker, a przesuwanie takich wartości przesunęłoby każdy znacznik czasu tego narzędzia o przesunięcie strefy
Żaden czytnik nie uratuje błędu w drugą stronę. Znacznik zapisany jako czas lokalny, ale noszący Z, wygląda dokładnie jak poprawny, więc HotXLS, Excel i każdy inny czytnik trzymający się formatu przesuwa go o przesunięcie strefy. Tylko kodowanie czasu edycji i umieszczenie w $0E w .xls mają podpis, który czytnik potrafi wykryć
Testowanie na bajtach, których Twój kod nie pisał
Każda pułapka powyżej przechodzi sprawdzenie zapisz-potem-otwórz, bo symetryczna pomyłka jest niewidzialna dla symetrycznego testu. Referencja musi przyjść skądinąd. Dla .xlsx rozpakuj zapisany plik i asercjonuj dosłowny tekst dcterms:created; dla .xls pakiet olefile w Pythonie czyta strumień SummaryInformation niezależnie przez get_metadata(), raportuje czas edycji w sekundach i traktuje $0E jako liczbę stron, co czyni obie pułapki .xls widocznymi naraz. Drugi kierunek to skoroszyt zapisany przez samego Excela, przeczytany przez API i porównany z tym, co pokazuje File > Info
uses
System.SysUtils, System.DateUtils;
procedure CheckExcelReference;
var
Book: TXLSXWorkbook;
Expected: TDateTime;
begin
// Wartość, którą File > Info w Excelu pokazuje dla tego pliku na maszynie testowej
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');
// Twoje własne sprawdzenie, nie API HotXLS: toleruj sekundę na zaokrąglenie
if Abs(Book.Created - Expected) > OneSecond then
raise Exception.CreateFmt('Created reads as %s',
[DateTimeToStr(Book.Created)]);
finally
Book.Free;
end;
end;
Odpal ten zestaw na maszynie ustawionej na strefę daleko od UTC, z jedną datą testową po każdej stronie zmiany czasu letniego. Agent buildowy zostawiony na UTC ukrywa błąd przesunięcia strefy zupełnie, a pojedyncza letnia data testowa ukrywa błąd LocalFileTimeToFileTime; 20 stycznia i 1 lipca w czasie środkowoeuropejskim łapią oba
Systemy ewidencji, indeksy wyszukiwania i ślady audytu sortują po tych znacznikach, a data myląca się o dzień albo osiem godzin robi więcej szkody niż brakująca, bo nikt jej nie zakwestionuje. Z arkuszowym komponentem HotXLS dla Delphi stała epoki, identyfikatory właściwości i konwersja UTC świadoma czasu letniego są ogarnięte dla .xls i .xlsx, więc kod aplikacji przypisuje i czyta zwykłe lokalne wartości TDateTime. Resztę zestawu właściwości, od tytułu i autora po właściwości niestandardowe, pokrywa artykuł towarzyszący o ustawianiu właściwości dokumentów Excel w Delphi