PDFKit JavaScript (Node.js): دليل شامل، تثبيت، أمثلة…

ما هي مكتبة PDFKit ولماذا تحتاجها؟

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

أبرز حالات استخدام PDFKit:

توليد التقارير والفواتير: إنشاء مستندات PDF ديناميكية بناءً على بيانات من قاعدة بيانات أو API.
إنشاء فواتير الشراء والإيصالات: توليد تلقائي للمستندات للمتاجر الإلكترونية وأنظمة المحاسبة.
إصدار الشهادات والدبلومات: إنشاء مستندات مخصصة ببيانات فريدة لكل مستلم.
تصدير البيانات: تحويل صفحات الويب أو الجداول أو الرسوم البيانية إلى صيغة PDF للطباعة أو الأرشفة.
إنشاء الكتب الإلكترونية والأدلة: تنسيق برمجي للمستندات متعددة الصفحات مع فهرس وعلامات مرجعية.

PDFKit هي الخيار الأمثل للمطورين الذين يحتاجون إلى أداء عالٍ ومرونة وتحكم كامل دون استخدام تبعيات خارجية (مثل الحاجة إلى تثبيت LibreOffice أو wkhtmltopdf).

تثبيت PDFKit

يتم توزيع PDFKit عبر مدير الحزم npm. للتثبيت، قم بتشغيل الأمر التالي في الطرفية (Terminal) داخل مجلد مشروعك:

npm install pdfkit

بعد التثبيت، ستكون المكتبة جاهزة للاستيراد في الكود الخاص بك. لا حاجة لتبعيات إضافية.

بداية سريعة: إنشاء أول مستند PDF

لنقم بإنشاء ملف PDF بسيط يحتوي على نص "Hello, World!".

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

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

// تحديد تيار (stream) لكتابة النتيجة
doc.pipe(fs.createWriteStream('hello_world.pdf'));

// إضافة نص إلى الصفحة
doc.fontSize(25)
   .text('Hello, World!', 100, 100);

// إنهاء المستند وإغلاق التيار
doc.end();

console.log('تم إنشاء ملف PDF "hello_world.pdf" بنجاح!');

بعد تشغيل هذا الكود، سيظهر ملف hello_world.pdf في نفس المجلد مع النص "Hello, World!".

أهم الأساليب والوظائف في PDFKit

توفر PDFKit واجهة برمجية واسعة. فيما يلي 10 من أهم الأساليب مع شرح مفصل وأمثلة.

1. `text(text, x, y, options)`

الوصف: يضيف نصاً إلى المستند. هذه هي الطريقة الأساسية للتعامل مع النصوص. تدعم التفاف النص تلقائياً، المحاذاة، الهوامش، والتنسيق.

المعاملات:

text (String) — النص المراد إضافته.
x (Number, اختياري) — إحداثي X. إذا لم يتم تحديده، يستمر النص من الموضع الحالي.
y (Number, اختياري) — إحداثي Y. إذا لم يتم تحديده، يستمر النص من الموضع الحالي.
options (Object, اختياري) — كائن يحتوي على الإعدادات:
- align (String) — المحاذاة: 'left'، 'center'، 'right'، 'justify'.
- indent (Number) — مسافة بادئة للسطر الأول.
- paragraphGap (Number) — المسافة بين الفقرات.
- lineGap (Number) — المسافة بين الأسطر.
- width (Number) — عرض كتلة النص (لتفعيل التفاف النص).
- height (Number) — ارتفاع كتلة النص.
- underline (Boolean) — وضع خط تحت النص.