Перенос возможностей XLSX
English · Русский
Поддерживается XLSX с пространством имён SpreadsheetML Transitional. Библиотека копирует архив шаблона, генерирует данные листов и переносит метаданные отдельным потоковым проходом. В памяти находятся метаданные и одна строка XML, а не весь лист. Части архива, на которые ссылаются сохранённые метаданные, остаются из шаблона.
| Возможность | Подстановка без изменения структуры | Вставка, пропуск или сдвиг ячеек |
|---|---|---|
| Условное форматирование | Сохраняются исходные правила, sqref, приоритеты и индексы dxf; таблица dxfs переносится без изменения индексов |
Диапазоны и формулы правил остаются исходными; диагностика, отказ в строгом режиме |
| Проверки данных | Сохраняются все атрибуты, формулы, дочерние узлы, параметры контейнера и исходные расширения. Новые обычные проверки Writer добавляются к исходным | Диапазоны и формулы не пересчитываются; диагностика, отказ в строгом режиме |
| Автофильтр | Сохраняются диапазон и дочерние фильтры; атрибуты, заданные Writer, имеют приоритет | Диапазон автоматически не расширяется; диагностика, отказ в строгом режиме |
| Таблицы Excel | Сохраняются tableParts, XML таблиц, стили и relationships |
Диапазоны таблиц, фильтры и вычисляемые колонки не перестраиваются; диагностика, отказ в строгом режиме |
| Гиперссылки | Сохраняются исходный XML и relationships, включая внешние адреса | Адреса ячеек не пересчитываются; диагностика, отказ в строгом режиме |
| Имена диапазонов и области печати | workbook.xml сохраняется из шаблона |
Формулы имён остаются исходными; диагностика, отказ в строгом режиме |
| Изображения и примечания | Сохраняются XML привязок, изображения, VML, комментарии и relationships | Привязки и адреса примечаний остаются исходными; диагностика, отказ в строгом режиме |
| Параметры печати | Сохраняются исходные узлы; изменения атрибутов через Writer имеют приоритет. Колонтитулы сохраняют текст и корректно читают XML-флаги false/0 |
Области печати и разрывы не пересчитываются |
| Виды листов | Сохраняется исходный sheetViews, включая выделения и закрепления |
Адреса выделений и закреплений не пересчитываются |
| Объединения | Восстанавливаются по строкам образца | Горизонтальные объединения сдвигаются и сужаются при удалении ячеек. Удаление начала убирает объединение. Операция, затрагивающая объединение из нескольких строк, отклоняется исключением |
| Палитры и стили таблиц | Сохраняются исходные colors, tableStyles и расширения стилей |
Структурного пересчёта нет |
Расширения extLst |
Переносятся как исходный XML с пространствами имён | Семантика расширений не интерпретируется; при структурных изменениях выдаётся диагностика |
| Неизвестные элементы верхнего уровня | Пропускаются с записью в диагностику | В строгом режиме сохранение отклоняется |
При одновременном наличии исходных и новых условных правил требуется согласовать приоритеты. При конфликте исходного и нового extLst сохраняется исходное расширение. Оба случая отражаются в диагностике; строгий режим отклоняет сохранение.
Диагностика и строгий режим
$excel = Excel::template($template, $output, ['strict_metadata' => true]);
$excel->sheet()->fill(['{{NAME}}' => 'Отчёт'])->transferRows();
$excel->save();
$diagnostics = $excel->metadataDiagnostics();
metadataDiagnostics() возвращает массив записей sheet, code, message, заполненный при последней генерации архива. sheet содержит путь XML-части, например xl/worksheets/sheet1.xml. Сообщения message записываются на английском языке. Ошибки предварительной проверки пути не обновляют отчёт метаданных.
По умолчанию strict_metadata равен false: файл сохраняется с перечисленными ограничениями. strict_metadata=true вызывает исключение при обнаруженном неподдерживаемом переносе. Проверка выполняется до размещения результата: существующий выходной файл сохраняется при отказе. Строгий режим останавливается на первой проблеме, поэтому отчёт может быть неполным.
| Код | Значение | Поведение обычного режима |
|---|---|---|
unsupported-node |
Неизвестный элемент верхнего уровня листа | Элемент пропускается |
unmapped-ranges |
Структура изменена, а диапазоны метаданных или привязки не пересчитаны | Метаданные сохраняют координаты шаблона |
unmapped-defined-names |
Структура изменена, в книге есть определённые имена | Формулы имён остаются исходными |
rule-conflict |
Есть и исходные, и новые условные правила | Обе группы сохраняются без согласования приоритетов |
extension-conflict |
Есть и исходный, и новый extLst |
Приоритет получает исходный extLst |
Пример обработки отказа:
use avadim\FastExcelTemplator\Exception;
try {
$excel->save();
} catch (Exception $exception) {
foreach ($excel->metadataDiagnostics() as $item) {
error_log($item['sheet'] . ': ' . $item['code'] . ' — ' . $item['message']);
}
throw $exception;
}
SheetTemplate::hasStructuralChanges() показывает консервативный признак структурных операций. Вставки, пропуски и удаления могут вызвать отказ даже тогда, когда конкретный диапазон не затронут. Имена книги проверяются целиком. Низкоуровневые изменения напрямую через Writer не отслеживаются полностью. Строгий режим не заменяет проверку произвольных сторонних расширений XLSX.
Изменение содержимого и ссылок
RowTemplate::setValue('A', null) очищает содержимое и прежнюю формулу, сохраняя оформление. Ноль, false и пустая строка являются отдельными допустимыми значениями.
removeCell() и removeCells() сдвигают оставшиеся ячейки текущей строки. Они не удаляют колонку книги и не переписывают ссылки на неё во всех листах. Относительные ссылки переносимой формулы перебазируются относительно нового адреса; абсолютные остаются прежними. Ссылки других ячеек автоматически не перестраиваются.
Сохранение поверх исходного шаблона запрещено, в том числе через относительный путь, регистровый алиас Windows или символическую ссылку. Если выходной путь является жёсткой ссылкой на шаблон, размещение готового результата заменяет только эту ссылку; исходный шаблон сохраняется. Режим без перезаписи отклоняет существующие ссылки, включая символическую ссылку без цели.
Проверки и разработка
В тестах есть исходный файл Excel и файл, пересохранённый LibreOffice: tests/fixtures/. Проверяются XML, порядок узлов, стили, связанные части архива, изображения, примечания и обработка листов в обратном порядке. Офисные приложения для запуска PHPUnit не требуются.
composer test
composer analyse
CI проверяет Windows и Ubuntu, PHP 7.4 и 8.0–8.5. Минимальные зависимости отдельно проверяются на PHP 7.4; остальные задания устанавливают актуальные допустимые версии. PHPStan работает на уровне 1 с целевой версией PHP 7.4, без baseline и подавлений ошибок. Новый внутренний обработчик метаданных использует strict_types; массовое изменение правил преобразования типов существующего API не выполняется.
Проверки ZIP остаются в локальном TemplateWriter: минимальная зависимость Writer 6.16.1 их не обеспечивает. Для переноса в Writer необходимо проверять результаты открытия, замены элементов и закрытия ZIP, закрывать архив при исключениях и передавать ошибку вызывающему коду. Новая версия Writer для текущей реализации не требуется; vendor/ не изменяется.