上海一台建置機器在 09:30 產生的活頁簿,在 Excel 裡打開,File > Info 卻說它建立於 17:30。產出這份檔案的單元測試通過了:指派 09:30、存檔、重開、原樣讀回 09:30。兩個讀值來自同一位元組。檔案裡存的是標記為 UTC 的 09:30,Excel 尊重標記加了八小時,而測試根本沒看過那個標記。Excel 檔案裡的文件時間戳在磁碟上是 UTC,程式操作的值是本地時間,兩者之間的每一次轉換,都得用時間戳自己那天的日光節約規則
往返測試看不見的一天之差
在 .xls 檔案裡,建立與儲存時間是 FILETIME 值:從 1601-01-01 UTC 起算的 64 位元 100 奈秒刻度計數([MS-DTYP] §2.3.3)。Delphi 的 TDateTime 從 1899-12-30 起算天數,與Delphi 的 Excel 日期序號與 1900 對 1904 系統裡談的是同一個序號起點。兩者互轉只需要一個常數——兩個紀元之間的天數——這個數字是 109205。有個不必查曆的快速驗證法:Unix 紀元以 TDateTime 表示是 25569,在 FILETIME 紀元之後 134774 天,而 25569 + 109205 = 134774
徒手數天數、把兩個端點都算進去,會得到 109206。建立在這個常數上的寫入端與讀取端彼此完美一致:每個建立與儲存時間戳寫入時晚一天、讀回時早一天,所以存檔重開測試看到的正是它指派的值,而 Excel——或任何使用正確紀元的讀取端——顯示的是明天
const
// 從 FILETIME 紀元(1601-01-01)到 TDateTime 紀元(1899-12-30)的天數
// 驗算:25569 + 109205 = 134774,以 FILETIME 天數計的 Unix 紀元
FileTimeDayBias = 109205;
function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
// 先取整到整毫秒,再換算成 100 奈秒刻度。
// 把 Double 直接乘成刻度,04:00 會變成 03:59:59.9999
Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
示意裡那條捨入註解也同樣要緊。TDateTime 的小數部分是二進位 Double,直接乘上每天 864,000,000,000 個刻度,會把表示誤差推進低位數,正好 04:00 的時間戳回來變成 03:59:59.9999、顯示成 03:59。HotXLS 先取整到整毫秒,然後才換算成刻度,整點值得以完整存活。這個示意刻意吃 UTC 輸入;時區那一步來得更晚,也才是難的那一半
哪些 SummaryInformation 屬性 ID 放著日期?
[MS-OLEPS] 定義的 \005SummaryInformation 屬性集裡,建立時間在屬性 ID $0C(PIDSI_CREATE_DTM)、最後儲存時間在 $0D(PIDSI_LASTSAVE_DTM)、總編輯時間在 $0A(PIDSI_EDITTIME)。緊排在儲存時間戳後面的 $0E 是 PIDSI_PAGECOUNT:把儲存時間放那裡,Excel 就沒有儲存日期可顯示,還多出一個裝著 FILETIME 的頁數屬性。HotXLS 把儲存時間戳寫在 $0D;讀到 $0D 不存在、但 $0E 帶 VT_FILETIME 的檔案時,就把該值當作最後儲存時間。格式錯亂的檔案裡,這些 ID 底下若坐著字串或其他型別,會被跳過而不是誤讀成日期。想親眼看這些原始串流,見在 Delphi 中不靠 COM IStorage 讀取 OLE2 複合檔案
PIDSI_EDITTIME 是其中的異類。型別是 VT_FILETIME,裝的卻是一段時長:已流逝的 100 奈秒刻度原始數量,不加任何紀元。把它當成另外兩個那樣處理、讓 EditTimeMinutes / 1440 走紀元換算,125 分鐘的編輯就變成一個約 299 年長的值。HotXLS 寫的是純刻度數(分鐘 × 600,000,000)。Windows 上讀取端還會靠大小認出這種日期形狀的編碼,因為沒有任何真實編輯過程橫跨三個世紀:任何 109206 天以上的編輯時間,會在填入 EditTimeMinutes 之前先扣掉這個偏移
用 TXLSWorkbook 設定 .xls 時間戳
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 的日期剛好差了一個時區偏移?
寫入端把本地時間打上 UTC 標記時,XLSX 的日期就會差出一個時區偏移。docProps/core.xml 裡的 dcterms:created 與 dcterms:modified 是 ECMA-376 Part 2 核心屬性模型下的 W3CDTF 值,常見形式以 Z 結尾。把 Now 格式化再接一個 Z 是最直覺的一行寫法:在 UTC+8 的機器上,它把 09:30 變成 09:30:00Z,同一台機器上的 Excel 顯示 17:30——正好就是開頭那個例子。以 vt:filetime 儲存的自訂日期屬性遵循同一規則,.xls 裡的二進位 FILETIME 也一樣。HotXLS 在三條路徑上都是先轉換再寫入:TXLSXWorkbook.Created、TXLSXWorkbook.Modified 與透過 CustomProperties.AddDate 加入的日期,API 側是本地時間,檔案裡是帶 Z 的 UTC
用哪個 Windows 函式做轉換,比大家預期的更重要。LocalFileTimeToFileTime 套用的是此刻生效的偏移;在有日光節約的時區,把一月的時間戳拿到七月來轉,就會差一小時。HotXLS 寫入用 TzSpecificLocalTimeToSystemTime、讀取用 SystemTimeToTzSpecificLocalTime,兩者都由被轉換的日期自己決定標準時間還是日光節約時間,而不是看今天。未設定的零值兩個方向都原樣通過,所以空屬性永遠不會變成一個被挪了幾小時的 1899-12-30
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');
// 在設為中歐時間的機器上,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,其他產生器不一定,而只檢查第 20 個字元是不是 Z 的讀取端,會把兩種常見形式讀錯: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 與任何遵循格式的讀取端都會把它平移一個時區偏移。只有 .xls 裡的編輯時長編碼與 $0E 位置,留下了讀取端認得出的指紋
用不是你自己程式碼寫出的位元組來測試
上面每個陷阱都能通過存檔再重開的檢查,因為對稱的錯誤在對稱的測試裡是隱形的。基準必須來自別處。.xlsx:把存出的檔案解壓,斷言 dcterms:created 的字面文字;.xls:Python 的 olefile 套件以 get_metadata() 獨立讀取 SummaryInformation 串流,以秒回報編輯時間、把 $0E 當頁數,兩個 .xls 陷阱一次現形。另一個方向是拿 Excel 自己存的活頁簿,透過 API 讀取,與 File > Info 顯示的內容比對
uses
System.SysUtils, System.DateUtils;
procedure CheckExcelReference;
var
Book: TXLSXWorkbook;
Expected: TDateTime;
begin
// Excel 的 File > Info 在測試機器上為這份檔案顯示的值
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');
// 你自己的檢查,不是 HotXLS API:容許一秒的捨入誤差
if Abs(Book.Created - Expected) > OneSecond then
raise Exception.CreateFmt('Created reads as %s',
[DateTimeToStr(Book.Created)]);
finally
Book.Free;
end;
end;
把這套測試跑在時區離 UTC 很遠的機器上,測試日期在日光節約切換的兩側各放一個。留在 UTC 的建置代理程式會把時區偏移錯誤藏得完全不見,只用夏天的測試日期則會漏掉 LocalFileTimeToFileTime 那個;中歐時間的一月 20 日與七月 1 日,兩個一起抓
記錄系統、搜尋索引與稽核軌跡都按這些時間戳排序,而差一天或差八小時的日期比缺漏更糟,因為沒有人會起疑。有了 HotXLS Delphi 試算表元件,紀元常數、屬性 ID 與日光節約感知的 UTC 轉換在 .xls 與 .xlsx 都已處理好,應用程式碼只管指派與讀取普通的本地 TDateTime 值。屬性集的其餘部分——從標題、作者到自訂屬性——姊妹篇在 Delphi 中設定 Excel 文件屬性涵蓋剩下的欄位