PDFKit لجافا سكريبت (Node.js): دليل شامل مع أمثلة

مقدمة عن PDFKit

PDFKit هي مكتبة قوية ومرنة لإنشاء مستندات PDF من جهة الخادم باستخدام JavaScript (Node.js). تمنح المطورين تحكمًا كاملاً في عملية إنشاء PDF: بدءًا من المستندات النصية البسيطة وصولاً إلى التقارير المعقدة متعددة الصفحات التي تحتوي على جداول وصور ورسومات وعناصر تفاعلية. لا تتطلب PDFKit تثبيت أي تبعيات إضافية مثل PhantomJS أو Puppeteer، وتعمل حصريًا على JavaScript الخالص، مما يجعلها الخيار الأمثل لتطبيقات الخادم عالية التحميل.

لماذا تحتاج هذه المكتبة؟ في تطوير الويب الحديث، غالبًا ما تنشأ الحاجة إلى إنشاء مستندات PDF برمجيًا: الفواتير، كشوف الحساب، التقارير، الشهادات، العقود. PDFKit تحل هذه المشكلة بأناقة وكفاءة. على عكس محولات HTML-to-PDF التي قد تكون بطيئة وغير متوقعة، تمنحك PDFKit وصولًا مباشرًا إلى نموذج PDF: أنت من تحدد إحداثيات كل عنصر، وتتحكم في الخطوط والألوان وتخطيط الصفحات. هذا مهم بشكل خاص عندما تحتاج إلى تحديد دقيق لمواقع العناصر أو العمل مع تنسيقات غير قياسية.

المكتبة مدعومة بنشاط من المجتمع، ولها توثيق شامل، وتُستخدم في بيئات الإنتاج من قبل آلاف الشركات حول العالم. تدعم PDFKit جميع الميزات الأساسية لتنسيق PDF: تضمين الخطوط (بما في ذلك العربية)، العمل مع الصور (JPEG, PNG, SVG)، إنشاء التعليقات التوضيحية والروابط التشعبية والإشارات المرجعية، بالإضافة إلى تشفير المستندات. بفضل البنية المعيارية وإمكانية الكتابة المتدفقة، تعتبر PDFKit مثالية لإنشاء كل من المستندات الصغيرة وملفات PDF الضخمة التي تصل إلى عدة غيغابايت.

تثبيت PDFKit

يتم توزيع PDFKit عبر مدير الحزم npm. يتم التثبيت باستخدام الأمر القياسي:

npm install pdfkit

للعمل مع TypeScript، قد تحتاج إلى تثبيت الأنواع الإضافية:

npm install pdfkit @types/pdfkit

إذا كنت تستخدم Yarn:

yarn add pdfkit

بعد التثبيت، المكتبة جاهزة للاستخدام. لا حاجة لأي تبعيات إضافية أو متطلبات نظام — كل شيء يعمل "مباشرة" على أي منصة تدعم Node.js (Windows, macOS, Linux).

بداية سريعة: مثال عملي بسيط

أنشئ ملفًا باسم hello-pdf.js وأضف الكود التالي:

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

// إنشاء مستند PDF جديد
const doc = new PDFDocument();

// تحديد مكان حفظ النتيجة
doc.pipe(fs.createWriteStream('hello.pdf'));

// إضافة نص
doc.fontSize(25)
   .text('مرحبًا بالعالم!', 100, 100);

// إنهاء المستند
doc.end();

console.log('تم إنشاء PDF: hello.pdf');

قم بتشغيل السكريبت:

node hello-pdf.js

سيظهر في المجلد الحالي ملف hello.pdf يحتوي على النص "مرحبًا بالعالم!". يوضح هذا المثال المبدأ الأساسي للعمل مع PDFKit: إنشاء مستند، إضافة محتوى، وحفظ النتيجة.

الطرق والفئات الرئيسية في PDFKit

توفر PDFKit واجهة برمجة تطبيقات (API) غنية للعمل مع مستندات PDF. دعنا نستعرض أهم الطرق التي ستحتاجها في التطوير اليومي.

1. new PDFDocument(options) — مُنشئ المستند

التوقيع: new PDFDocument([options])

الوصف: ينشئ مثيلًا جديدًا لمستند PDF. المعامل options هو كائن يسمح بتعيين حجم الصفحة، الهوامش، الاتجاه، البيانات الوصفية، وإعدادات أخرى.

const doc = new PDFDocument({
  size: 'A4',              // حجم الصفحة (A4, Letter, Legal وغيرها)
  layout: 'portrait',      // الاتجاه: 'portrait' أو 'landscape'
  margins: {               // الهوامش