Преобразование JSON в Excel (XLSX) в Angular

Как разработчик, вы ежедневно сталкиваетесь с новыми задачами и требованиями бизнес-логики. Часто веб-приложению нужно подготовить экспорт данных — например, преобразовать JSON из API в отчёт в формате Excel (XLSX) для менеджеров, бухгалтерии или аналитиков.

В этом руководстве подробно показано, как настроить библиотеку xlsx в Angular‑проекте, реализовать сервис экспорта и сохранить JSON в аккуратную таблицу .xlsx. Также приведены альтернативы, рекомендации по совместимости и контрольные сценарии для приёмки.

Что такое библиотека XLSX

XLSX (часто называемая SheetJS) — это популярная JavaScript‑библиотека для чтения и записи табличных форматов, включая XLSX. Она позволяет:

• конвертировать JSON в worksheet (лист) и сохранять в файл .xlsx;
• читать Excel‑файлы и преобразовывать их в JSON;
• работать с несколькими листами, форматами ячеек и базовыми стилями.

Коротко: если нужно экспортировать или импортировать табличные данные в браузере — xlsx покрывает большинство сценариев.

Перед началом: требования и локальная среда

Важно: на машине должен быть установлен Node.js. Для работы с Angular выполните глобальную установку CLI, если ещё не сделали:

npm install -g @angular/cli

Создайте новый проект Angular (или откройте существующий):

ng new your-angular-app
cd your-angular-app

Запустите локальный сервер разработки:

ng serve --o

Чтобы установить библиотеку xlsx в проект:

npm install xlsx --save

Совет: для более удобной загрузки файлов можно дополнительно установить file-saver:

npm install file-saver --save

Создание сервиса экспорта Excel

Сгенерируйте сервис через Angular CLI:

ng generate service ExcelService

По умолчанию будет создан файл src/app/excel-service.service.ts (имя может отличаться в зависимости от версии CLI). Обновите содержимое сервиса, чтобы он экспортировал JSON в XLSX:

import { Injectable } from '@angular/core';
import * as XLSX from 'xlsx';

const EXCEL_EXTENSION = '.xlsx'; // расширение Excel

@Injectable({ providedIn: 'root' })
export class ExcelService {
  constructor() { }

  public exportToExcel(element: any[], fileName: string): void {
    // генерируем worksheet из JSON
    const ws: XLSX.WorkSheet = XLSX.utils.json_to_sheet(element);
    // создаём новую книгу
    const workbook: XLSX.WorkBook = XLSX.utils.book_new();

    // добавляем лист в книгу и сохраняем файл
    XLSX.utils.book_append_sheet(workbook, ws, 'Sheet1');
    XLSX.writeFile(workbook, `${fileName}${EXCEL_EXTENSION}`);
  }
}

Важно: в параметре element ожидается массив объектов, где ключи объектов станут заголовками столбцов.

Использование сервиса в компоненте

Импортируйте и внедрите сервис в компонент, где будет доступна функция экспорта:

import { Component, OnInit } from '@angular/core';
import { ExcelService } from './excel.service';

@Component({
  selector: 'app-example',
  templateUrl: './example.component.html'
})
export class ExampleComponent implements OnInit {
  apiJsonResponseData: any[] = [];

  constructor(private excelService: ExcelService) { }

  ngOnInit(): void {
    // пример: здесь вы можете получить данные из API и положить в apiJsonResponseData
  }

  exportExcel(): void {
    const fileToExport = this.apiJsonResponseData.map((items: any) => {
      return {
        'User Id': items?.userId,
        'Id': items?.id,
        'Title': items?.title,
        'Body': items?.body
      };
    });

    this.excelService.exportToExcel(
      fileToExport,
      'yourExcelFile-' + new Date().getTime()
    );
  }
}

В шаблоне (HTML) добавьте кнопку для экспорта, например:

Export Data to Excel

После нажатия кнопки браузер предложит скачать файл .xlsx. При открытии вы увидите таблицу со столбцами, соответствующими ключам объектов.

Полезные расширения и продвинутые сценарии

1. Несколько листов в одной книге

const ws1 = XLSX.utils.json_to_sheet(data1);
const ws2 = XLSX.utils.json_to_sheet(data2);
const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, ws1, 'Clients');
XLSX.utils.book_append_sheet(workbook, ws2, 'Orders');
XLSX.writeFile(workbook, 'report.xlsx');

2. Указание порядка столбцов и заголовков

const worksheet = XLSX.utils.json_to_sheet(data, { header: ['Id', 'User Id', 'Title', 'Body'] });

3. Форматирование дат и типов

• Преобразуйте даты в ISO или желаемый формат перед передачей в json_to_sheet.
• Для числовых значений убедитесь, что они являются number, а не строкой — тогда Excel распознает их как числа.

4. Стиль ячеек и формулы

XLSX поддерживает базовые свойства ячеек (тип, формат). Для сложного форматирования и стилей может понадобиться платный/расширенный модуль или альтернативы.

Альтернативные подходы

• FileSaver + XLSX: сохранять бинарный blob через FileSaver, если требуется более гибкое управление загрузкой.
• ngx-export-as: готовые Angular‑обёртки для экспорта (HTML, PDF, XLSX) — удобны для быстрых решений.
• Серверный экспорт: если требуется мощное форматирование или конфиденциальность данных, генерируйте XLSX на бэкенде (Node, Python) и отдавайте готовый файл.

Когда xlsx не подходит: если нужен сложный стиль, защищённые паролем файлы или большие объёмы данных (>100k строк), лучше использовать серверную генерацию.

Ментальные модели и чек‑лист разработчика

Ментальная модель: workbook → sheets → rows → cells. Преобразуйте свои объекты в массивы/объекты, где ключи — заголовки столбцов.

Роль‑based чек‑лист (разработчик / QA / PM):

• Разработчик:
  • Проверить корректность ключей и типов данных.
  • Добавить уникальное имя файла (timestamp).
  • Обработать пустые/неопределённые значения.
• QA:
  • Проверить совпадение заголовков и данных.
  • Убедиться в правильности форматов дат/чисел.
  • Тестировать на малых и больших объёмах данных.
• PM:
  • Уточнить требования к форматированию и структуре отчёта.
  • Согласовать необходимость многостраничных книг.

Критерии приёмки

• Кнопка экспорта вызывает скачивание файла .xlsx.
• Открытый файл содержит листы с ожидаемыми заголовками столбцов.
• Числовые поля открываются как числа, даты — как даты (при соответствующей обработке).
• Имена файлов уникальны (например, содержат timestamp).
• Производительность: экспорт для типичных объёмов данных (<10k строк) выполняется без зависаний UI.

Тесты и сценарии (acceptance)

1. Функциональный тест: при API‑ответе с 10 объектами скачанный файл содержит 10 строк и все заголовки.
2. Пограничный тест: пустой массив → файл с заголовками или с уведомлением об отсутствии данных.
3. Нагрузочный тест: экспорт 50k строк выполняется за приемлемое время или перенаправляется на серверный экспорт.
4. Кросс‑браузер: скачать и открыть файл в Chrome, Firefox и Excel (Windows/Mac).

Совместимость и миграция

• Импорт: используйте import * as XLSX from ‘xlsx’; — это совместимо с TypeScript. В некоторых сборках может потребоваться dynamic import для уменьшения размера бандла.
• SSR (Angular Universal): избегайте прямого использования window/doc в серверном окружении; условно загружайте xlsx только в браузере.
• Версии: следите за несовместимостью API между основными версиями xlsx. Перед обновлением тестируйте экспорты.

Важно: если вы используете Angular CLI с AOT, убедитесь, что типы и импорты корректно обрабатываются.

Быстрый чеклист реализации (шпаргалка)

• Установить xlsx (и file-saver при необходимости).
• Реализовать сервис exportToExcel(element, fileName).
• Преобразовать apiJsonResponseData в массив объектов с нужными заголовками.
• Добавить кнопку в шаблон и обработчик (click).
• Тестировать скачанный файл в Excel.

Примеры полезных сниппетов

• Экспорт нескольких листов:

const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, XLSX.utils.json_to_sheet(dataA), 'DataA');
XLSX.utils.book_append_sheet(workbook, XLSX.utils.json_to_sheet(dataB), 'DataB');
XLSX.writeFile(workbook, 'multi-sheet-report.xlsx');

• Принудительное указание порядка колонок:

const worksheet = XLSX.utils.json_to_sheet(data, { header: ['Id','Name','Amount'] });

Глоссарий (1 строка)

• workbook — объект книги Excel (набор листов).
• worksheet — один лист внутри книги.
• json_to_sheet — функция для конвертации массива объектов в worksheet.

Риски и рекомендации по безопасности

• Не включайте в экспорт чувствительные персональные данные без согласования с политиками конфиденциальности.
• При большом объёме данных рассматривайте серверную генерацию, чтобы не перегружать браузер и не раскрывать весь набор данных на клиенте.

Важно: для GDPR/локальных регуляций согласуйте экпорт персональных данных с ответственным за безопасность.

Когда стоит выбрать серверный экспорт

• Нужно сложное форматирование и стили, защищённые паролем файлы или цифровые подписи.
• Объём данных слишком большой для браузера.
• Необходимо логирование и контроль доступа на уровне сервера.

Резюме

Использование библиотеки xlsx в Angular позволяет быстро и эффективно экспортировать JSON в Excel‑файлы. Реализованный сервис упрощает повторное использование функционала по всему приложению. Варианты расширения включают поддержку нескольких листов, настройку порядка столбцов и серверный экспорт для тяжёлых сценариев. Тестируйте экспорт на реальных объёмах и учитывайте требования к безопасности данных.

Ключевые места для улучшений: добавить локальные форматы дат, предусмотреть падение на серверный экспорт при больших объёмах и оформить шаблоны отчётов для бизнес‑пользователей.