1. ما هي المكتبة ولماذا نستخدمها؟

printpdf هي مكتبة قوية ومرنة للغة البرمجة Rust، مصممة لإنشاء مستندات PDF من الصفر. على عكس الأدوات الأخرى التي تقوم بتحويل HTML أو Markdown إلى PDF، توفر printpdf واجهة برمجة تطبيقات منخفضة المستوى تمنحك تحكمًا كاملاً في كل جانب من جوانب المستند: من وضع النصوص والرسومات المتجهة إلى تضمين الخطوط والصور. هذه المكتبة مكتوبة بلغة Rust الخالصة دون أي تبعيات خارجية (باستثناء المكتبة القياسية)، مما يجعلها الخيار الأمثل للأنظمة التي تهم فيها أمان الذاكرة والأداء العالي وقابلية النقل.

لماذا نستخدم printpdf؟ في عالمنا المعاصر، يُعد PDF تنسيقًا عالميًا لتبادل المستندات. إنشاء PDF على جانب الخادم مطلوب في العديد من السيناريوهات: إنشاء الفواتير في أنظمة ERP، توليد التقارير ولوحات التحليل، إصدار الشهادات، وإنشاء النماذج المطبوعة. Rust، بفضل تركيزها على الأداء والموثوقية، مثالية لهذه المهام. تتيح لك printpdf القيام بذلك بكفاءة عالية، دون الحاجة إلى تشغيل عمليات خارجية (كما في wkhtmltopdf) أو استخدام محركات متصفح ثقيلة.

تشمل الميزات الرئيسية للمكتبة: دعم جميع كائنات PDF القياسية (الصفحات، الخطوط، الصور، الرسومات)، العمل مع Unicode وتضمين خطوط TrueType/OpenType، إنشاء مستندات متعددة الصفحات، استخدام أنظمة الألوان RGB وCMYK وGrayscale، وتحديد دقيق لمواقع العناصر باستخدام نظام الإحداثيات PDF. إنها ليست أداة للتحويل الفوري، بل هي "منصة بناء" احترافية لإنشاء المستندات.

2. التثبيت

لتثبيت مكتبة printpdf في مشروع Rust الخاص بك، استخدم مدير الحزم القياسي Cargo. كل ما عليك فعله هو إضافة التبعية إلى ملف Cargo.toml الخاص بمشروعك.

افتح الطرفية في المجلد الجذر لمشروعك ونفذ الأمر التالي:

cargo add printpdf

أو أضف السطر التالي يدويًا إلى قسم [dependencies] في ملف Cargo.toml:

[dependencies]
printpdf = "0.7"

بعد ذلك، سيقوم Cargo تلقائيًا بتحميل المكتبة وجميع تبعياتها الداخلية عند البناء التالي للمشروع. تأكد من تثبيت Rust (rustc) و Cargo على جهازك. إذا لم يكن الأمر كذلك، تفضل بزيارة rustup.rs للتثبيت.

3. البداية السريعة — مثال عملي بسيط

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

use printpdf::*;
use std::fs::File;
use std::io::BufWriter;

fn main() {
    // إنشاء مستند PDF جديد
    let (doc, page1, layer1) = PdfDocument::new(
        "أول مستند PDF لي في Rust",
        Mm(210.0), // عرض الصفحة (A4)
        Mm(297.0), // ارتفاع الصفحة (A4)
        "Layer 1", // اسم الطبقة
    );

    // الحصول على الخط الافتراضي (Helvetica المضمن)
    let font = doc.add_builtin_font(BuiltinFont::Helvetica).unwrap();

    // بدء العمل مع الطبقة
    let current_layer = doc.get_page(page1).get_layer(layer1);

    // استخدام الخط بحجم 48 نقطة، باللون الأسود
    current_layer.use_text("مرحباً، عالم PDF في Rust!", 48.0, Mm(50.0), Mm(200.0), &font);

    // حفظ المستند في ملف
    let file =