Şanghay'daki bir derleme makinesinde 09:30'da üretilmiş bir çalışma kitabı Excel'de açılır ve Dosya > Bilgi, 17:30'da oluşturulduğunu raporlar. Dosyayı üreten birim testi geçti: 09:30 atadı, kaydetti, yeniden açtı ve 09:30'u olduğu gibi geri okudu. İki okuma da aynı baytlardan gelir. Dosya, UTC olarak işaretlenmiş 09:30 taşır; Excel işarete uyar ve sekiz saat ekler; test ise işarete hiç bakmadı. Excel dosyalarındaki belge zaman damgaları diskte UTC'dir, programın çalıştığı değer yerel saatir ve ikisi arasındaki her dönüşüm, damganın kendi tarihinin yaz saati uygulaması kurallarını kullanmak zorundadır
Gidiş dönüşün göremediği bir günlük hata
Bir .xls dosyasında oluşturma ve kaydetme zamanları FILETIME değerleridir: 1601-01-01 UTC'den bu yana 100 nanosaniyelik tiklerin 64 bitlik sayısı ([MS-DTYP] §2.3.3). Bir Delphi TDateTime ise günleri 1899-12-30'dan sayar — Delphi'de Excel tarih serileri ile 1900 ve 1904 sistemleri yazısının kapsadığı aynı seri başlangıcı. İkisi arasında dönüşüm tek bir sabit ister: iki devir arasındaki gün sayısı ve o sayı 109205'tir. Takvimsiz denetlemenin hızlı bir yolu vardır. Unix devri bir TDateTime olarak 25569'dur ve FILETIME devrinden 134774 gün sonradır; 25569 + 109205 = 134774
Günleri elle sayıp iki bitiş tarihini de katarsanız 109206 çıkar. O sabit üzerine kurulmuş bir yazıcı ve okuyucu birbirıyla mükemmel şekilde anlaşır. Her oluşturma ve kaydetme damgası dosyaya bir gün geç girer, bir gün erken çıkar; böylece bir kaydet-ve-yeniden-aç testi tam olarak atadığı değeri görürken Excel ya da doğru devri kullanan herhangi bir okuyucu yarını gösterir
const
// FILETIME devri (1601-01-01) ile TDateTime devri (1899-12-30) arasındaki gün sayısı
// denetim: 25569 + 109205 = 134774, FILETIME günü cinsinden Unix devri
FileTimeDayBias = 109205;
function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
// Önce tam milisaniyeye yuvarla, sonra 100 ns tikine ölçekle.
// Double'ı doğrudan tike ölçeklemek 04:00'ü 03:59:59.9999 yapar
Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
O taslaktaki yuvarlama yorumu da önemlidir. Bir TDateTime kesri ikili bir Double'dır ve onu doğrudan günde 864.000.000.000 tikle çarpmak gösterim hatasını düşük basamaklara iter; tam olarak 04:00 damgası 03:59:59.9999 olarak geri okunur ve 03:59 görünür. HotXLS önce tam milisaniyeye yuvarlar, sonra tike ölçekler. Tam saat değerleri sağ çıkarlar. Taslak, giriş olarak bilinçli olarak UTC alır; saat dilimi adımı sonra gelir ve zoru odur
Tarihleri hangi SummaryInformation özellik kimlikleri taşır?
[MS-OLEPS]'in tanımladığı \005SummaryInformation özellik kümesi, oluşturma zamanını $0C (PIDSI_CREATE_DTM) özellik kimliği altında, son kaydetme zamanını $0D (PIDSI_LASTSAVE_DTM) altında ve toplam düzenleme süresini $0A (PIDSI_EDITTIME) altında tutar. Kaydetme damgasının hemen ardından gelen kimlik olan $0E, PIDSI_PAGECOUNT'tur. Oraya bir kaydetme zamanı koyun; Excel'in gösterecek kaydetme tarihi kalmaz, üstelik FILETIME taşıyan bir sayfa sayısı özelliği olur. HotXLS kaydetme damgasını $0D altına yazar ve $0D bulunmayan ama $0E'nin VT_FILETIME taşıdığı bir dosyayı okurken o değeri son kaydetme zamanı olarak alır. Bozuk bir dosyada bu kimliklerden birinin altında duran bir string ya da başka herhangi bir tür, tarih olarak yanlış okunmak yerine atlanır. Ham akışların kendilerine bakmak için COM IStorage olmadan Delphi'de OLE2 bileşik dosyaları okuma yazısına bakın
PIDSI_EDITTIME aralarındaki tuhaf olanıdır. Türü VT_FILETIME ama bir süre taşır: geçen 100 ns tiklerinin ham sayısı, üstüne eklenmiş bir devir yoktur. Öteki ikisi gibi işlemeye kalkıp EditTimeMinutes / 1440'ı devir matematiğiyle çevirirseniz 125 dakikalık düzenleme kabaca 299 yıllık bir değere dönüşür. HotXLS düz tik sayısını yazar (dakika × 600.000.000). Windows'ta okuyucu, tarih biçimli kodlamayı boyutundan da yakalar; gerçek bir düzenleme oturumu üç yüzyıla yayılamayacağı için 109206 gün ve üzeri her düzenleme zamanından, EditTimeMinutes doldurulmadan önce o sapma çıkarılır
TXLSWorkbook ile .xls zaman damgalarını atamak
TXLSWorkbook.CreatedDate ve TXLSWorkbook.LastSavedDate yerel TDateTime değerleri alır ve HotXLS çalışma kitabı kaydedilirken onları UTC FILETIME'lara çevirir. RevisionNumber ve EditTimeMinutes aynı akışta durur. Sıfır değeri "bu özelliği bırak" demektir; dördünü de sökmek de böyle olur: temizleyin, bir sonraki kayıt hiçbirini yazmaz. HotXLS kendi kendine LastSavedDate'e Now damgalamaz. Ne atıyorsanız dosyaya o gider ve bir kitaplık için doğru varsayılan budur. Geçen yılın raporlarını yeniden üreten bir toplu iş genellikle geçen yılın tarihlerini ister ve otomatik bir damga onları sessizce üzerine yazardı
var
Book: TXLSWorkbook;
begin
Book := TXLSWorkbook.Create;
try
Book.Title := 'Q3 settlement';
// API değerleri yerel saat; dosya UTC FILETIME'ları saklar
Book.CreatedDate := EncodeDate(2026, 1, 15) + EncodeTime(9, 30, 0, 0);
Book.LastSavedDate := Now; // atandığı gibi yazılır, asla otomatik damgalanmaz
Book.RevisionNumber := 7;
Book.EditTimeMinutes := 125; // bir süre, ham tikler olarak saklanır
if Book.SaveAs('settlement.xls') <> 1 then
raise Exception.Create('Save failed');
finally
Book.Free;
end;
end;
Bir dosyayı açmak aynı dört özelliği geri doldurur; okuyan makinenin yerel saatine çevrilmiş olarak. UTC'de çalışan bir hizmet ile Tokyo'daki bir masaüstü, aynı çalışma kitabı için dokuz saat farklı CreatedDate değerleri raporlar ve ikisi de doğrudur. İki sistemin damgaları karşılaştırması gerekiyorsa, karşılaştırmadan önce kendi tarafınızda UTC'ye çevirin ya da UTC değerini yanına saklayın
XLSX tarihleri neden tam olarak saat dilimi ofseti kadar saptı?
Bir yazıcı yerel saati damgalayıp ona UTC etiketi taktığında XLSX tarihleri bölge ofseti kadar saptı çıkar. docProps/core.xml'de dcterms:created ve dcterms:modified, ECMA-376 Bölüm 2'nin çekirdek özellikler modeli altında W3CDTF değerleridir ve alışılmış biçim Z ile biter. Now'u biçimlendirip Z eklemek bariz tek satırlıktır. UTC+8 bir makinede 09:30'u 09:30:00Z'ye çevirir ve aynı makinedeki Excel 17:30 gösterir — açılış örneğinin ta kendisi. vt:filetime olarak saklanan özel tarih özellikleri de aynı kuralı izler; .xls'teki ikili FILETIME'lar da. HotXLS üç yolda da yazmadan önce çevirir: TXLSXWorkbook.Created, TXLSXWorkbook.Modified ve CustomProperties.AddDate üzerinden eklenen tarihler API tarafında yereldir, dosyada Z'li UTC'dir
Dönüşümü hangi Windows işlevinin yaptığı, insanların beklentisinin ötesinde bir işe yarar. LocalFileTimeToFileTime şu an geçerli olan ofseti uygular. Yaz saati uygulaması olan herhangi bir bölgede Ocak damgasını Temmuz'da çevirin, bir saat saptı gelir. HotXLS yazarken TzSpecificLocalTimeToSystemTime'ı, okurken SystemTimeToTzSpecificLocalTime'ı kullanır ve ikisi de standart ya da yaz saatini, bugünden değil çevrilen tarihten seçer. Atanmamış sıfır değeri iki yönde de dokunulmadan geçirilir; böylece boş bir özellik asla birkaç saat kaydırılmış 30 Aralık 1899 tarihine dönüşmez
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');
// Orta Avrupa Saati'ne ayarlı bir makinede core.xml artık şunu taşır:
// <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
// (Temmuz'da UTC+2); ApprovedOn ise 16:00Z olarak yazılır (Ocak'ta UTC+1)
finally
Book.Free;
end;
end;
Windows dışında aynı dönüşüm, RTL'nin saat dilimi desteğinden geçer. Delphi'de o destek TTimeZone.Local'dır ve yılın iki sancılı saati orada sabit bir yanıt alır: ileri atlama boşluğunun içindeki bir yerel saat yoktur, olduğu gibi yazılır; sonbaharda iki kez yaşanan saat, standart saatteki tekrarı sayılır
Başka üreticilerin yazdığı W3CDTF damgalarını okumak
Excel Z yazar; öteki üreticiler her zaman yapmaz ve 20. karakterdeki Z'yi denetleyen bir okuyucu iki yaygın biçimi yanlış okur. 2026-07-01T01:30:00.5Z'in yolunda bir kesir vardır, 2026-07-01T09:30:00+08:00'in ise açık bir ofseti. Naif bir ayrıştırıcı ikisini de ayarsız yerel saat olarak okur. Created, Modified ve tarih değerli özel özellikler için HotXLS okuyucusu her uzunlukta kesirli saniyeleri, Z'yi ve +hh:mm / -hh:mm ofsetlerini kabul eder; an, verilen ofsetten UTC'ye ve sonra yerel saate çevrilir. 2026-07-01 gibi yalnızca tarihli bir damga o tarihin gece yarısı olarak okunur; hiç ayrıştırılamayan bir damga sıfır olarak geri gelir
Şartnamelerin açık bıraktığı tek durum, hiç bölge işareti taşımayan bir zamandır: 2026-07-01T09:30:00 gibi. W3CDTF profili, saat varolduğunda bir bölge göstergesi ister; ECMA-376 Bölüm 2 ise onu bırakan bir damga için kural vermez. HotXLS böyle bir değeri yerel saat olarak, değiştirmeden okur. Onu UTC saymak kâğıt üzerinde aynı derecede savunulabilir olurdu; ama bölgesiz bir damganın en olası kaynağı, yerel saat yazıp işareti bırakan bir araçtır ve o değerleri kaydırmak, o aracın her zaman damgasını bölge ofseti kadar oynatırdı
Tersini yapan hatayı hiçbir okuyucu kurtaramaz. Yerel saat yazılıp üstüne Z takılmış bir damga, doğrusuna tepeden bakınca aynı görünür; HotXLS, Excel ve biçimi izleyen herhangi bir okuyucu onu bölge ofseti kadar kaydırır. Yalnızca düzenleme-süresi kodlaması ile .xls'teki $0E yerleşimi, bir okuyucunun sezebileceği bir imzaya sahiptir
Kendi kodunuzun yazmadığı baytlara karşı test etmek
Yukarıdaki her tuzak bir kaydet-sonra-yeniden-aç denetimini geçer; çünkü simetrik bir hata, simetrik bir teste görünmezdir. Başvuru başka bir yerden gelmek zorundadır. .xlsx için kaydedilen dosyayı açın ve dcterms:created'in harfiyen metnini doğrulayın; .xls için Python'un olefile paketi, SummaryInformation akışını get_metadata() ile bağımsız okur, düzenleme süresini saniye cinsinden raporlar ve $0E'yi sayfa sayısı sayar; böylece iki .xls tuzağı da bir anda görünür olur. Öteki yön, Excel'in kendisinin kaydettiği, API üzerinden okunan ve Dosya > Bilgi'nin gösterdiğiyle karşılaştırılan bir çalışma kitabıdır
uses
System.SysUtils, System.DateUtils;
procedure CheckExcelReference;
var
Book: TXLSXWorkbook;
Expected: TDateTime;
begin
// Test makinesinde bu dosya için Excel'in Dosya > Bilgi'sinin gösterdiği değer
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');
// Kendi denetiminiz, HotXLS API'si değil: yuvarlama için bir saniye tanıyın
if Abs(Book.Created - Expected) > OneSecond then
raise Exception.CreateFmt('Created reads as %s',
[DateTimeToStr(Book.Created)]);
finally
Book.Free;
end;
end;
O takımı, UTC'den iyice uzak bir bölgeye ayarlı bir makinede, test tarihlerinden biri yaz saati değişiminin bir yanında öteki öte yanında olacak biçimde çalıştırın. UTC'de bırakılmış bir derleme ajanı bölge-ofseti hatasını tümüyle gizler ve tek bir yazlık test tarihi LocalFileTimeToFileTime hatasını gizler; Orta Avrupa Saati'nde 20 Ocak ile 1 Temmuz ikisini de yakalar
Kayıt sistemleri, arama indeksleri ve denetim izleri bu damgalara göre sıralar; bir ya da sekiz saat sapmış bir tarih, eksik bir tarihten daha çok zarar verir, çünkü kimse sorgulamaz. HotXLS Delphi elektronik tablo bileşeniyle devir sabiti, özellik kimlikleri ve yaz saatine duyarlı UTC dönüşümü .xls ile .xlsx'in ikisinde de halledilir; uygulama kodu sıradan yerel TDateTime değerleri atar ve okur. Özellik kümesinin geri kalanı için — başlıktan yazara ve özel özelliklere dek — Delphi'de Excel belge özelliklerini atama yazısı kalan alanları kapsar