Техническая статья

Round-trip XLSX в Delphi: theme, extLst, calcChain

Биллинговое задание открывает клиентский шаблон, пишет 42750 в B3 и сохраняет. Разверните потом оба пакета и сравните — список изменений куда длиннее одной ячейки: xl/theme/theme1.xml теперь держит стандартную палитру Office вместо клиентской бирюзы и грифеля, <extLst> в самом низу XML листа потерял группу спарклайнов и более новое правило условного форматирования, а xl/calcChain.xml исчез целиком. Excel открывает результат, предлагает восстановление, и фирменные цвета пропали. Код тронул одну ячейку. Всё остальное изменилось, потому что сохранение пересобрало пакет из того, что было известно модели в памяти, а три части типичного шаблона лежат за пределами того, что табличная модель обычно хранит

Три механизма за беспроигрышным круговым путём XLSX в HotXLS в Delphi: xl/theme/theme1.xml, кешируемый сырыми байтами и записываемый назад без изменений, не считая перекрытий слотов через ThemeColor; чужие блоки extLst, захватываемые из XML-событий и проигрываемые заново; и свежий соответствующий спецификации calcChain.xml, выдающийсяся при каждом сохранении с формулами
Каждая сохранённая часть идёт своим путём через сохранение — дословные байты темы, переигрывание extLst на уровне событий и регенерированная цепочка вычислений, — тогда как XML листа и стили перестраиваются из модели

Почему правка одной ячейки перезаписывает весь пакет XLSX

Файл .xlsx — это ZIP из XML-частей: xl/workbook.xml, по xl/worksheets/sheetN.xml на каждый лист, xl/styles.xml, xl/sharedStrings.xml, тема, цепочка вычислений и все рисунки, таблицы и кэши сводных, что книга несёт. У библиотеки, которая читает значения и формулы в объекты и при сохранении регенерирует каждую часть из этих объектов, есть одно слабое место. Всё, для чего в объектной модели нет слота, в память не попадает никогда, поэтому регенерированная часть выходит без него. Никому не приходится удалять спарклайны — им просто негде жить между Open и SaveAs

ECMA-376 предвидел половину этого. SpreadsheetML резервирует extLst (ECMA-376 Part 1, §18.2.10 для элемента уровня книги, с соответствующими элементами на листах, в стилях и условном форматировании) как склад будущих возможностей. Более новый производитель заворачивает каждую возможность в элемент <ext>, чей атрибут uri называет возможность, а от более старого потребителя ожидается, что он донесёт то, чего не понимает. Спарклайны, списки срезов, новые опции гистограмм и наборов значков, расширенная проверка данных — всё это ездит так в файлах, которые Excel пишет сегодня. Выбрасывание неизвестных блоков <ext> ломает контракт прямой совместимости, вокруг которого построен формат, а повреждение всплывает, только когда клиент заново открывает файл в Excel

Тема и цепочка вычислений отказывают по разным причинам, поэтому каждой нужно своё обращение. Дальше в статье — как HotXLS обходит все три, что вызывающий код на Delphi может наблюдать и проверить и где гарантия заканчивается

Как в Delphi сохранить нетронутым пользовательский theme1.xml

HotXLS сохраняет тему книги, удерживая оригинальные байты xl/theme/theme1.xml из открытого пакета и записывая эту часть как есть при SaveAs. Часть темы (ECMA-376 Part 1, §14.2.7) — это DrawingML: цветовая схема с двенадцатью слотами, схема шрифтов, схема форматов из заливок, линий и эффектов. Стили ячеек ссылаются в неё через <color theme="4"/> и подобные ссылки, так что табличному движку нужно лишь разрешать слоты, а не понимать градиенты или стили эффектов. Регенерация одной и той же темы Office при каждом сохранении — это ровно то, что превращает клиентскую бирюзу в офисный синий. Книга, созданная с нуля и не имеющая темы, вместо этого получает встроенную тему Office

HotXLS кеширует сырые байты xl/theme/theme1.xml при открытии и пишет их назад без изменений при сохранении, заменяя только перекрытые через ThemeColor цветовые слоты, а библиотека с пересборкой из модели регенерирует стандартную тему Office и отщёлкивает фирменные цвета клиента обратно
Кэширование theme1.xml дословно не требует никакой модели темы вовсе, а ThemeMajorFont с ThemeMinorFont лишь оформляют книги, не несущие захваченной темы

Бытовому случаю не нужно никакого кода для темы вообще. Заметьте индекс листа: Sheets в XLSX-движке считается от 1, а Cells[3, 2] — строка 3, колонка 2, то есть B3

var
  Book: TXLSXWorkbook;
begin
  Book := TXLSXWorkbook.Create;
  try
    Book.Open('branded-invoice.xlsx');
    Book.Sheets[1].Cells[3, 2].Value := 42750.00;  // та самая правка
    Book.SaveAs('branded-invoice-out.xlsx');
    // xl/theme/theme1.xml в выходном файле несёт собственную тему шаблона
  finally
    Book.Free;
  end;
end;

Сырые байты — максимальная точность, какая возможна для такой части: без разбора, без повторной сериализации, нечему расползаться. Когда сохранение пишет Strict OOXML вместо переходного диалекта, захваченная тема проходит через транслятор пространств имён, а не копируется, потому что байтовая копия оставила бы переходные URI пространств имён внутри Strict-пакета

Ловушка прячется на стороне API. TXLSXWorkbook выставляет наружу ThemeMajorFont и ThemeMinorFont, и после Open они отчитываются шрифтами заголовков и основного текста, разобранными из схемы шрифтов шаблона. Присваивать их выглядит естественным способом поменять шрифт, но лепят они только встроенную тему Office, которую получают новые книги. В книге, пришедшей со своей темой, побеждает захваченная часть, и эти два сеттера не меняют в сохранённом файле ничего. С цветами иначе: ThemeColor[Slot] адресует двенадцать слотов clrScheme, и перекрытие записывается в сохранённую тему заменой цвета ровно одного слота, не трогая схему шрифтов, схему форматов и никакие расширения темы

Book.Open('branded-invoice.xlsx');
// На сохранённый файл не влияет: preserved-тема шаблона побеждает
Book.ThemeMajorFont := 'Segoe UI Semibold';
// В файл попадает: внутри theme1.xml меняется только слот accent1
Book.ThemeColor[xlsxThemeAccent1] := $FF0F7B6C;  // $AARRGGBB
Book.SaveAs('rebranded.xlsx');

Этот разлом намеренный. Перекрытие цвета — узкая, хорошо определённая правка одного элемента, так что остальная часть дизайнерской темы может остаться ровно прежней. Переписывание схемы шрифтов зацепило бы списки шрифтов по письменностям, которые дата-ориентированный API не выражает хорошо. Если шаблону нужен новый шрифт — поменяйте его в Excel и отгрузите новый шаблон; так тема остаётся в руках тех, кто владеет брендом

Что происходит с неизвестными блоками extLst при сохранении?

HotXLS захватывает каждый блок <ext> уровня листа, который не моделирует нативно, и переигрывает его внутри extLst сохранённого листа. Блоки, которые он моделирует, разбираются в типизированные объекты и восстанавливаются из них: группы спарклайнов уходят в SparklineGroups, расширение проверки данных x14 читается в коллекцию проверки данных, а списки срезов переиспускает модель срезов. Всё остальное складывается — один XML-фрагмент на блок — в список строк RawWorksheetExts только для чтения на каждом TXLSXWorksheet, так что тест может разглядеть ровно то, что понесётся дальше

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)); // открывающий тег показывает uri
    // Объявления пространств имён, одолженные фрагментами у корня <worksheet>
    WriteLn(Sheet.RawExtNamespaceDecls);
  finally
    Book.Free;
  end;
end;

Захват работает из потока XML-событий, потому что потоковый читатель выдаёт элементы, текст и закрывающие теги, но никак не байтовые смещения в источнике. Каждое неизвестное поддерево собирается заново из этих событий по мере их прохода. Наивный счётчик глубины здесь ломается: он наращивается на каждом открывающем теге и уменьшается на каждом закрывающем, а самозакрывающийся ребёнок вроде <x14:cfvo type="min"/> приезжает одним событием открытия с пометкой пустого и без закрывающего тега вслед. Сочтёте его открытым элементом — счётчик никогда не вернётся в ноль, и захват проглотит остаток листа. Цикл захвата в HotXLS наращивает глубину только для непустого открывающего тега, а пустой <ext/> складывается немедленно однострочным фрагментом

У пересборки из событий есть видимый побочный эффект. Кавычки атрибутов, пробелы между элементами и выбор между <a></a> и <a/> возвращаются нормализованными, так что фрагмент эквивалентен оригиналу по смыслу, но не байт в байт. Excel разбирает XML, а не сравнивает байты. Однако инструмент diff, сравнивающий текст, пометит изменение — и об этом стоит знать до того, как кто-нибудь оформит его как регрессию

Пространства имён — второе, что может пойти наперекосяк у переигранного фрагмента. Excel обычно объявляет нужные префиксы на самом элементе <ext>, что делает фрагмент самодостаточным, но блок может и опираться на префикс вроде x14ac или xr, объявленный один раз на корне исходного <worksheet>. Переиграйте такой фрагмент в лист без объявления — и сохранённый XML не будет well-formed по пространствам имён. HotXLS сканирует каждый захваченный фрагмент на префиксы, которые он использует, но не объявляет, записывает соответствующие объявления из источника в RawExtNamespaceDecls и пишет их на корне сохранённого листа. Поскольку фрагменты — простые строки, дублирование листа внутри одной книги или между книгами тоже может донести их до нового листа

Запись calcChain.xml для корректной обработки формул в Excel

HotXLS пишет xl/calcChain.xml (часть Calculation Chain, ECMA-376 Part 1, §12.3.1) всякий раз, когда сохранённая книга содержит хотя бы одну формульную ячейку, вместе с перекрытием типа содержимого и отношением книги. Каждая запись — элемент <c r="D10" i="1"/>: ссылка на ячейку плюс индекс листа от 1, который райтер выдаёт в каждой записи, хотя схема позволяет серии записей по одному листу его опускать. Явное проще и столь же валидно

Порядок зависит от того, что книга уже знает. Когда граф зависимостей формул существует и актуален — состояние сразу после Recalculate, — цепочка следует полному топологическому порядку: каждая формула после ячеек, от которых зависит, а члены циклических ссылок приставлены в конец, так что цепочка всё равно перечисляет каждую формульную ячейку. Когда граф устарел или не строился вовсе, формульные ячейки перечисляются в порядке документов, лист за листом. Оба варианта легальны. Заметки Microsoft по реализации формата, [MS-XLSX], описывают цепочку как подсказку, которую Excel проверяет и переупорядочивает при вычислении, так что полный список в любом порядке загружается чисто

HotXLS выдаёт xl/calcChain.xml в топологическом порядке, когда Recalculate построил граф зависимостей, и в порядке документов иначе; Excel трактует любой полный список как подсказку и переупорядочивает его при загрузке
Оба порядка остаются легальными, потому что Excel перепроверяет цепочку при загрузке, а HotXLS никогда не навязывает полную постройку графа зависимостей внутри SaveAs
Book.Open('model.xlsx');
Book.Sheets[1].Cells[10, 4].Formula := '=SUM(D2:D9)';
// Сохранение прямо сейчас перечислит формульные ячейки в порядке
// документов: правка формулы инвалидовала граф зависимостей
Book.Recalculate;   // перестраивает граф и обновляет кэшированные значения
Book.SaveAs('model-out.xlsx');
// calcChain.xml теперь следует порядку зависимостей: D10 после D2:D9

SaveAs не строит граф по собственной инициативе. Полная постройка зависимостей означает разрешение каждой ссылки в каждой формуле, что на большой модели — настоящая работа, о которой вызывающий, хотевший просто записать файл, не просил. Если кэшированные значения в выходном файле вам важны — а они обычно важны для всего, что нижестоящая система читает, не открывая Excel, — всё равно вызовите Recalculate перед сохранением; цепочка в порядке зависимостей приедет бесплатно

Зачем выдавать часть, которую Excel считает консультативной? Потому что её отсутствие бросается в глаза. Эвристики восстановления, сторонние просмотрщики и diff-инструменты — все ожидают от формульной книги цепочки вычислений, и пакет без неё выглядит не похоже ни на что из того, что производит сам Excel. Запись валидной цепочки держит вывод внутри формы, под которую остальная экосистема обкатана, и стоит одного прохода по формульным ячейкам

Где заканчивается round-trip без потерь

HotXLS не копирует весь пакет байт в байт, и вывод не стоит так судить. XML листа, styles.xml, общие строки и часть книги регенерируются из разобранной модели, так что они верны по содержимому, но не двоично идентичны входу. Одни локальные заголовки ZIP несут свежие метки времени. Захваченные фрагменты <ext> возвращаются нормализованными, как описано выше. ThemeMajorFont и ThemeMinorFont остаются вне сохранённой темы, тогда как перекрытия ThemeColor уходят в неё слот за слотом

Сохраняющая сеть имеет очерченную форму: возможности, которые движок моделирует нативно, вроде спарклайнов и расширенной проверки данных, — разбираются и переписываются; чужое содержимое <ext> уровня листа — переигрывается; и часть темы — переносится как захваченная. Проекты VBA и внешние ссылки на книги проезжают сохранение на том же подходе «хранить то, что не моделируешь», о них рассказано в сопутствующей статье о сохранении VBA и внешних ссылок, а у свойств документа в docProps есть собственный API чтения-записи. Часть из экзотической надстройки, которая ни моделируется, ни сидит в точке расширения, лежит за пределами трёх разобранных здесь механизмов

Проверка, которая имеет значение, использует ваши собственные файлы. Откройте богатый возможностями производственный шаблон, поменяйте одно значение, сохраните, разверните оба пакета и сравнивайте часть за частью. Ждите отличий в отредактированном листе, в styles.xml и в оформлении атрибутов внутри extLst; часть темы должна совпасть со входом, элементы <ext> должны перечислить те же значения uri, а calcChain.xml должен назвать каждую формульную ячейку. Всё за пределами этого списка стоит вылавливать, прежде чем шаблон уйдёт в производство

Сохранение темы, переигрывание чужих extLst и вывод цепочки вычислений — часть XLSX-движка в HotXLS Delphi Excel Component; остальное из того, что он читает и пишет для проектов Delphi и C++Builder, перечислено на странице продукта