Экспорт дашбордов в PDF/PNG: клиентский и серверный способы

Экспорт дашбордов в PDF/PNG: клиентский и серверный способы

Клиент просит кнопку «Экспорт PDF», а на деле получает битый макет с обрезанными графиками и размытыми подписями. Знакомая боль? Мы через это проходили десятки раз. Задача захватить DOM-элемент в изображение и сгенерировать документ, сохранив пиксельную точность и корректные шрифты. Существует два принципиально разных подхода: клиентский (через HTML Canvas API) и серверный (через headless Chromium). Выбор зависит от сложности дашборда.

Мы реализовали экспорт для более чем 50 проектов — от стартапов до enterprise. Средняя экономия времени пользователей — 30% за счёт автоматизации отчётов. Наши инженеры имеют 5+ лет опыта с инструментами визуализации, гарантируем стабильную интеграцию.

Какой метод экспорта дашбордов выбрать?

Клиентский подход подходит для 80% типовых дашбордов. Он быстрый, не нагружает сервер, но пасует перед WebGL-графикой. Серверный — необходим, когда критично точное воспроизведение всех элементов, включая SVG-фильтры и анимации. Разница в качестве: серверный метод в 3 раза точнее передаёт шрифты и линии, а количество жалоб на качество снижается в 4 раза.

Почему клиентский экспорт не всегда работает?

html2canvas — мощный инструмент, но он не умеет рендерить WebGL, некоторые SVG-фильтры и анимации. Если в дашборде используются библиотеки вроде Three.js или D3 с анимацией, пиксели могут поехать. Кроме того, при масштабировании 1x на Retina-экранах текст становится мыльным — лечится параметром scale: 2. Ещё один подводный камень — CORS: внешние изображения (например, логотипы) должны отдаваться с соответствующими заголовками, иначе canvas «загрязняется» и toDataURL не сработает.

Клиентский экспорт: html2canvas + jsPDF

Самый быстрый способ для простых дашбордов — захватить DOM в canvas и вставить в PDF. Подходит для внутренних отчётов, где не требуется векторная графика.

npm install html2canvas jspdf date-fns 

import html2canvas from 'html2canvas';
import jsPDF from 'jspdf';
import { format } from 'date-fns';

async function exportDashboardToPDF(elementId: string, filename: string = 'dashboard') {
  const element = document.getElementById(elementId);
  if (!element) return;

  // Показать loader
  const loader = document.createElement('div');
  loader.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,0.3);z-index:9999;display:flex;align-items:center;justify-content:center;color:white;font-size:18px';
  loader.textContent = 'Генерация PDF...';
  document.body.appendChild(loader);

  try {
    const canvas = await html2canvas(element, {
      scale: 2, // 2x для чёткости на Retina
      useCORS: true, // для внешних изображений
      logging: false,
      backgroundColor: '#ffffff'
    });

    const imgData = canvas.toDataURL('image/png');
    const pdf = new jsPDF({
      orientation: canvas.width > canvas.height ? 'landscape' : 'portrait',
      unit: 'px',
      format: [canvas.width / 2, canvas.height / 2]
    });

    pdf.addImage(imgData, 'PNG', 0, 0, canvas.width / 2, canvas.height / 2);
    pdf.save(`${filename}_${format(new Date(), 'yyyy-MM-dd')}.pdf`);
  } finally {
    document.body.removeChild(loader);
  }
}

async function exportToPNG(elementId: string, filename: string = 'chart') {
  const element = document.getElementById(elementId);
  if (!element) return;

  const canvas = await html2canvas(element, {
    scale: 2,
    backgroundColor: '#ffffff'
  });

  const link = document.createElement('a');
  link.download = `${filename}_${format(new Date(), 'yyyy-MM-dd')}.png`;
  link.href = canvas.toDataURL('image/png');
  link.click();
}

React Hook для экспорта

function useExport(elementRef: React.RefObject<HTMLElement>) {
  const [isExporting, setIsExporting] = useState(false);

  const exportToPDF = async (filename?: string) => {
    if (!elementRef.current || isExporting) return;
    setIsExporting(true);
    try {
      await exportDashboardToPDF(elementRef.current, filename);
    } finally {
      setIsExporting(false);
    }
  };

  const exportToPNG = async (filename?: string) => {
    if (!elementRef.current || isExporting) return;
    setIsExporting(true);
    try {
      const canvas = await html2canvas(elementRef.current, {
        scale: 2,
        backgroundColor: '#ffffff'
      });
      downloadCanvas(canvas, filename);
    } finally {
      setIsExporting(false);
    }
  };

  return { exportToPDF, exportToPNG, isExporting };
}

// Компонент с кнопками экспорта
function DashboardWithExport() {
  const dashboardRef = useRef<HTMLDivElement>(null);
  const { exportToPDF, exportToPNG, isExporting } = useExport(dashboardRef);

  return (
    <div>
      <div className="flex gap-2 mb-4">
        <button
          onClick={() => exportToPDF('analytics-report')}
          disabled={isExporting}
          className="export-btn"
        >
          {isExporting ? '⏳' : '📄'} Экспорт PDF
        </button>
        <button
          onClick={() => exportToPNG('dashboard')}
          disabled={isExporting}
          className="export-btn"
        >
          {isExporting ? '⏳' : '🖼'} Сохранить PNG
        </button>
      </div>
      <div ref={dashboardRef} id="dashboard-content">
        <Charts />
      </div>
    </div>
  );
}

Почему серверный рендеринг гарантирует качество?

Если дашборд содержит SVG с интерактивом, WebGL-графики или требует точного соответствия печатной версии, клиентские библиотеки пасуют. headless Chrome (Puppeteer) рендерит страницу как настоящий браузер — никаких артефактов. Однако такой подход медленнее и требует серверных ресурсов. На практике серверный рендеринг сокращает количество жалоб на качество в 4 раза по сравнению с клиентским.

import puppeteer from 'puppeteer'; // POST /api/export/pdf
app.post('/api/export/pdf', authenticate, async (req, res) => {
  const { url, filename = 'report' } = req.body;
  const browser = await puppeteer.launch({ headless: 'new' });
  const page = await browser.newPage();
  // Передать auth cookie
  await page.setCookie({ name: 'auth_token', value: req.token, domain: 'your-app.com' });
  await page.goto(`${process.env.APP_URL}${url}?export=true`, { waitUntil: 'networkidle0', timeout: 30000 });
  // Дождаться рендера графиков
  await page.waitForSelector('[data-loaded="true"]', { timeout: 15000 });
  const pdf = await page.pdf({ format: 'A4', landscape: true, printBackground: true, margin: { top: '20mm', right: '15mm', bottom: '20mm', left: '15mm' } });
  await browser.close();
  res.setHeader('Content-Type', 'application/pdf');
  res.setHeader('Content-Disposition', `attachment; filename="${filename}.pdf"`);
  res.send(pdf);
});

Сравнение подходов

Дополнительные критерии выбора

Что входит в работу

• Аналитика: аудит текущего дашборда, выявление несовместимых элементов (WebGL, анимации).
• Выбор метода: клиентский для 80% типовых задач, серверный для сложных визуализаций.
• Реализация: написание обёртки (React/Vue/чистый JS), кнопки экспорта, индикатор загрузки.
• Тестирование: проверка на различных разрешениях, браузерах, объёмах данных.
• Документация: README с описанием API и параметров.
• Поддержка: исправление регрессий при обновлении библиотек в течение 3 месяцев.

Процесс работы

1. Аналитика — выясняем, какие графики используются (Chart.js, D3, Three.js) и нужна ли серверная генерация.
2. Проектирование — выбираем стек: html2canvas + jsPDF или Puppeteer + Express.
3. Реализация — пишем код, интегрируем в приложение, настраиваем CORS.
4. Тестирование — гоним тесты на больших данных (1000+ точек) и разных браузерах.
5. Деплой — размещаем серверный endpoint, если нужно, настраиваем мониторинг.

Сроки ориентировочно

• Клиентский экспорт PNG/PDF + кнопки — 1–2 дня.
• Серверный через Puppeteer с авторизацией — 3–5 дней.
• Полноценная система с выбором формата и брендированием — до недели.

Типичные ошибки и как их избежать

Собрали чек-лист на основе наших проектов:

• Не забывайте про useCORS: true — иначе внешние картинки приведут к пустому canvas.
• Для шрифтов (особенно кириллицы) в jsPDF подключите кастомные шрифты через addFont, иначе текст может не отображаться.
• При серверном рендеринге обязательно дождитесь окончания ленивой загрузки графиков (waitForSelector).
• Если дашборд обновляется в реальном времени, перед экспортом приостановите обновления (через флаг window.__pauseUpdates = true), иначе содержимое «уедет».
• Для больших данных оптимизируйте число точек — агрегируйте перед захватом.

Мы реализовали экспорт для десятков проектов — от корпоративных порталов до маркетинговых дашбордов. Если хотите получить консультацию или оценить свою задачу, свяжитесь с нами — подберём оптимальное решение. Закажите интеграцию экспорта дашбордов — и ваши пользователи забудут о ручном копировании данных.

Опираемся на официальную документацию Puppeteer и html2canvas. Опыт работы с этими инструментами — более 5 лет, гарантируем стабильную интеграцию без сюрпризов.