技术文章

Delphi 中的 Excel 文档时间戳:FILETIME、UTC 与 DST

上海一台构建机上 09:30 生成的工作簿在 Excel 里打开,File > Info 显示创建时间是 17:30。产出这个文件的单元测试是通过的:赋值 09:30、保存、重开、原样读回 09:30。两次读数来自同一份字节。文件里存的是标着 UTC 的 09:30,Excel 认这个标记加了八小时,而测试从头到尾没看过那个标记。Excel 文件里的文档时间戳在磁盘上是 UTC,程序操作的值是本地时间,两者之间的每一次换算都必须使用时间戳自身日期当天的夏令时规则

往返测试看不出的一天误差

在 .xls 文件里,创建和保存时间是 FILETIME 值:自 1601-01-01 UTC 起 100 纳秒 tick 的 64 位计数([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 纳秒 tick
  // 把 Double 直接放大到 tick 会把 04:00 变成 03:59:59.9999
  Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
HotXLS 时间线示意:FILETIME 纪元 1601-01-01、TDateTime 纪元 1899-12-30 与 1970 Unix 纪元,UtcDateTimeToFileTimeTicks 背后的 109205 天偏移,以及偏移取 109206 时每条 CreatedDate 如何被写晚一天、读早一天
UtcDateTimeToFileTimeTicks 示意里的偏移量正处在错误常数会自我抵消的位置——对称的保存重开测试看到自己赋的值,Excel 的 Info 面板却显示明天

那段取整注释同样要紧。TDateTime 的小数部分是一个二进制 Double,直接乘上每天 864,000,000,000 个 tick 会把表示误差挤进低位数字,恰好 04:00 的时间戳读回来就成了 03:59:59.9999,显示为 03:59。HotXLS 先取整到整毫秒、再放大到 tick,整点值得以幸存。这段示意特意接收 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 下面的字符串或其他类型会被跳过,而不会被误读成日期。想看那些流的原始样子,见 不靠 COM IStorage 在 Delphi 中读取 OLE2 复合文件

PIDSI_EDITTIME 是其中最古怪的。类型标着 VT_FILETIME,装的却是一段时长:裸的已流逝 100 纳秒 tick 数,不加任何纪元。把它当成另外两个属性处理、让 EditTimeMinutes / 1440 走一遍纪元换算,125 分钟的编辑就变成一个约 299 年长的值。HotXLS 写的是裸 tick 数(分钟 × 600,000,000)。Windows 上的读取端还能按数值大小认出这种日期形状的编码——没有哪次真实编辑横跨三个世纪:任何 109206 天以上的编辑时长都会先减去这个偏移再填进 EditTimeMinutes

HotXLS 的 005SummaryInformation 属性集映射:$0C 的 PIDSI_CREATE_DTM 存创建时间,$0D 的 PIDSI_LASTSAVE_DTM 存保存时间戳,$0A 的 PIDSI_EDITTIME 是裸时长而非日期,$0E 的 PIDSI_PAGECOUNT 则是不能放时间戳的页数槽位
PIDSI_EDITTIME 是陷阱里的陷阱——类型标着 VT_FILETIME,装的却是不带纪元的流逝 tick 数,当成日期处理会把 125 分钟编辑时长变成约 299 年,读取端按大小判断的检查能认出这种编码

用 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;   // 一段时长,按裸 tick 存储
    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 是 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 日

HotXLS 本地时间到 UTC 的换算路径,对象是一条一月 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');
    // 在设为中欧时间的机器上,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 profile 要求有时间就必须带时区指示符,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 那个;中欧时间下的 1 月 20 日和 7 月 1 日能把两个都抓住

记录系统、搜索索引和审计追踪都按这些戳排序,一个差一天或差八小时的日期比缺失的日期危害更大,因为没人会怀疑它。用 HotXLS Delphi 电子表格组件,纪元常数、属性 ID 和感知夏令时的 UTC 换算对 .xls 和 .xlsx 都已处理妥当,应用代码只管赋和读普通的本地 TDateTime。属性集的其余部分——从标题、作者到自定义属性——见姊妹篇 在 Delphi 中设置 Excel 文档属性