В последнее время всё больше проектов внедряют SpreadJS, чтобы в точности реализовать среду Excel в веб-приложениях. Система, за которую я отвечаю, также использует SpreadJS. Одной из проблем при использовании SpreadJS было то, что «определённый файл вообще не открывался на экране».
На начальном этапе разработки система была обновлена со старой версии до новой, и по мере загрузки пользователями различных файлов нам пришлось столкнуться с необъяснимыми ошибками разбора и ошибками времени выполнения. Причина заключалась в том, что в старой версии для открытия файлов использовался только «open()», тогда как в новой версии были добавлены «import()» и «fromJSON()», в результате чего использовались оба подхода вперемешку.
Основываясь на этом опыте, я систематизировал правильные методы API и корректный пример кода для трёх форматов (.xlsx, .ssjson и .sjs), чтобы никогда больше не повторять эту ошибку.
Причина ошибки: несоответствие типа файла и метода
Основная причина, по которой SpreadJS не удаётся открыть файл, заключается в неправильном соответствии между «физической формой имеющихся у меня данных файла (двоичные данные или объект JSON)» и «механизмом API, используемым для их чтения». Ниже приведены типичные случаи сбоев, с которыми мы столкнулись.
* Случай сбоя 1: исходный двоичный файл .xlsx, выбранный пользователем в браузере, ошибочно обрабатывался как строковые данные и напрямую передавался устаревшему методу fromJSON() → механизм SpreadJS не мог разобрать внутреннюю структуру, из-за чего экран переставал отвечать.
* Случай сбоя 2: текстовые данные .ssjson, загруженные через взаимодействие с серверным API, напрямую передавались в метод import() как объект файла → возникала ошибка загрузки из-за отсутствия заголовка формата двоичного потока.
* Случай сбоя 3: была предпринята попытка открыть новейший большой сжатый формат .sjs с использованием устаревшего подхода модуля ExcelIO.open() → устаревшая библиотека IO не могла декодировать новую сжатую структуру и возвращала ошибку.
Пройдя через эти многочисленные попытки и ошибки, я понял, что ключ к безопасному открытию файлов без сбоев браузера — точно сопоставлять каждое расширение файла с предназначенным для него методом и параметрами.
Матрица соответствия трёх форматов
Если при открытии файла возникает ошибка, в первую очередь проверьте, соблюдались ли приведённые ниже правила матрицы.
-
Если расширение — .xlsx,
* Фактический формат данных: стандартный двоичный файл Microsoft Excel
* Правильный метод обработки: workbook.import()
* Необходимый подключаемый модуль расширения: gc.spread.sheets.io
-
Если расширение — .ssjson,
* Фактический формат данных: текстовый объект JavaScript JSON
* Правильный метод обработки: workbook.fromJSON()
* Необходимый подключаемый модуль расширения: встроен в модуль Core по умолчанию
-
Если расширение — .sjs,
* Фактический формат данных: большой сжатый двоичный формат (Zip), специфичный для SpreadJS
* Правильный метод обработки: workbook.import()
* Необходимый подключаемый модуль расширения: gc.spread.sheets.io
В старой документации и устаревших сообщениях в блогах может быть рекомендовано создать экземпляр GC.Spread.Excel.IO, а затем вызвать excelIo.open(), однако в новейшей архитектуре SpreadJS официальным стандартом и наиболее безопасным подходом является использование интегрированного метода workbook.import()для объекта workbook.
Руководство по реализации открытия файлов различных форматов
Ниже приведён стандартный исходный код реализации для каждого формата. Способ обработки объектов File/Blob в браузере различается в зависимости от особенностей каждого файла.
-
Открытие стандартного файла Excel (.xlsx)
Файл .xlsx — это обычный двоичный файл. Поэтому передайте объект файла, полученный из тега input браузера, напрямую в workbook.import()и обязательно укажите FileType.excelв параметрах.
-
Открытие устаревшего файла JSON (.ssjson)
.ssjsonможет выглядеть как формат файла, но на самом деле это объект javaScript, представляющий состояние SpreadJS, экспортированное в виде текста. Передача его в метод как объекта файла всегда приведёт к ошибке. Сначала необходимо прочитать его как текст с помощью FileReader, затем преобразовать в обычный объект с помощью JSON.parse()и загрузить, используя fromJSON().
-
Открытие новейшего специализированного сжатого файла (.sjs)
.sjs — это специальный сжатый формат, созданный для решения проблем с низкой скоростью загрузки и большим размером файлов крупных таблиц Excel. Структурно это двоичный сжатый файл, такой как .xlsx, поэтому для него используется тот же метод import(), но поскольку внутренняя обработка механизма разбора должна отличаться, для параметра fileType необходимо явно указать значение FileType.sjs.
Заключение
После стандартизации и четкого разграничения правильного метода открытия файлов для каждого формата мы с удивлением обнаружили, что количество ошибок выполнения и сбоев разбора, вызванных несоответствием форматов при загрузке файлов, заметно снизилось по сравнению с прежними показателями. Благодаря значительному снижению частоты ошибок нам удалось сократить ресурсы, затрачиваемые на связанную с ними отладку, и сэкономить значительное количество времени разработки, в конечном итоге добившись ценного результата — существенного повышения стабильности системы.
kina.j