توليد تقارير PDF باستخدام JavaScript (Node.js): نظرة عامة على المكتبات وأمثلة الكود

توليد تقارير PDF باستخدام JavaScript (Node.js): دليل شامل

يعد إنشاء مستندات PDF من أكثر المهام المطلوبة في تطوير الويب. سواء كان الأمر يتعلق بتصدير الفواتير، أو إعداد تقارير تحليلية، أو إنشاء شهادات - لا يمكن الاستغناء عن أداة موثوقة. في نظام Node.js البيئي، توجد عدة مكتبات قوية تتيح لك حل هذه المهمة بسرعة ومرونة. في هذه المقالة، سنستعرض ثلاثة أساليب رئيسية ونوضح كيفية اختيار الأداة المناسبة لمشروعك على PythonLib.

لماذا توليد PDF على الخادم؟

غالبًا ما يكون التوليد من جانب العميل (المتصفح) محدودًا: فقد يفقد المستخدم البيانات عند تحديث الصفحة، وقد لا تعالج الأجهزة المحمولة التخطيطات المعقدة بشكل صحيح. يمنحك نهج الخادم باستخدام Node.js تحكمًا كاملاً في بنية المستند، ويحمي المنطق التجاري، ويسمح بدمج التوليد في خطوط أنابيب CI/CD.

أفضل 3 مكتبات للعمل مع PDF في Node.js

1. PDFKit - العمل منخفض المستوى مع المحتوى

PDFKit هي المكتبة الأكثر شيوعًا لإنشاء PDF من الصفر. لا تتطلب تثبيت تبعيات إضافية (مثل Chromium) وتسمح بالتحكم في كل بكسل من المستند.

• المزايا: خفيفة (بضعة ميغابايت فقط)، حرية كاملة في التخطيط، دعم الخطوط والصور والرسومات المتجهة.
• العيوب: تحتاج إلى كتابة الكثير من الكود للتخطيطات المعقدة، لا يوجد نقل تلقائي للنص.

مثال على إنشاء فاتورة بسيطة:

const PDFDocument = require('pdfkit');const fs = require('fs');

const doc = new PDFDocument({ margin: 50 });

doc.pipe(fs.createWriteStream('invoice.pdf'));

// العنوانdoc.fontSize(25).text('فاتورة رقم 123', { align: 'center' });doc.moveDown();

// الجدولdoc.fontSize(12).text('المنتج: استشارة', { continued: true })   .text('السعر: 5000 روبل', { align: 'right' });

doc.moveDown();doc.text('الإجمالي: 5000 روبل', { align: 'right' });

doc.end();

2. Puppeteer - التوليد من HTML/CSS

Puppeteer يقوم بتشغيل متصفح Chromium بدون واجهة رسومية (headless) ويحول صفحة HTML إلى PDF. هذا هو الخيار المثالي إذا كان لديك بالفعل قوالب HTML مع أنماط CSS.

• المزايا: تخطيط بسيط عبر HTML، دعم جميع خصائص CSS (flex، grid، @media print)، إمكانية إضافة الرؤوس والتذييلات.
• العيوب: تبعية ثقيلة (~300 ميجابايت من Chromium)، بدء تشغيل بطيء، غير مناسب للمستندات البسيطة.

مثال على تحويل HTML إلى PDF:

const puppeteer = require('puppeteer');

async function generateReport() {  const browser = await puppeteer.launch();  const page = await browser.newPage();

  await page.setContent(`<h1 style="color: blue;">تقرير مارس 2025</h1>    <p>إجمالي الإيرادات: <strong>1,200,000 روبل</strong></p>`);

  await page.pdf({    path: 'report.pdf',    format: 'A4',    printBackground: true,    margin: { top: '20px', bottom: '20px' }  });

  await browser.close();}

generateReport();

3. jsPDF - أداة متعددة الاستخدامات (عميل + خادم)

jsPDF هي مكتبة تعمل في كل من المتصفح و Node.js. توفر طرقًا عالية المستوى لإنشاء الجداول والرسوم البيانية وحتى تضمين الخطوط.

• المزايا: واجهة برمجة تطبيقات بسيطة، دعم مدمج للجداول (عبر إضافة)، وزن خفيف.
• العيوب: على الخادم، يتطلب إعدادًا يدويًا للخطوط (ليست جميع أحرف السيريلية موجودة افتراضيًا).

مثال مع جدول:

const { jsPDF } = require("jspdf");require("jspdf-autotable");

const doc = new jsPDF();

doc.text("إحصائيات المبيعات", 14, 20);

doc.autoTable({  head: [['الشهر', 'المبيعات', 'الربح']],  body: [    ['يناير', '100', '20,000'],