آموزش کامل استفاده از پکیج QuestPDF برای تولید خروجی PDF در پروژه‌های Web API

خروجی PDF، طراحی سند PDF، تولید PDF، QuestPDF 1404/8/25
نویسنده: مدرس بهمن آبادی

آموزش کامل استفاده از پکیج QuestPDF برای تولید خروجی PDF در پروژه‌های Web API

خروجی pdf در نرم افزار

مقدمه

تولید فایل‌های PDF یکی از نیازهای اساسی در بسیاری از پروژه‌های Web API است؛ مخصوصاً در بخش‌های گزارش‌گیری، تولید فاکتور، رسید پرداخت، فرم‌ها، بلیت‌ها یا خروجی مستندات.
کتابخانه QuestPDF یکی از بهترین گزینه‌های مدرن و قدرتمند برای تولید اسناد PDF در محیط دات‌نت محسوب می‌شود. این کتابخانه با ارائه یک API ساده، ساختاری شبیه به طراحی UI دارد و به‌راحتی می‌توان قالب‌های پیچیده را با آن ایجاد کرد.

این مقاله به معرفی QuestPDF، نحوه نصب، پیاده‌سازی در پروژه‌های Web API و نکات کلیدی توسعه می‌پردازد.

معرفی QuestPDF

QuestPDF یک کتابخانه متن‌باز و مبتنی بر دات‌نت است که امکان تولید PDF با ساختاری کاملاً برنامه‌نویسی‌شده را فراهم می‌کند. این کتابخانه برخلاف سایر ابزارها مانند iText یا PdfSharp، رویکردی Component-Based دارد و طراحی سند را مشابه ساختار صفحات UI انجام می‌دهد.

‏ویژگی‌های مهم:

  • پشتیبانی کامل از .NET 6، .NET 7 و نسخه‌های جدید

  • طراحی کاملاً Fluent و مدرن

  • پشتیبانی از RTL

  • پشتیبانی از فونت فارسی

  • سرعت بالا و حافظه کم

  • مناسب برای تولید گزارش، فاکتور، قرارداد، لیست‌ها و نمودارهای ساده

نصب QuestPDF

برای نصب کتابخانه کافی است پکیج زیر را اضافه کنید:

Install-Package QuestPDF

یا در فایل .csproj:

<PackageReference Include="QuestPDF" Version="2024.2.0" />

ساخت اولین سند PDF

QuestPDF یک ساختار اصلی با نام Document دارد. برای ساخت یک سند، باید یک کلاس ایجاد کنید که از این اینترفیس ارث‌بری کند:

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

public class SampleDocument : IDocument
{
    public DocumentMetadata GetMetadata() => new DocumentMetadata();

    public DocumentSettings GetSettings() => new DocumentSettings();

    public void Compose(IDocumentContainer container)
    {
        container.Page(page =>
        {
            page.Margin(30);
            page.Size(PageSizes.A4);

            page.Content().Padding(20).Column(col =>
            {
                col.Item().Text("گزارش نمونه").FontSize(22).Bold();
                col.Item().Text("این یک مثال ساده از خروجی PDF با QuestPDF است.");
            });
        });
    }
}

استفاده از سند در Web API

برای تولید فایل PDF در کنترلر Web API، ابتدا باید یک نمونه از کلاس Document بسازید و سپس خروجی آن را به صورت byte[] برگردانید.

[HttpGet("export-pdf")]
public IActionResult ExportPdf()
{
    var document = new SampleDocument();
    var pdfBytes = document.GeneratePdf(); // تولید فایل

    return File(pdfBytes, 
        "application/pdf", 
        "report.pdf");
}

این اکشن یک فایل PDF تولید کرده و به‌صورت دانلود برای کاربر ارسال می‌کند.

افزودن فونت فارسی

برای پشتیبانی کامل از زبان فارسی، باید یک فونت فارسی معرفی کنید:

QuestPDF.Settings.License = LicenseType.Community;

FontManager.RegisterFont(File.OpenRead("wwwroot/fonts/Vazir.ttf"));

و سپس در سند:

col.Item().Text("متن فارسی تست").FontFamily("Vazir");

 نمونه عملی: ساخت جدول در PDF

public class PersonReportDocument : IDocument
{
    public List<Person> People { get; set; }

    public PersonReportDocument(List<Person> people)
    {
        People = people;
    }

    public DocumentMetadata GetMetadata() => new DocumentMetadata();

    public DocumentSettings GetSettings() => new DocumentSettings();

    public void Compose(IDocumentContainer container)
    {
        container.Page(page =>
        {
            page.Margin(20);
            page.Content().Table(table =>
            {
                table.ColumnsDefinition(cols =>
                {
                    cols.ConstantColumn(50);
                    cols.RelativeColumn();
                    cols.RelativeColumn();
                });

                table.Header(header =>
                {
                    header.Cell().Text("ID").Bold();
                    header.Cell().Text("Name").Bold();
                    header.Cell().Text("Age").Bold();
                });

                foreach (var p in People)
                {
                    table.Cell().Text(p.Id.ToString());
                    table.Cell().Text(p.Name);
                    table.Cell().Text(p.Age.ToString());
                }
            });
        });
    }
}

و استفاده در API:

[HttpGet("report")]
public IActionResult GetReport()
{
    var people = new List<Person>
    {
        new Person { Id=1, Name="Ali", Age=30 },
        new Person { Id=2, Name="Sara", Age=25 }
    };

    var doc = new PersonReportDocument(people);
    var pdf = doc.GeneratePdf();

    return File(pdf, "application/pdf", "people.pdf");
}

 نکات مهم و حرفه‌ای

‏۱) استفاده از Layoutها

QuestPDF از Layoutهایی مانند:

  • Row

  • Column

  • Grid

  • Table

  • Stack

پشتیبانی می‌کند.

‏۲) تولید PDF در پس‌زمینه

می‌توان خروجی PDF را در Queue یا Background Service تولید کرد.

‏۳) محدودیت‌ها

  • نمودارهای پیچیده نیازمند رندر تصویر هستند.

  • طراحی پیچیده نیازمند تجربه در Layout بندی است.

اگر تمایل به یادگیری اصولی و حرفه ای برنامه نویسی دارید دوره جامع برنامه نویسی وب را مشاهده کنید

نتیجه‌گیری

QuestPDF یکی از بهترین گزینه‌های تولید PDF در Web API است. این کتابخانه با طراحی بسیار ساده، سرعت بالا و پشتیبانی عالی از RTL و فونت فارسی، می‌تواند جایگزین مناسبی برای بسیاری از ابزارهای سنگین و تجاری مانند iText باشد.
پیاده‌سازی آن در Web API نیز بسیار ساده و قابل توسعه است و می‌توان انواع گزارش‌ها، جداول، فاکتورها و اسناد رسمی را با آن تولید کرد.

۱. مستندات رسمی QuestPDF
https://www.questpdf.com/documentation

2. GitHub رسمی پروژه
https://github.com/QuestPDF/QuestPDF