Articolo tecnico

Round-trip XLSX senza perdite: theme, extLst, calcChain

Un job di fatturazione apre un modello cliente, scrive 42750 in B3 e salva. Fate il diff dei pacchetti decompressi dopo, e la lista delle modifiche è molto più lunga di una cella: xl/theme/theme1.xml ora contiene la palette Office di serie invece del teal e dello slate del cliente, il <extLst> in fondo all'XML del foglio ha perso il gruppo di sparkline e una regola di formattazione condizionale più recente, e xl/calcChain.xml manca del tutto. Excel apre il risultato, propone una riparazione, e i colori del marchio sono spariti. Il codice ha toccato una cella. Tutto il resto è cambiato perché il salvataggio ha ricostruito il pacchetto da ciò che il modello in memoria sapeva, e tre parti di un modello tipico stanno fuori da ciò che un modello di foglio di calcolo normalmente contiene

I tre meccanismi dietro un round-trip XLSX senza perdite di HotXLS in Delphi: xl/theme/theme1.xml messo in cache come byte grezzi e riscritto identico salvo gli override degli slot ThemeColor, blocchi extLst estranei catturati dagli eventi XML e riprodotti, e un calcChain.xml nuovo e conforme alle specifiche emesso a ogni salvataggio con formule
Ogni parte conservata segue il proprio percorso attraverso il salvataggio — byte letterali del tema, riproduzione a livello di evento di extLst e catena di calcolo rigenerata — mentre l'XML dei fogli e gli stili vengono ricostruiti dal modello

Perché una modifica a una cella riscrive l'intero pacchetto XLSX

Un file .xlsx è uno ZIP di parti XML: xl/workbook.xml, un xl/worksheets/sheetN.xml per foglio, xl/styles.xml, xl/sharedStrings.xml, il tema, la catena di calcolo, e qualsiasi drawing, tabella e cache di pivot la cartella porti con sé. Una libreria che legge valori e formule in oggetti e rigenera ogni parte da quegli oggetti al salvataggio ha un punto debole. Tutto ciò per cui il modello a oggetti non ha uno slot non arriva mai in memoria, quindi la parte rigenerata ne esce senza. Nessuno deve cancellare le sparkline; semplicemente non hanno dove vivere tra Open e SaveAs

ECMA-376 aveva visto arrivare metà del problema. SpreadsheetML riserva extLst (ECMA-376 Parte 1, §18.2.10 per l'elemento a livello workbook, con elementi corrispondenti su fogli, stili e formattazioni condizionali) come area di archiviazione per funzionalità future. Un produttore più recente avvolge ogni funzionalità in un elemento <ext> il cui attributo uri nomina la funzionalità, e ci si aspetta che un consumatore più vecchio porti ciò che non capisce. Sparkline, liste di slicer, opzioni più recenti per data bar e set di icone, e la validazione dati estesa viaggiano tutti così nei file che Excel scrive oggi. Buttare via blocchi <ext> sconosciuti rompe quindi il contratto di forward compatibility su cui il formato è costruito, e il danno appare solo quando il cliente riapre il file in Excel

Il tema e la catena di calcolo falliscono per ragioni diverse, quindi ognuno richiede il suo trattamento. Il resto dell'articolo percorre come HotXLS gestisce tutti e tre, che cosa può osservare e controllare un caller Delphi, e dove la garanzia si ferma

Mantenere intatto un theme1.xml personalizzato in Delphi

HotXLS conserva il tema di una cartella tenendo i byte originali di xl/theme/theme1.xml dal pacchetto aperto e riscrivendo quella parte così com'è al SaveAs. La parte tema (ECMA-376 Parte 1, §14.2.7) è DrawingML: uno schema colori con dodici slot, uno schema font, uno schema di formato di riempimenti, linee ed effetti. Gli stili di cella puntano lì dentro con <color theme="4"/> e riferimenti simili, quindi il motore del foglio deve solo risolvere slot, mai capire gradienti o stili di effetto. Rigenerare un tema Office fisso a ogni salvataggio è esattamente ciò che trasforma il teal del cliente in blu Office. Una cartella creata da zero, senza tema da portare, riceve invece il tema Office incorporato

HotXLS mette in cache i byte grezzi di xl/theme/theme1.xml all'apertura e li riscrive identici al salvataggio sostituendo solo gli slot colore passati per ThemeColor, mentre una libreria che ricostruisce dal modello rigenera un tema Office di serie e riporta indietro i colori del marchio del cliente
Mettere in cache theme1.xml letteralmente non richiede alcun modello del tema, e ThemeMajorFont insieme a ThemeMinorFont danno stile solo alle cartelle che non portano un tema catturato

Il caso quotidiano non richiede alcun codice per il tema. Notate l'indice del foglio: Sheets è a base 1 nel motore XLSX, e Cells[3, 2] è riga 3, colonna 2, cioè B3

var
  Book: TXLSXWorkbook;
begin
  Book := TXLSXWorkbook.Create;
  try
    Book.Open('branded-invoice.xlsx');
    Book.Sheets[1].Cells[3, 2].Value := 42750.00;  // l'unica modifica
    Book.SaveAs('branded-invoice-out.xlsx');
    // xl/theme/theme1.xml nell'output porta il tema del modello stesso
  finally
    Book.Free;
  end;
end;

I byte grezzi sono la fedeltà massima ottenibile per una parte così: nessun parse, nessuna ri-serializzazione, nulla che possa derivare. Quando il salvataggio scrive Strict OOXML invece del dialetto transitional, il tema catturato passa per il traduttore di namespace invece di essere copiato, perché una copia byte lascerebbe URI di namespace transitional dentro un pacchetto Strict

La trappola è sul lato API. TXLSXWorkbook espone ThemeMajorFont e ThemeMinorFont, e dopo Open riportano i caratteri di titolo e corpo analizzati dallo schema font del modello. Impostarli sembra il modo naturale di cambiare font, ma plasmano solo il tema Office incorporato che ricevono le cartelle nuove. Su una cartella che porta il suo tema, la parte catturata vince e quei due setter non cambiano nulla nel file salvato. I colori sono gestiti diversamente: ThemeColor[Slot] indirizza i dodici slot clrScheme, e un override viene scritto nel tema preservato sostituendo solo il colore di quello slot, lasciando intatti lo schema font, lo schema di formato e le estensioni del tema

Book.Open('branded-invoice.xlsx');
// Nessun effetto sul file salvato: il tema del modello stesso è preservato
Book.ThemeMajorFont := 'Segoe UI Semibold';
// Arriva al file: cambia solo lo slot accent1 dentro theme1.xml
Book.ThemeColor[xlsxThemeAccent1] := $FF0F7B6C;  // $AARRGGBB
Book.SaveAs('rebranded.xlsx');

Quella divisione è deliberata. Un override di colore è una modifica stretta e ben definita a un elemento, così il resto del tema del designer può restare esattamente com'era. Una riscrittura dello schema font toccherebbe liste di font per script che una API orientata ai dati non ha un buon modo di esprimere. Se un modello ha bisogno di un nuovo carattere, cambiatelo in Excel e distribuite il nuovo modello; così il tema resta nelle mani di chi possiede il marchio

Che cosa accade ai blocchi extLst sconosciuti al salvataggio?

HotXLS cattura ogni blocco <ext> a livello foglio che non modella nativamente e lo reinterpreta dentro l'extLst del foglio salvato. I blocchi che modella vengono analizzati in oggetti tipizzati e ricostruiti da loro: i gruppi di sparkline finiscono in SparklineGroups, l'estensione di validazione dati x14 viene letta nella collezione di validazione dati, e le liste di slicer vengono riemesse dal modello slicer. Tutto il resto atterra, un frammento XML per blocco, nella lista di stringhe di sola lettura RawWorksheetExts su ogni TXLSXWorksheet, il che significa che un test può ispezionare esattamente che cosa verrà portato avanti

var
  Book: TXLSXWorkbook;
  Sheet: TXLSXWorksheet;
  i: Integer;
begin
  Book := TXLSXWorkbook.Create;
  try
    Book.Open('from-newer-excel.xlsx');
    Sheet := Book.Sheets[1];
    WriteLn(Format('%d foreign ext block(s), %d sparkline group(s)',
      [Sheet.RawWorksheetExts.Count, Sheet.SparklineGroups.Count]));
    for i := 0 to Sheet.RawWorksheetExts.Count - 1 do
      WriteLn(Copy(Sheet.RawWorksheetExts[i], 1, 100)); // il tag di apertura mostra l'uri
    // Dichiarazioni di namespace che i frammenti hanno preso in prestito dalla radice <worksheet>
    WriteLn(Sheet.RawExtNamespaceDecls);
  finally
    Book.Free;
  end;
end;

La cattura lavora dallo stream di eventi XML, perché un lettore streaming consegna elementi, testo e tag di chiusura ma nessun offset di byte nella sorgente. Ogni sottoalbero sconosciuto viene ricostruito da quegli eventi al loro passaggio. Un contatore di profondità ingenuo si rompe qui: incrementa a ogni tag di apertura e decrementa a ogni tag di chiusura, e un figlio auto-conclusivo come <x14:cfvo type="min"/> arriva come un solo evento di apertura flaggato vuoto, senza tag di chiusura dietro. Contatelo come elemento aperto e il contatore non torna mai a zero, quindi la cattura ingoia il resto del foglio. Il loop di cattura in HotXLS incrementa la profondità solo per un tag di apertura non vuoto, e un <ext/> vuoto a sua volta viene conservato subito come frammento di una riga

Ricostruire dagli eventi ha un effetto collaterale visibile. Le virgolette degli attributi, gli spazi tra elementi e la scelta tra <a></a> e <a/> tornano normalizzati, quindi un frammento è equivalente nel significato all'originale ma non identico byte per byte. Excel analizza l'XML; non confronta byte. Uno strumento di diff che confronta testo però segnerà la modifica, e conviene saperlo prima che qualcuno la archivi come regressione

I namespace sono la seconda cosa che può andare storta con un frammento reinterpretato. Excel di solito dichiara i prefissi che servono sull'elemento <ext> stesso, il che rende il frammento autosufficiente, ma un blocco può anche appoggiarsi a un prefisso come x14ac o xr dichiarato una volta sola sulla radice <worksheet> di partenza. Reinterpretate quel frammento in un foglio senza la dichiarazione e l'XML salvato non è namespace-well-formed. HotXLS scansione ogni frammento catturato alla ricerca di prefissi usati e non dichiarati, registra le dichiarazioni corrispondenti dalla sorgente in RawExtNamespaceDecls e le scrive sulla radice del foglio salvato. Poiché i frammenti sono stringhe semplici, duplicare un foglio dentro o tra cartelle di lavoro può portarli anche al nuovo foglio

Scrivere calcChain.xml perché Excel si fidi delle vostre formule

HotXLS scrive xl/calcChain.xml (la parte Calculation Chain, ECMA-376 Parte 1, §12.3.1) ogni volta che la cartella salvata contiene almeno una cella con formula, insieme al suo content-type override e alla relazione del workbook. Ogni voce è un elemento <c r="D10" i="1"/>: il riferimento di cella più l'indice del foglio a base 1, che il writer emette su ogni voce anche se lo schema lascia che una sequenza di voci sullo stesso foglio lo ometta. Esplicito è più semplice e valido altrettanto

L'ordine dipende da ciò che la cartella sa già. Quando il grafo delle dipendenze delle formule esiste ed è aggiornato, che è lo stato subito dopo Recalculate, la catena segue un ordine topologico completo: ogni formula dopo le celle da cui dipende, con i membri dei riferimenti circolari accodati alla fine così la catena elenca comunque ogni cella con formula. Quando il grafo è stantio o non è mai stato costruito, le celle con formula sono elencate in ordine di documento, foglio per foglio. Entrambi sono legali. Le note di implementazione Microsoft per il formato, [MS-XLSX], descrivono la catena come un suggerimento che Excel controlla e riordina mentre calcola, quindi un elenco completo in qualsiasi ordine carica pulito

HotXLS emette xl/calcChain.xml in ordine topologico quando Recalculate ha costruito il grafo delle dipendenze, e in ordine di documento altrimenti; Excel tratta come suggerimento qualsiasi elenco completo e lo riordina durante il caricamento
Entrambi gli ordinamenti restano leciti perché Excel riverifica la catena al caricamento, e HotXLS non forza mai dentro SaveAs la costruzione del grafo completo
Book.Open('model.xlsx');
Book.Sheets[1].Cells[10, 4].Formula := '=SUM(D2:D9)';
// Salvare qui elenca le celle con formula in ordine di documento, perché
// cambiare una formula ha invalidato il grafo delle dipendenze.
Book.Recalculate;   // ricostruisce il grafo e rinfresca i valori in cache
Book.SaveAs('model-out.xlsx');
// calcChain.xml ora segue l'ordine delle dipendenze: D10 dopo D2:D9

SaveAs non costruisce il grafo di sua iniziativa. Una costruzione completa delle dipendenze significa risolvere ogni riferimento in ogni formula, il che su un modello grande è lavoro vero che un caller che voleva solo scrivere un file non ha mai chiesto. Se i valori in cache nell'output vi stanno a cuore, e di solito lo stanno per qualsiasi cosa un sistema a valle legga senza aprire Excel, chiamate comunque Recalculate prima di salvare; la catena in ordine di dipendenza viene di gratis

Perché emettere una parte che Excel tratta come consultiva? Perché la sua assenza si nota. Le euristiche di riparazione, i viewer di terze parti e gli strumenti di diff si aspettano tutti che una cartella con formule porti una catena di calcolo, e un pacchetto senza sembra un qualcosa che Excel stesso non produce mai. Scrivere una catena valida tiene l'output dentro la forma contro cui il resto dell'ecosistema è stato esercitato, e costa un passaggio sulle celle con formula

Dove finisce il round-trip senza perdite

HotXLS non copia l'intero pacchetto byte per byte, e l'output non va giudicato così. L'XML dei fogli, styles.xml, le stringhe condivise e la parte workbook sono rigenerati dal modello analizzato, quindi sono fedeli nel contenuto ma non binariamente identici all'input. I local header dello ZIP da soli portano timestamp freschi. I frammenti <ext> catturati tornano normalizzati, come descritto sopra. ThemeMajorFont e ThemeMinorFont restano fuori da un tema preservato, mentre gli override di ThemeColor ci entrano slot per slot

La rete di conservazione ha una forma definita: funzionalità che il motore modella nativamente, come sparkline e validazione dati estesa, analizzate e riscritte; contenuto <ext> estraneo a livello foglio, reinterpretato; e la parte tema, portata come catturata. I progetti VBA e i riferimenti a cartelle esterne passano il salvataggio con lo stesso approccio keep-what-you-do-not-model, coperto in l'articolo companion sulla conservazione di VBA e link esterni, e le proprietà del documento in docProps hanno la loro API di lettura-scrittura. Una parte di un add-in esotico che non è né modellata né dentro un punto di estensione sta fuori dai tre meccanismi coperti qui

Il controllo che conta usa i vostri file. Aprite un modello di produzione ricco di funzionalità, cambiate un valore, salvate, decomprimete entrambi i pacchetti e fate il diff parte per parte. Aspettatevi differenze nel foglio modificato, in styles.xml e nella formattazione degli attributi dentro extLst; la parte tema dovrebbe corrispondere all'input, gli elementi <ext> dovrebbero elencare gli stessi valori di uri, e calcChain.xml dovrebbe nominare ogni cella con formula. Tutto ciò che va oltre quella lista merita di essere inseguito prima che il modello entri in produzione

Conservazione del tema, reinterpretazione degli extLst estranei e output della catena di calcolo fanno parte del motore XLSX del HotXLS Delphi Excel Component; la pagina del prodotto elenca il resto di ciò che legge e scrive per progetti Delphi e C++Builder