توليد تقارير PDF بلغة C# (.NET) باستخدام QuestPDF

توليد تقارير PDF بلغة C# (.NET) باستخدام QuestPDF

في التطوير الحديث على منصة .NET، غالبًا ما تنشأ الحاجة لإنشاء مستندات PDF احترافية: تقارير، فواتير، إشعارات شحن، ملخصات تحليلية، وغيرها من المستندات التجارية. مكتبة QuestPDF هي حل حديث وعالي الأداء وبديهي لتوليد PDF بلغة C#. لا تتطلب تثبيت أدوات خارجية (مثل wkhtmltopdf) وتعمل بالكامل ضمن الكود المُدار لـ .NET.

في هذه المقالة، سنشرح بالتفصيل كيفية البدء مع QuestPDF، إعداد المشروع، إنشاء تقرير بسيط يحتوي على جدول وصورة وتنسيق نص.

التثبيت والإعداد

يتم توزيع QuestPDF عبر NuGet. للتثبيت، نفذ الأمر في Package Manager Console أو عبر واجهة Visual Studio/Rider:

Install-Package QuestPDF

أو عبر .NET CLI:

dotnet add package QuestPDF

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

QuestPDF.Settings.License = LicenseType.Community;// أو للاستخدام التجاري:// QuestPDF.Settings.License = LicenseType.Professional;

إنشاء أول مستند PDF

تستخدم QuestPDF واجهة Fluent API — حيث تصف هيكل المستند من خلال استدعاءات متسلسلة للطرق. لنلقِ نظرة على مثال بسيط:

using QuestPDF.Fluent;using QuestPDF.Helpers;using QuestPDF.Infrastructure;

// إعداد الترخيص (إلزامي)QuestPDF.Settings.License = LicenseType.Community;

// إنشاء المستندDocument.Create(container =>{    container.Page(page =>    {        page.Size(PageSizes.A4);        page.Margin(2, Unit.Centimetre);        page.DefaultTextStyle(x => x.FontSize(12));

        page.Header()            .Text("تقرير المبيعات")            .SemiBold().FontSize(24).FontColor(Colors.Blue.Medium);

        page.Content()            .PaddingVertical(1, Unit.Centimetre)            .Column(col =>            {                col.Item().Text("التاريخ: " + DateTime.Now.ToShortDateString());                col.Item().PaddingBottom(10).LineHorizontal(1);                col.Item().Text("فيما يلي جدول بالبيانات:");            });

        page.Footer()            .AlignCenter()            .Text(x =>            {                x.Span("صفحة ");                x.CurrentPageNumber();            });    });}).GeneratePdf("report.pdf");

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

العمل مع الجداول

من أكثر المهام شيوعًا عرض البيانات الجدولية. توفر QuestPDF واجهة برمجة تطبيقات قوية لإنشاء جداول مع ضبط تلقائي لعرض الأعمدة:

container.Page(page =>{    page.Size(PageSizes.A4);    page.Margin(20);

    page.Content().Table(table =>    {        // تعريف الأعمدة (العرض كنسبة مئوية من المساحة المتاحة)        table.ColumnsDefinition(columns =>        {            columns.RelativeColumn(3); // اسم المنتج            columns.RelativeColumn(1); // الكمية            columns.RelativeColumn(1); // السعر            columns.RelativeColumn(1); // الإجمالي        });

        // رأس الجدول        table.Header(header =>        {            header.Cell().Background(Colors.Grey.Lighten2).Padding(5).Text("المنتج");            header.Cell().Background(Colors.Grey.Lighten2).Padding(5).AlignCenter().Text("الكمية");            header.Cell().Background(Colors.Grey.Lighten2).Padding(5).AlignCenter().Text("السعر");            header.Cell().Backgrou