1. Введение
В процессе разработки проекта была реализована функция загрузки данных, которые пользователь просмотрел на экране, в Excel. Это было не просто экспортирование данных, апредоставление результатов, максимально идентичных тем, что пользователь видит на экране,это было требованием.
Например, если цвет текста изменяется в зависимости от значения состояния или определенная строка выделяется, или если на заголовке применяется отдельный цвет фона, то визуальные элементы на браузере должны поддерживаться и в Excel.
Сначала я думал, что если просто вызвать метод exportDataAsExcel() от ag-Grid, то будет создан такой же результат, как на экране. Но на самом деле стиль не сохранялся, так как способ рендеринга браузера и способ работы экспорта в Excel отличаются друг от друга. Я хотел бы поделиться своим опытом и процессом решения этой проблемы. Эта статья написана на основе окружения ag-Grid v28.0.2, и некоторые действия или поддерживаемые функции могут варьироваться в зависимости от версии.
2. Причина, по которой данные на экране и в Excel были разными: не было применен `valueFormatter`
[Проблема]
Некоторые столбцы отображали текст, преобразованный с помощью `valueFormatter`, вместо оригинальных значений, взятых из БД, для удобства чтения пользователем.
Когда я выполнил экспорт в Excel в этом состоянии, данные, которые на экране выглядели как 'Одобрено', в файле Excel отображались как исходные данные 'Y'.
[Решение]
С помощью опции Excel Export от ag-Grid, `processCellCallback`, я добавил колбек-логику для обработки значений, чтобы вернуть финальный текст, к которому применен valueFormatter, перед тем как записать значения в файл Excel.
С помощью этого процесса я смог сохранить интуитивный текст, который пользователь видит на экране, в Excel вместо внутреннего ключа данных.
3. Причина, по которой CSS не применяется в Excel
[Проблема]
Чтобы изменить цвет текста ячейки на красный при определенных условиях в браузере, я использовал настройку `cellClass`, как показано ниже.
На экране все работало нормально благодаря CSS-скрипту (`.text-red { color: red; }`), однако в загруженном файле Excel никаких стилей не было применено.
[Анализ причин]
Экспортный движок Excel ag-Grid не может считывать отрендеренную CSS среду браузера. Вместо этого он построен на основе внутреннего объекта `excelStyles`, который ссылается на формат XML-стилей, уникальный для Excel.
То есть, использование только CSS для экрана не привело к автоматическому применению стиля Excel. Для решения этой проблемы был применен способ сопоставления между excelStyles и классом ячейки, который будет описан в следующем разделе.
4. структура взаимодействия excelStyles с cellClass и cellClassRules
[Способ решения]
Чтобы решить проблему, мы объявили настройки `excelStyles`, которые будут использоваться внутри Grid. Ключевое значение в том, что CSS классы и идентификаторы `excelStyles` сопоставляются 1:1Это то, что нужно делать.
[что я узнал]
В версии 28.0.2, если строка класса, возвращаемая функцией `cellClass`, соответствует классу, активированному по правилам `cellClassRules`, то в конечном итоге строка классов, присвоенная ячейке, совпадает с id excelStyles, Excel-движок автоматически распознает это. Благодаря этому свойства, такие как цвет шрифта и жирность, корректно кодируются, и удалось последовательно объединить структуру CSS экрана и структуру стиля Excel.
5. Процесс применения стиля заголовка и специальный уникальный идентификатор (header)
[Ситуация с проблемой]
В процессе стилизации области заголовка (Header) мы столкнулись с неожиданной проблемой. Сначала я думал, что можно просто определить и сопоставить пользовательский идентификатор стиля так же, как и в случае с успешным общим методом ячеек.
CSS для экрана работал нормально, но при загрузке Excel я заметил, что никакие стили не применились к заголовку. Сначала я думал, что это просто опечатка или ошибка в настройках, и несколько раз проверял и тестировал код, но результат оставался прежним.
[Анализ причины и решение]
В официальной документации я обнаружил, что в механизме экспорта Excel ag-Grid область заголовка обрабатывается очень особым образом. Заголовок не распознает произвольно заданный разработчиком пользовательский идентификатор (`blue-header`), а использует название зарезервированного ag-Grid уникального ID `header`, которое структурируется обязательно.
В соответствии с этим я изменил настройку excelStyles, чтобы она соответствовала официальной спецификации, как показано ниже.
[Что стало ясным]
После внесения изменений я смог подтвердить, что стиль заголовка корректно отображается в Excel-файле. Этот процесс помог мне понять, что общая область ячеек и область заголовка работают совершенно по разным механизмам внутреннего парсинга. Ключевым моментом было следовать встроенным правилам, установленным фреймворком (`id: "header"`), а не произвольному привязыванию классов при управлении стилем заголовка.
Однако вышеуказанная информация основана на ag-Grid версии 28.0.2, и в версиях 29 и выше структура внутреннего механизма Excel Export может быть изменена, поэтому я рекомендую также проверить официальную документацию.
6. Заключение
Этот опыт снова заставил меня осознать важность понимания механизма работы библиотеки и выбора подходящего решения, соответствующего проектной ситуации, а не просто реализации функциональности.
Источники и справочные материалы
* Официальная документация ag-Grid – Экспорт в Excel: https://www.ag-grid.com/react-data-grid/excel-export/
* Официальная документация ag-Grid – Стили экспорта Excel: https://www.ag-grid.com/react-data-grid/excel-export-styles/
* Официальная документация ag-Grid – Стили ячеек (`cellClass`, `cellClassRules`): https://www.ag-grid.com/react-data-grid/cell-styles/
JJ