Zadanie bilingowe otwiera szablon klienta, wpisuje 42750 w B3 i zapisuje plik. Porównaj potem rozpakowane pakiety, a lista zmian będzie znacznie dłuższa niż jedna komórka: xl/theme/theme1.xml trzyma teraz fabryczną paletę Office zamiast klientowskich kolorów turkusu i grafitu, <extLst> na dnie XML arkusza stracił grupę miniwykresów i nowszą regułę formatowania warunkowego, a xl/calcChain.xml zniknął w całości. Excel otwiera wynik, proponuje naprawę, a kolory marki zniknęły. Kod dotknął jednej komórki. Wszystko inne zmieniło się, bo zapis przebudował pakiet z tego, co model w pamięci wiedział, a trzy części typowego szablonu siedzą poza tym, co model arkusza normalnie trzyma
Dlaczego edycja jednej komórki przepisuje cały pakiet XLSX
Plik .xlsx to ZIP części XML: xl/workbook.xml, po jednym xl/worksheets/sheetN.xml na arkusz, xl/styles.xml, xl/sharedStrings.xml, motyw, łańcuch obliczeń i wszystko, co skoroszyt niesie — rysunki, tabele, cache-e pivotów. Biblioteka, która czyta wartości i formuły do obiektów i regeneruje każdą część z tych obiektów przy zapisie, ma jedną słabą plamę. Cokolwiek, na co model obiektowy nie ma slotu, nigdy nie trafia do pamięci, więc regenerowana część wychodzi bez tego. Nikt nie musiał usuwać miniwykresów; po prostu nie mają gdzie mieszkać między Open a SaveAs
ECMA-376 przewidział połowę tego. SpreadsheetML rezerwuje extLst (ECMA-376 Part 1, §18.2.10 dla elementu na poziomie skoroszytu, z odpowiednikami na arkuszach, stylach i formatach warunkowych) jako magazyn funkcji przyszłych. Nowszy producent pakuje każdą funkcję w element <ext>, którego atrybut uri nazywa funkcję, a od starszego konsumenta oczekuje się, że przeniesie to, czego nie rozumie. Miniwykresy, listy fragmentatorów, nowsze opcje pasków danych i zestawów ikon oraz rozszerzona walidacja danych podróżują tak w plikach, które Excel zapisuje dziś. Wyrzucanie nieznanych bloków <ext> łamie więc kontrakt zgodności w przód, wokół którego zbudowano ten format, a szkody wychodzą na jaw dopiero, gdy klient otworzy plik ponownie w Excelu
Motyw i łańcuch obliczeń zawodzą z różnych powodów, więc każdy potrzebuje osobnego traktowania. Reszta artykułu przechodzi przez to, jak HotXLS obsługuje wszystkie trzy, co wywołujący z Delphi może zaobserwować i sprawdzić oraz gdzie gwarancja się kończy
Jak utrzymać własny theme1.xml nietknięty w Delphi
HotXLS zachowuje motyw skoroszytu, trzymając oryginalne bajty xl/theme/theme1.xml z otwartego pakietu i zapisując tę część bez zmian przy SaveAs. Część motywu (ECMA-376 Part 1, §14.2.7) to DrawingML: schemat kolorów z dwunastoma slotami, schemat fontów, schemat formatów z wypełnień, linii i efektów. Style komórek wskazują w niego referencjami typu <color theme="4"/>, więc silnik arkusza musi tylko rozwiązywać sloty, nigdy rozumieć gradienty czy style efektów. Regenerowanie fabrycznego motywu Office przy każdym zapisie to dokładnie to, co zamienia turkus klienta w niebieski Office. Skoroszyt tworzony od zera, bez motywu do przeniesienia, dostaje wbudowany motyw Office
Codzienny przypadek nie potrzebuje żadnego kodu motywu. Zwróć uwagę na indeks arkusza: Sheets jest numerowany od 1 w silniku XLSX, a Cells[3, 2] to wiersz 3, kolumna 2, czyli B3
var
Book: TXLSXWorkbook;
begin
Book := TXLSXWorkbook.Create;
try
Book.Open('branded-invoice.xlsx');
Book.Sheets[1].Cells[3, 2].Value := 42750.00; // ta jedyna edycja
Book.SaveAs('branded-invoice-out.xlsx');
// xl/theme/theme1.xml w wyniku niesie własny motyw szablonu
finally
Book.Free;
end;
end;
Surowe bajty to najsilniejsza wierność, jaką da się uzyskać dla takiej części: bez parsowania, bez ponownej serializacji, nic do dryfowania. Gdy zapis pisze Strict OOXML zamiast dialektu tranzycyjnego, przechwycony motyw przechodzi przez tłumacza przestrzeni nazw zamiast być kopiowanym, bo kopia bajtowa zostawiłaby tranzycyjne URI przestrzeni nazw wewnątrz pakietu Strict
Pułapka siedzi po stronie API. TXLSXWorkbook eksponuje ThemeMajorFont i ThemeMinorFont, a po Open raportują one krój nagłówków i treści sparsowany ze schematu fontów szablonu. Ustawianie ich wygląda jak naturalny sposób wymiany fontów, ale kształtują tylko wbudowany motyw Office, który dostają nowe skoroszyty. W skoroszycie, który przyniósł własny motyw, wygrywa przechwycona część i te dwa setterzy nie zmieniają nic w zapisanym pliku. Kolory są obsłużone inaczej: ThemeColor[Slot] adresuje dwanaście slotów clrScheme, a nadpisanie trafia do zachowanego motywu przez podmianę samego koloru tego slotu, zostawiając schemat fontów, schemat formatów i wszelkie rozszerzenia motywu nietknięte
Book.Open('branded-invoice.xlsx');
// Bez efektu na zapisany plik: własny motyw szablonu jest zachowany
Book.ThemeMajorFont := 'Segoe UI Semibold';
// Dociera do pliku: w theme1.xml zmienia się tylko slot accent1
Book.ThemeColor[xlsxThemeAccent1] := $FF0F7B6C; // $AARRGGBB
Book.SaveAs('rebranded.xlsx');
Ten podział jest celowy. Nadpisanie koloru to wąska, dobrze zdefiniowana edycja jednego elementu, więc reszta motywu projektanta może zostać dokładnie taka, jaka była. Przepisanie schematu fontów dotknęłoby list fontów per pismo, których API zorientowane na dane nie ma jak dobrze wyrazić. Jeśli szablon potrzebuje nowego kroju, zmień go w Excelu i roześlij nowy szablon; to trzyma motyw w rękach tego, kto odpowiada za markę
Co dzieje się z nieznanymi blokami extLst przy zapisie
HotXLS przechwytuje każdy blok <ext> na poziomie arkusza, którego nie modeluje natywnie, i odtwarza go wewnątrz extLst zapisanego arkusza. Bloki, które modeluje, są parsowane do typowanych obiektów i z nich odbudowywane: grupy miniwykresów trafiają do SparklineGroups, rozszerzenie walidacji danych x14 jest czytane do kolekcji walidacji, a listy fragmentatorów są emitowane ponownie przez model fragmentatorów. Cała reszta ląduje, jeden fragment XML na blok, w tylko-do-odczytu liście napisów RawWorksheetExts na każdym TXLSXWorksheet, co znaczy, że test może obejrzeć dokładnie to, co zostanie przeniesione
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)); // tag otwierający pokazuje uri
// Deklaracje przestrzeni nazw, które fragmenty pożyczyły z korzenia <worksheet>
WriteLn(Sheet.RawExtNamespaceDecls);
finally
Book.Free;
end;
end;
Przechwytywanie działa ze strumienia zdarzeń XML, bo czytnik strumieniowy podaje elementy, tekst i tagi kończące, ale nie bajtowe offsety w źródle. Każde nieznane poddrzewo jest odbudowywane z tych zdarzeń, w miarę jak przechodzą. Naiwny licznik głębokości psuje się tutaj: zwiększa się na każdym tagu otwierającym i zmniejsza na każdym zamykającym, a samozamykające się dziecko, jak <x14:cfvo type="min"/>, przychodzi jako jedno zdarzenie otwarcia oflagowane jako puste, bez końcowego taga do następowania. Policz je jako otwarty element, a licznik nigdy nie wróci do zera, więc przechwytywanie połknie resztę arkusza. Pętla przechwytywania w HotXLS zwiększa głębokość tylko dla taga otwierającego, który nie jest pusty, a pusty <ext/> jest od razu zapisany jako jednowierszowy fragment
Odbudowa ze zdarzeń ma widoczny efekt uboczny. Cytowanie atrybutów, biały znak między elementami i wybór między <a></a> a <a/> wracają znormalizowane, więc fragment jest równoważny znaczeniowo z oryginałem, ale nie identyczny bajt po bajcie. Excel parsuje XML; nie porównuje bajtów. Narzędzie różnicujące porównujące tekst oflaguje jednak zmianę i warto to wiedzieć, zanim ktoś zgłosi ją jako regresję
Przestrzenie nazw to druga rzecz, która może pójść źle z odtworzonym fragmentem. Excel zwykle deklaruje potrzebne prefiksy na samym elemencie <ext>, co czyni fragment samowystarczalnym, ale blok może też oprzeć się na prefiksie takim jak x14ac albo xr, zadeklarowanym raz na korzeniu źródłowego <worksheet>. Odtwórz taki fragment do arkusza bez deklaracji, a zapisany XML nie będzie poprawny namespace'owo. HotXLS skanuje każdy przechwycony fragment pod kątem używanych, a niezadeklarowanych prefiksów, zapisuje pasujące deklaracje ze źródła w RawExtNamespaceDecls i wpisuje je na korzeń zapisanego arkusza. Ponieważ fragmenty są zwykłymi napisami, duplikowanie arkusza wewnątrz lub między skoroszytami może przenieść je też na nowy arkusz
Zapisywanie calcChain.xml, żeby Excel ufał twoim formułom
HotXLS zapisuje xl/calcChain.xml (część Calculation Chain, ECMA-376 Part 1, §12.3.1) za każdym razem, gdy zapisywany skoroszyt zawiera co najmniej jedną komórkę z formułą, razem z jego nadpisaniem typu zawartości i relacją skoroszytu. Każdy wpis to element <c r="D10" i="1"/>: referencja komórki plus indeks arkusza numerowany od 1, który pisarz emituje przy każdym wpisie, choć schemat pozwala serii wpisów na tym samym arkuszu go pominąć. Jawność jest prostsza i równie poprawna
Kolejność zależy od tego, co skoroszyt już wie. Gdy graf zależności formuł istnieje i jest aktualny — czyli stan tuż po Recalculate — łańcuch idzie pełną kolejnością topologiczną: każda formuła po komórkach, od których zależy, z członkami odwołań cyklicznych doklejonymi na końcu, więc łańcuch nadal wymienia każdą komórkę z formułą. Gdy graf jest nieaktualny albo nigdy nie powstał, komórki z formułami są wymieniane w kolejności dokumentu, arkusz po arkuszu. Oba są legalne. Uwagi implementacyjne Microsoftu dla tego formatu, [MS-XLSX], opisują łańcuch jako podpowiedź, którą Excel sprawdza i porządkuje podczas liczenia, więc kompletna lista w dowolnej kolejności wczytuje się czysto
Book.Open('model.xlsx');
Book.Sheets[1].Cells[10, 4].Formula := '=SUM(D2:D9)';
// Zapis tutaj wymienia komórki formuł w kolejności dokumentu, bo zmiana
// formuły zniweczyła graf zależności.
Book.Recalculate; // odbudowuje graf i odświeża buforowane wartości
Book.SaveAs('model-out.xlsx');
// calcChain.xml idzie teraz kolejnością zależności: D10 po D2:D9
SaveAs nie buduje grafu z własnej inicjatywy. Pełna budowa zależności znaczy rozwiązywanie każdej referencji w każdej formule, co na dużym modelu to realna praca, o którą wywołujący, który chciał tylko zapisać plik, nigdy nie prosił. Jeśli buforowane wartości w wyjściu są dla ciebie ważne, a zwykle są dla wszystkiego, co system downstream czyta bez otwierania Excela, i tak wywołaj Recalculate przed zapisem; łańcuch w kolejności zależności przychodzi przy okazji za darmo
Po co emitować część, którą Excel traktuje jako doradczą? Bo jej brak rzuca się w oczy. Heurystyki naprawcze, przeglądarki firm trzecich i narzędzia różnicujące oczekują, że skoroszyt z formułami niesie łańcuch obliczeń, a pakiet bez niego wygląda niepodobnie na nic, co sam Excel produkuje. Zapisanie poprawnego łańcucha trzyma wyjście w kształcie, na którym reszta ekosystemu była ćwiczona, i kosztuje jeden przebieg po komórkach z formułami
Gdzie kończy się bezstratny round-trip
HotXLS nie kopiuje całego pakietu bajt po bajcie i wyjścia nie należy oceniać w ten sposób. XML arkusza, styles.xml, wspólne napisy i część skoroszytu są regenerowane z sparsowanego modelu, więc są wierne treściowo, ale nie identyczne binarnie z wejściem. Same lokalne nagłówki ZIP niosą świeże znaczniki czasu. Przechwycone fragmenty <ext> wracają znormalizowane, jak opisano wyżej. ThemeMajorFont i ThemeMinorFont omijają zachowany motyw, a nadpisania ThemeColor wchodzą do niego slot po slocie
Sieć zachowywania ma zdefiniowany kształt: funkcje modelowane natywnie przez silnik, jak miniwykresy i rozszerzona walidacja danych, które są parsowane i przepisywane; obca zawartość <ext> na poziomie arkusza, która jest odtwarzana; oraz część motywu, która jest niesiona tak, jak została przechwycona. Projekty VBA i zewnętrzne odwołania do skoroszytów przejeżdżają przez zapis tym samym podejściem trzymaj-co-nie-modelujesz, opisanym w powiązanym artykule o zachowywaniu VBA i odnośników zewnętrznych, a właściwości dokumentu w docProps mają własne API odczytu i zapisu. Część z egzotycznego dodatku, która nie jest ani modelowana, ani wewnątrz punktu rozszerzeń, siedzi poza trzema mechanizmami opisanymi tutaj
Kontrola, która ma znaczenie, używa twoich własnych plików. Otwórz bogaty w funkcje produkcyjny szablon, zmień jedną wartość, zapisz, rozpakuj oba pakiety i porównaj część po części. Spodziewaj się różnic w edytowanym arkuszu, w styles.xml i w formatowaniu atrybutów wewnątrz extLst; część motywu powinna zgadzać się z wejściem, elementy <ext> powinny wymieniać te same wartości uri, a calcChain.xml powinien nazywać każdą komórkę z formułą. Wszystko poza tą listą warto gonić, zanim szablon wejdzie do produkcji
Zachowywanie motywu, odtwarzanie obcego extLst i wyjście łańcucha obliczeń są częścią silnika XLSX w HotXLS Delphi Excel Component; strona produktu wymienia resztę tego, co on czyta i zapisuje dla projektów Delphi i C++Builder