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;
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
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
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