Экспорт дашбордов в 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 лет, гарантируем стабильную интеграцию без сюрпризов.