Artigo Técnico

Timestamps de documento Excel em Delphi: FILETIME, UTC e DST

Uma pasta de trabalho gerada às 09:30 em uma máquina de build em Xangai abre no Excel, e o File > Info reporta que ela foi criada às 17:30. O teste unitário que produziu o arquivo passou: ele atribuiu 09:30, salvou, reabriu e leu 09:30 direto de volta. As duas leituras vêm dos mesmos bytes. O arquivo guarda 09:30 marcado como UTC, o Excel honra a marca e soma oito horas, e o teste nunca olhou a marca. Timestamps de documento em arquivos Excel são UTC em disco, o valor com que um programa trabalha é hora local, e toda conversão entre os dois precisa usar as regras de horário de verão da própria data do stamp

O erro de um dia que um round trip não enxerga

Em um arquivo .xls as horas de criação e save são valores FILETIME: uma contagem de 64 bits de ticks de 100 nanossegundos desde 1601-01-01 UTC ([MS-DTYP] §2.3.3). Um TDateTime do Delphi conta dias a partir de 1899-12-30, a mesma origem serial coberta em seriais de data Excel em Delphi e os sistemas 1900 vs 1904. Converter entre eles precisa de uma constante, o número de dias entre as duas épocas, e esse número é 109205. Há um jeito rápido de conferir sem calendário. A época Unix é 25569 como TDateTime e 134774 dias depois da época do FILETIME, e 25569 + 109205 = 134774

Conte os dias à mão incluindo as duas datas de ponta e você obtém 109206. Um escritor e um leitor construídos sobre essa constante concordam perfeitamente entre si. Todo stamp de criação e save entra no arquivo um dia tarde e sai um dia cedo, então um teste de salvar e reabrir vê exatamente o valor que atribuiu, enquanto o Excel, ou qualquer leitor que use a época correta, mostra amanhã

const
  // dias da época do FILETIME (1601-01-01) até a época do TDateTime (1899-12-30)
  // confira: 25569 + 109205 = 134774, a época Unix em dias de FILETIME
  FileTimeDayBias = 109205;

function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
  // Arredonde para milissegundos inteiros primeiro, depois escale para ticks de 100 ns.
  // Escalar o Double direto para ticks transforma 04:00 em 03:59:59.9999
  Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
Linha do tempo do HotXLS da época do FILETIME 1601-01-01, da época do TDateTime 1899-12-30 e da época Unix de 1970, mostrando o bias de 109205 dias por trás do UtcDateTimeToFileTimeTicks e como um bias de 109206 gravaria todo stamp CreatedDate um dia tarde e o leria um dia cedo
O sketch do UtcDateTimeToFileTimeTicks mantém o bias onde uma constante errada se cancela sozinha — um teste simétrico de salvar e reabrir vê o valor que atribuiu enquanto o painel Info do Excel mostra amanhã

O comentário sobre arredondamento naquele sketch também importa. A fração de um TDateTime é um Double binário, e multiplicá-la diretamente por 864.000.000.000 ticks por dia empurra o erro de representação para os dígitos finais, então um stamp de exatamente 04:00 volta como 03:59:59.9999 e exibe como 03:59. O HotXLS arredonda para milissegundos inteiros primeiro e só então escala para ticks. Valores em hora cheia sobrevivem. O sketch recebe entrada UTC de propósito; o passo de fuso horário vem depois e é a metade mais difícil

Quais IDs de propriedade do SummaryInformation guardam as datas?

O property set \005SummaryInformation definido pelo [MS-OLEPS] mantém a hora de criação sob o ID de propriedade $0C (PIDSI_CREATE_DTM), a hora do último save sob $0D (PIDSI_LASTSAVE_DTM) e o tempo total de edição sob $0A (PIDSI_EDITTIME). O ID logo depois do stamp de save, $0E, é o PIDSI_PAGECOUNT. Coloque um save time lá e o Excel fica sem data de save para exibir, mais uma propriedade de contagem de páginas guardando um FILETIME. O HotXLS grava o stamp de save sob $0D, e quando lê um arquivo em que $0D está ausente mas $0E carrega um VT_FILETIME, toma esse valor como a hora do último save. Uma string ou qualquer outro tipo parado sob um desses IDs em um arquivo malformado é pulado em vez de lido como data. Para ver as streams cruas, veja ler arquivos compostos OLE2 em Delphi sem COM IStorage

PIDSI_EDITTIME é a exceção estranha. Ela é tipada VT_FILETIME mas guarda uma duração: a contagem crua de ticks de 100 ns decorridos, sem época alguma somada. Trate-a como as outras duas, converta EditTimeMinutes / 1440 pela matemática de época, e 125 minutos de edição viram um valor de uns 299 anos. O HotXLS grava a contagem crua de ticks (minutos × 600.000.000). No Windows o leitor também flagra a codificação em forma de data pelo tamanho, já que nenhuma sessão de edição real atravessa três séculos: qualquer edit time de 109206 dias ou mais tem esse offset subtraído antes de EditTimeMinutes ser preenchido

Mapa do HotXLS do property set 005SummaryInformation em que PIDSI_CREATE_DTM em $0C guarda a hora de criação, PIDSI_LASTSAVE_DTM em $0D o stamp de save, PIDSI_EDITTIME em $0A uma duração crua em vez de uma data, e $0E PIDSI_PAGECOUNT, um slot de contagem de páginas que não deve guardar timestamps
PIDSI_EDITTIME é a armadilha dentro da armadilha — tipado VT_FILETIME mas guardando ticks decorridos sem época, então tratá-lo como data transforma 125 minutos de edição em cerca de 299 anos, o que uma checagem de leitura por tamanho reconhece

Definindo timestamps .xls com TXLSWorkbook

TXLSWorkbook.CreatedDate e TXLSWorkbook.LastSavedDate recebem valores TDateTime locais, e o HotXLS os converte para FILETIMEs UTC quando a pasta de trabalho é salva. RevisionNumber e EditTimeMinutes ficam na mesma stream. Um valor zero significa "deixe esta propriedade de fora", que também é como você remove as quatro: limpe-as e o próximo save não grava nenhuma. O HotXLS não carimba Now em LastSavedDate por conta própria. O que você atribuir é o que vai para o arquivo, e esse é o default certo para uma biblioteca. Um job em lote que regenera os relatórios do ano passado normalmente quer as datas do ano passado, e um carimbo automático as sobrescreveria em silêncio

var
  Book: TXLSWorkbook;
begin
  Book := TXLSWorkbook.Create;
  try
    Book.Title := 'Q3 settlement';
    // valores da API são hora local; o arquivo guarda FILETIMEs UTC
    Book.CreatedDate := EncodeDate(2026, 1, 15) + EncodeTime(9, 30, 0, 0);
    Book.LastSavedDate := Now;     // gravado como atribuído, nunca carimbado automaticamente
    Book.RevisionNumber := 7;
    Book.EditTimeMinutes := 125;   // uma duração, guardada como ticks crus
    if Book.SaveAs('settlement.xls') <> 1 then
      raise Exception.Create('Save failed');
  finally
    Book.Free;
  end;
end;

Abrir um arquivo preenche as mesmas quatro propriedades de volta, convertidas para a hora local da máquina que faz a leitura. Um serviço rodando em UTC e um desktop em Tóquio vão reportar valores de CreatedDate diferentes para a mesma pasta de trabalho, nove horas de diferença, e ambos estão certos. Se dois sistemas precisam comparar stamps, converta para UTC do seu lado antes da comparação, ou guarde o valor UTC junto

Por que as datas XLSX saem deslocadas exatamente pelo offset de fuso?

As datas XLSX saem deslocadas pelo offset de fuso quando um escritor carimba a hora local e a rotula como UTC. No docProps/core.xml, dcterms:created e dcterms:modified são valores W3CDTF sob o modelo de core properties do ECMA-376 Part 2, e a forma usual termina em Z. Formatar Now e acrescentar Z é o one-liner óbvio. Numa máquina UTC+8 isso transforma 09:30 em 09:30:00Z, e o Excel nessa mesma máquina mostra 17:30 — o exemplo de abertura, exatamente. Propriedades de data customizadas guardadas como vt:filetime seguem a mesma regra, assim como os FILETIMEs binários no .xls. O HotXLS converte nos três caminhos antes de gravar: TXLSXWorkbook.Created, TXLSXWorkbook.Modified e datas adicionadas por CustomProperties.AddDate são locais do lado da API e UTC com Z no arquivo

Qual função do Windows faz a conversão importa mais do que as pessoas esperam. LocalFileTimeToFileTime aplica o offset em vigor agora. Converta um stamp de janeiro em julho em qualquer fuso com horário de verão e ele sai uma hora errado. O HotXLS usa TzSpecificLocalTimeToSystemTime na escrita e SystemTimeToTzSpecificLocalTime na leitura, e ambos escolhem horário padrão ou de verão a partir da data sendo convertida, não de hoje. Um valor não definido de zero passa intocado nos dois sentidos, então uma propriedade vazia nunca vira uma data de 30 de dezembro de 1899 deslocada por algumas horas

Caminhos de conversão local para UTC do HotXLS para um stamp de janeiro 17:00 CET salvo em julho: o LocalFileTimeToFileTime aplica o offset de verão de hoje e erra uma hora em 15:00Z, enquanto o TzSpecificLocalTimeToSystemTime escolhe o offset pela própria data do stamp e grava o correto 16:00Z
O offset de fuso pertence à própria data do stamp, não às regras atuais da máquina — uma Windows API escolhe o lado certo de uma virada de horário de verão, a outra desloca silenciosamente stamps de janeiro convertidos em julho em uma hora
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');
    // Numa máquina configurada para Central European Time, o core.xml agora guarda
    // <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
    // (UTC+2 em julho), enquanto ApprovedOn é gravado como 16:00Z (UTC+1 em janeiro)
  finally
    Book.Free;
  end;
end;

Fora do Windows a mesma conversão passa pelo suporte de fuso da RTL. No Delphi é o TTimeZone.Local, e as duas horas espinhosas do ano ganham uma resposta fixa lá: uma hora local dentro do vão da primavera não existe, então é gravada inalterada, e uma hora de outono que ocorre duas vezes é tomada como a ocorrência de horário padrão

Lendo stamps W3CDTF gravados por outros geradores

O Excel grava Z, outros geradores nem sempre gravam, e um leitor que só confere Z no caractere 20 erra duas formas comuns. 2026-07-01T01:30:00.5Z tem uma fração no caminho, e 2026-07-01T09:30:00+08:00 tem um offset explícito. Um parser ingênuo lê ambos como hora local sem ajuste. O leitor do HotXLS para Created, Modified e propriedades customizadas com valor de data aceita segundos fracionários de qualquer comprimento, Z, e offsets +hh:mm / -hh:mm; ele converte o instante do offset informado para UTC e depois para hora local. Um stamp só de data como 2026-07-01 é lido como essa data à meia-noite, e um stamp que não parseia de jeito nenhum volta como zero

O único caso que as especificações deixam em aberto é uma hora sem marcador de fuso algum, como 2026-07-01T09:30:00. O perfil W3CDTF exige um designador de fuso sempre que uma hora está presente, e o ECMA-376 Part 2 não dá regra para um stamp que o omite. O HotXLS lê tal valor como hora local, inalterado. Tratá-lo como UTC seria igualmente defensável no papel, mas a origem mais provável de um stamp sem fuso é uma ferramenta que gravou hora local e esqueceu a marca, e deslocar esses valores moveria todos os timestamps dessa ferramenta pelo offset de fuso

Nenhum leitor resgata o erro oposto. Um stamp gravado como hora local e vestindo um Z parece exatamente com um correto, então o HotXLS, o Excel e qualquer outro leitor que siga o formato o deslocam pelo offset de fuso. Só a codificação de edit-time e a colocação em $0E no .xls têm assinatura que um leitor detecta

Testando contra bytes que o seu próprio código não escreveu

Toda armadilha acima passa numa checagem de salvar e reabrir, porque um engano simétrico é invisível para um teste simétrico. A referência precisa vir de outro lugar. Para .xlsx, deszipe o arquivo salvo e dê assert no texto literal de dcterms:created; para .xls, o pacote olefile do Python lê a stream SummaryInformation de forma independente com get_metadata(), reporta o edit time em segundos e trata $0E como contagem de páginas, o que torna as duas armadilhas do .xls visíveis de uma vez. O outro sentido é uma pasta de trabalho salva pelo próprio Excel, lida pela API e comparada com o que o File > Info mostra

uses
  System.SysUtils, System.DateUtils;

procedure CheckExcelReference;
var
  Book: TXLSXWorkbook;
  Expected: TDateTime;
begin
  // O valor que o File > Info do Excel mostra para esse arquivo na máquina de teste
  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');
    // Checagem sua, não é API do HotXLS: permita um segundo de arredondamento
    if Abs(Book.Created - Expected) > OneSecond then
      raise Exception.CreateFmt('Created reads as %s',
        [DateTimeToStr(Book.Created)]);
  finally
    Book.Free;
  end;
end;

Rode essa suíte numa máquina configurada para um fuso bem longe do UTC, com uma data de teste de cada lado de uma virada de horário de verão. Um build agent deixado em UTC esconde completamente o erro de offset de fuso, e uma única data de teste no verão esconde a do LocalFileTimeToFileTime; 20 de janeiro e 1º de julho em Central European Time flagram os dois

Sistemas de registros, índices de busca e trilhas de auditoria ordenam por esses stamps, e uma data deslocada por um dia ou por oito horas causa mais dano que uma ausente, porque ninguém a questiona. Com o componente de planilha HotXLS para Delphi, a constante de época, os IDs de propriedade e a conversão UTC ciente de horário de verão são tratados para .xls e .xlsx, então o código da aplicação atribui e lê valores TDateTime locais comuns. Para o resto do property set, de título e autor a propriedades customizadas, o texto complementar sobre definir propriedades de documento Excel em Delphi cobre os campos restantes