כיצד לייצא דשבורדים ל-PDF ו-PNG: צד לקוח מול צד שרת

מדריך לייצוא דשבורדים ל-PDF ו-PNG: צד לקוח מול צד שרת

לקוח מבקש כפתור "ייצוא PDF", אבל מה שהוא מקבל זה עיצוב שבור עם תרשימים חתוכים ותוויות מטושטשות. נשמע מוכר? עברנו את זה עשרות פעמים. המשימה היא ללכוד אלמנט DOM לתמונה וליצור מסמך תוך שמירה על דיוק פיקסל-מושלם וגופנים נכונים. קיימות שתי גישות שונות מהותית: צד לקוח (באמצעות HTML Canvas API) וצד שרת (באמצעות headless Chromium). הבחירה תלויה במורכבות הדשבורד.

יישמנו ייצוא ליותר מ-50 פרויקטים—מסטארטאפים ועד ארגונים. חיסכון ממוצע בזמן למשתמשים הוא 30% בזכות יצירת דוחות אוטומטית. הטמעת מערכת ייצוא זו עולה בדרך כלל בין $1,000 ל-$3,000, אבל חוסכת לעסקים עד $500 בחודש בהכנת דוחות ידנית. למהנדסים שלנו יש ניסיון של 5+ שנים עם כלי ויזואליזציה, מה שמבטיח אינטגרציה יציבה.

בחירה בין ייצוא בצד לקוח לצד שרת

הגישה של צד לקוח עובדת עבור 80% מהדשבורדים הטיפוסיים. היא מהירה ולא מעמיסה על השרת, אבל מתקשה עם גרפיקת WebGL. צד שרת נחוץ כאשר שחזור מדויק של כל האלמנטים, כולל מסנני SVG ואנימציות, הוא קריטי. עיבוד בצד שרת אמין פי 4 עבור ויזואליזציות מורכבות מכל ספריית צד לקוח. הבדל באיכות: שיטת השרת משחזרת גופנים וקווים בדיוק פי 3, ותלונות על איכות יורדות פי 4.

למה ייצוא בצד לקוח לא תמיד עובד

html2canvas הוא כלי חזק, אבל הוא לא יכול לעבד WebGL, חלק ממסנני SVG ואנימציות. אם הדשבורד משתמש בספריות כמו Three.js או D3 עם אנימציה, פיקסלים יכולים לזוז. בנוסף, בקנה מידה של 1x במסכי Retina, טקסט הופך מטושטש—מתוקן עם הפרמטר scale: 2. מלכודת נוספת היא CORS: תמונות חיצוניות (למשל, לוגואים) חייבות להישלח עם כותרות מתאימות, אחרת הקנבס הופך ל"מזוהם" ו-toDataURL נכשל.

יישום בצד לקוח: html2canvas + jsPDF + React

הדרך המהירה ביותר לדשבורדים פשוטים היא ללכוד את ה-DOM לקנבס ולהכניס אותו ל-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>
  );
}

עיבוד בצד שרת עם Puppeteer

אם הדשבורד מכיל 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);
});

השוואה וקריטריוני בחירה

קריטריונים נוספים

ליצירת דוחות web יעילה, שלבו את הכלים הללו. 95% מהמשתמשים מדווחים על שביעות רצון מהשיטה שנבחרה כאשר היא מותאמת כראוי לצרכים שלהם.

סקירת עבודה

מה כלול

• אנליטיקה: ביקורת על הדשבורד הנוכחי, זיהוי אלמנטים לא תואמים (WebGL, אנימציות).
• בחירת שיטה: צד לקוח עבור 80% מהמשימות הסטנדרטיות, צד שרת עבור ויזואליזציות מורכבות.
• יישום: כתיבת wrapper (React/Vue/vanilla JS), כפתורי ייצוא, מחוון טעינה.
• בדיקות: אימות ברזולוציות שונות, דפדפנים ונפחי נתונים.
• תיעוד: README עם תיאור API ופרמטרים.
• תמיכה: תיקון רגרסיות בעדכון ספריות תוך 3 חודשים.

תהליך העבודה

1. אנליטיקה — אנו קובעים אילו תרשימים נמצאים בשימוש (Chart.js, D3, Three.js) והאם נדרשת יצירה בצד שרת.
2. עיצוב — בוחרים את המחסנית: html2canvas + jsPDF או Puppeteer + Express.
3. יישום — כותבים קוד, משלבים באפליקציה, מגדירים CORS.
4. בדיקות — מריצים בדיקות על מערכי נתונים גדולים (1000+ נקודות) ודפדפנים שונים.
5. פריסה — פורסים את נקודת הקצה של השרת אם נדרש, מגדירים ניטור.

לוחות זמנים משוערים

• ייצוא בצד לקוח PNG/PDF + כפתורים — 1–2 ימים.
• צד שרת באמצעות Puppeteer עם אימות — 3–5 ימים.
• מערכת מלאה עם בחירת פורמט ומיתוג — עד שבוע.

טעויות נפוצות וכיצד להימנע מהן