إنشاء تقارير PDF في GO

حسنًا. الآن إنشاء ملفات PDF باستخدام لغة GO!

Page content

إنشاء مستندات PDF برمجيًا يمكن أن يكون ميزة مهمة في تطبيقك. هنا نستعرض ونقدم مراجعة قصيرة مع أمثلة للibraries المتاحة في لغة البرمجة Go (Golang) لإنشاء ملفات PDF](https://www.glukhov.org/ar/post/2025/05/generating-pdf-reports-in-go/ “المكتبات التي يمكن استخدامها لإنشاء PDFs في GO”).

يمكن أن تكون الحلول المناسبة مختلفة، على سبيل المثال، لإنشاء مستندات بسيطة أو لإنشاء مستندات PDF معقدة ومزودة بالعديد من الميزات.

go, pdf! نعم، الصورة مُولدة بواسطة الذكاء الاصطناعي، النموذج هو Flux1.Dev.

المكتبات والأدوات

gofpdf

GoPdf هي مكتبة بسيطة لإنشاء PDFs. تتيح إضافة النصوص، الصور، الأشكال، الجداول، والتعامل مع صفحات متعددة. مناسبة لإنشاء مستندات PDF بسيطة إلى معقدة بشكل معتدل.

المُحافظ: جونغ كورت (موقفت لكن لا تزال تُستخدم).

القيود: نقص التحديثات، رغم أن الاستخدام الحالي لا يزال قائماً.

مثال:

package main

import (
    "github.com/jung-kurt/gofpdf"
)

func main() {
    pdf := gofpdf.New("P", "mm", "A4", "")
    pdf.AddPage()
    pdf.SetFont("Arial", "B", 16)
    pdf.Cell(40, 10, "Hello World!")
    err := pdf.OutputFileAndClose("hello.pdf")
    if err != nil {
        panic(err)
    }
}

gopdf

المُحافظ: signintech (يتم الحفاظ عليه بشكل نشط).

في لغة Go، واحدة من المكتبات التي تبرز لهذا الغرض هي gopdf، المطورة من قِبل SignInTech. هذه المكتبة توفر طريقة مباشرة لإنشاء PDFs برمجيًا دون الاعتماد على مكتبات خارجية أو مكتبات C.

gopdf هي مكتبة Go чистая مصممة خصيصًا لإنشاء مستندات PDF. توفر واجهة برمجية بسيطة وفعالة تركز بشكل أساسي على إنشاء PDF، مما يجعلها أسهل للاستخدام في المهام الأساسية مع الحفاظ على المرونة المطلوبة للمهام المعقدة.

الميزات الرئيسية:

  • تنفيذ Go чистая: لا حاجة لمكتبات خارجية أو مكتبات C.
  • واجهة برمجية بسيطة: وظائف سهلة الاستخدام لإنشاء PDFs.
  • أداء فعّال: مُحسّنة للحصول على إنشاء PDF سريع وفعّال.

مثال على الاستخدام

لإظهار كيفية استخدام gopdf، دعنا ننظر إلى مثال بسيط لإنشاء مستند PDF بسيط:

package main

import (
    "github.com/signintech/gopdf"
)

func main() {
    // إنشاء مثيل جديد لـ PDF
    pdf := gopdf.New()

    // تحديد حجم الصفحة والهوامش
    pdf.SetPageSize(gopdf.PageSizeA4)
    pdf.AddPage()

    // إضافة بعض النصوص إلى PDF
    pdf.SetFont("Arial", "", 12)
    pdf.Write(50, 50, "Hello, World!")

    // حفظ PDF إلى ملف
    err := pdf.SaveToFile("example.pdf")
    if err != nil {
        panic(err)
    }
}

هذا المثال يوضح كيفية إنشاء مستند PDF جديد، وإضافة نص إليه، وحفظه كملف.

مزايا gopdf المتقدمة:

  • إضافة الصور: يمكنك إدراج صور في مستندات PDF الخاصة بك باستخدام طريقة AddImage.
  • رسم الأشكال: توفر المكتبة وظائف لرسم الخطوط، المستطيلات، والأشكال الأخرى.
  • حماية PDF: يمكنك تعيين حماية بكلمة مرور على PDFs لتحديد الوصول.

pdfcpu

مكتبة قوية أخرى متاحة لمعالجة PDFs في Go هي pdfcpu. توفر هذه المكتبة مجموعة شاملة من الميزات لإنشاء، تعديل، وفحص ملفات PDF عبر واجهة برمجية (API) وواجهة سطر الأوامر (CLI). أدناه نستعرض وصف pdfcpu، أمثلة على الاستخدام، والميزات الرئيسية.

pdfcpu هي مكتبة لمعالجة PDFs مبنية على Go، وتدعم التشفير وتقدم أدوات قوية لمعالجة جوانب مختلفة من مستندات PDF. وهي متوافقة مع جميع إصدارات PDF، بما في ذلك التحسينات المستمرة لـ PDF 2.0 (ISO-32000-2). تهدف المكتبة إلى توفير مجموعة شاملة من ميزات معالجة PDF، مما يجعلها مناسبة لحالات الاستخدام البسيطة والمعقدة.

الميزات الرئيسية

  • دعم التشفير: pdfcpu تدعم التشفير، مما يسمح للمطورين بحماية مستندات PDF بشكل فعّال.
  • API وواجهة سطر الأوامر: توفر واجهة برمجية للاستخدام البرمجي وواجهة سطر الأوامر لإجراء العمليات بسرعة.
  • معالجة دُفعة: دعم قوي لمعالجة الدُفعات عبر واجهة سطر الأوامر الغنية مما يجعلها فعّالة لمعالجة ملفات متعددة في وقت واحد.
  • توافق: متوافقة مع جميع إصدارات PDF، بما في ذلك الدعم الأساسي والتحسينات المستمرة لـ PDF 2.0.

لبدء استخدام pdfcpu، تحتاج إلى تثبيتها باستخدام نظام إدارة حزم Go:

go get github.com/pdfcpu/pdfcpu

العمليات الأساسية عبر واجهة سطر الأوامر

تُوفر pdfcpu مجموعة متنوعة من الأوامر لعمليات مختلفة. إليك بعض الأمثلة:

إنشاء PDF من الصور

يمكنك تحويل ملفات صورة واحدة أو أكثر إلى ملف PDF باستخدام الأوامر التالية:

pdfcpu img2pdf out.pdf image1.jpg image2.png

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

لدمج ملفات PDF متعددة في مستند واحد، استخدم أمر الدمج:

pdfcpu merge output.pdf file1.pdf file2.pdf

مثال على استخدام pdfcpu

لعمليات أكثر تعقيدًا، يمكنك استخدام API المقدمة من pdfcpu. إليك مثالًا على كيفية إنشاء PDF جديد وإضافة نص باستخدام Go:

package main

import (
    "github.com/pdfcpu/pdfcpu"
    "log"
)

func main() {
    // إنشاء مستند PDF جديد
    doc := pdfcpu.NewPDF(0, 0)
    defer doc.Close()

    // إضافة صفحة إلى المستند
    page := doc.AddPage()
    page.SetMediaBox(pdfcpu.MediaBox{
        LLX: 0,
        LLY: 0,
        URX: 612,
        URY: 792,
    })

    // إضافة نص إلى الصفحة
    content := "Hello, World!"
    font := pdfcpu.NewFont("Helvetica", "")
    page.AddText(content, font, 12, 100, 750)

    // حفظ المستند
    err := doc.Save("output.pdf")
    if err != nil {
        log.Fatal(err)
    }
}

هذا المثال يوضح كيفية إنشاء مستند PDF جديد، وإضافة صفحة إليه، وكتابة نص عليه باستخدام API لـ pdfcpu.

Maroto

  • المُحافظ: فريق go-playground (https://github.com/go-playground/maroto).
  • حالات الاستخدام: المطورون الذين يفضلون نهج التصميم أولاً (مثيل Bootstrap).
  • مستوحاة من Bootstrap؛ مصممة لسهولة الاستخدام مع نمط إعلاني مشابه لـ HTML/CSS.
  • مبنية على gofpdf، تبسط عملية الإنشاء مع الحفاظ على خيارات التخصيص القوية.

Maroto هي مكتبة أخرى لـ Go لإنشاء PDFs، لكنها تركز على تبسيط العملية من خلال إخفاء التفاصيل التقنية المنخفضة. تبني على مكتبة gofpdf وتقدم واجهة برمجية أكثر سهولة لإنشاء المستندات.

مثال على استخدام Maroto

هنا مثال على كيفية استخدام Maroto لإنشاء PDF بسيط:

package main

import (
    "github.com/andreyhoffmann1103/maroto"
)

func main() {
    // إنشاء مستند PDF جديد بمقاسات محددة
    m := maroto.NewPDF(595, 842) // مقاس A4 بالنقاط

    // إضافة بعض النصوص إلى الصفحة الأولى
    m.AddText("Hello, Maroto!", 0, 0)

    // حفظ PDF إلى ملف
    err := m.OutputFileAndClose("example.pdf")
    if err != nil {
        panic(err)
    }
}

هذا المثال يوضح كيفية إنشاء مستند PDF جديد مع صفحة واحدة وإضافة نص إليه باستخدام Maroto.

UniPDF

UniPDF هي مكتبة قوية وشاملة أخرى لإنشاء ومعالجة ملفات PDF في Golang (Go). تُقدم مجموعة واسعة من الميزات مما يجعلها شائعة بين المطورين الذين يحتاجون إلى إنشاء، تعديل، واستخراج محتوى من مستندات PDF.

  • المُحافظ: UnidocLib (https://unidoc.io).
  • حالات الاستخدام: معالجة PDF متقدمة (التشفير، الدمج، البرمجة).
  • مكتبة قوية لإنشاء ومعالجة PDF (Go чистая).
  • تقدم ميزات واسعة تشمل العناصر التفاعلية مثل الروابط، العلامات المرجعية، الدمج/التفكيك، التشفير، وغيرها.
  • واجهة برمجية شامِلة لقراءة وكتابة كائنات PDF (القواميس، التدفقات).
  • مناسبة للتطبيقات التي تحتاج إلى قدرات إنشاء PDF قوية.

تثبيت UniPDF

لبدء استخدام UniPDF، تحتاج إلى تثبيت المكتبة. اتبع هذه الخطوات:

# إنشاء دليل جديد:
mkdir go-pdf-generator cd go-pdf-generator
# تهيئة حزمة Go:
go mod init go-pdf-generator
# تثبيت مكتبة UniPDF:
go get github.com/unidoc/unipdf/v3

هذا سيقوم بإعداد مشروعك وتثبيت الاعتماديات اللازمة.

مثال على الاستخدام الأساسي

هنا مثال بسيط لإنشاء مستند PDF باستخدام UniPDF:

package main

import (
    "github.com/unidoc/unipdf/v3/core"
    "github.com/unidoc/unipdf/v3/model"
    "github.com/unidoc/unipdf/v3/creator"
)

func main() {
    // إنشاء مستند PDF جديد
    pdf := creator.New()

    // إضافة صفحة إلى PDF
    page := pdf.NewPage()

    // إعداد تدفق المحتوى للصفحة
    contentStream := model.NewContentStream()
    page.SetContents(contentStream)

    // إضافة نص إلى الصفحة
    text := "Hello, UniPDF!"
    font := creator.NewStandardFont(creator.FontHelvetica)
    textObject := model.NewText(text, font, 12)
    contentStream.Add(textObject)

    // حفظ مستند PDF
    err := pdf.WriteToFile("example.pdf")
    if err != nil {
        panic(err)
    }
}

هذا المثال يوضح كيفية إنشاء مستند PDF جديد، وإضافة صفحة إليه، وكتابة نص عليه. الملف الناتج example.pdf سيحتوي على النص “Hello, UniPDF!”.

مُغطّي wkhtmltopdf

  • https://github.com/SebastiaanKlippert/go-wkhtmltopdf
  • الاعتماد: يتطلب تثبيت wkhtmltopdf عبر brew أو apt-get.
  • حالات الاستخدام: إنشاء PDFs من محتوى HTML ديناميكي (مثل الفواتير، التقارير).

الميزات:

  • تحويل قوالب HTML (التي تُعرض باستخدام html/template في Go) إلى PDF.
  • تخصيص الهوامش، اتجاه الصفحة، والرأس/القدم.
  • مناسب عندما يكون تصميم المستند معقدًا ويضم أسلوب HTML/CSS.
  • يستخدم wkhtmltopdf كخلفية لتحويل محتوى HTML إلى تنسيق PDF.

مثال على استخدام go-wkhtmltopdf

import (
    "bytes"
    "github.com/SebastiaanKlippert/go-wkhtmltopdf"
    "html/template"
)

type PDFService struct {}

func NewPDFService() *PDFService {
    return &PDFService{}
}

func (p PDFService) GeneratePDF(data interface{}) ([]byte, error) {
    var templ *template.Template
    var err error

    if templ, err = template.ParseFiles("pdf-template.html"); err != nil {
        return nil, err
    }

    var body bytes.Buffer
    if err := templ.Execute(&body, data); err != nil {
        return nil, err
    }

    pdfg, err := wkhtmltopdf.NewPDFGenerator()
    if err != nil {
        return nil, err
    }

    page := wkhtmltopdf.NewPageReader(bytes.NewReader(body.Bytes()))
    page.EnableLocalFileAccess.Set(true)

    pdfg.AddPage(page)
    pdfg.MarginLeft.Set(0)
    pdfg.MarginRight.Set(0)
    pdfg.Dpi.Set(300)
    pdfg.PageSize.Set(wkhtmltopdf.PageSizeA4)
    pdfg.Orientation.Set(wkhtmltopdf.OrientationLandscape)

    err = pdfg.Create()
    if err != nil {
        return nil, err
    }

    return pdfg.Bytes(), nil
}

pdflib (من EndFirstCorp):

  • أداة سطر الأوامر لعمليات متعددة على PDF مثل التحقق، التحسين، التقسيم/الدمج.
  • مفيدة لمعالجة الدُفعات ومهام إدارية مرتبطة بمستندات PDF.

نظرة عامة على pdflib

مكتبة pdflib مصممة لتكون معالج PDF شاملة للغة Go. تدعم وظائف متعددة مثل التحقق، التحسين، التقسيم، الدمج، استخراج المحتوى من، وتقليم PDFs. تلتزم المكتبة بمعايير PDF 32000-1:2008 (PDF 1.7)، مما يضمن توافقها مع مجموعة واسعة من مستندات PDF.

الميزات الرئيسية

  • التحقق: تضمن أن ملفات PDF تتوافق مع معيار PDF 1.7.
  • التحسين: تقلل حجم الملف من خلال إزالة الموارد المتكررة.
  • التقسيم والدمج: تسمح بتقسيم مستندات PDF متعددة الصفحات إلى مستندات منفصلة أو دمج عدة PDFs في واحد.
  • الاستخراج: تسمح باستخراج الصور، الخطوط، المحتوى، والصفحات من PDF.
  • التقليم: تُنشئ إصدارات مُقلمة من مستندات PDF.

التركيب

للاستخدام pdflib، تحتاج إلى تثبيتها عبر نظام إدارة حزم Go. يمكنك فعل ذلك من خلال تشغيل:

go get github.com/EndFirstCorp/pdflib

مثال على الاستخدام الأساسي - التحقق من PDF

هنا مثال بسيط يوضح كيفية استخدام مكتبة pdflib لإجراء عمليات PDF الأساسية:

لإجراء تحقق من PDF ضد معيار PDF 1.7، يمكنك استخدام الكود التالي:

package main

import ( "fmt" "github.com/EndFirstCorp/pdflib/cmd/pdflib" )

func main() {
   // التحقق من ملف PDF
   err := pdflib.Validate("example.pdf")
   if err != nil {
     fmt.Println("فشل التحقق:", err)
   } else {
     fmt.Println("PDF صالح.")
   }
}

الخاتمة

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

  • مستندات بسيطة: استخدم gofpdf أو Maroto. هذه المكتبات توفر بساطة وسهولة الاستخدام للمهام البسيطة.
  • تصميم معقد مع HTML/CSS: استخدم wkhtmltopdf Wrapper، الذي يستخدم wkhtmltopdf لمعالجة المحتوى HTML المعقد والأسلوب.
  • معالجة PDF متقدمة: اختر Unipdf أو pdfcpu عندما يحتاج تطبيقك إلى ميزات متقدمة مثل التشفير، العناصر التفاعلية، التنسيق التفصيلي، والقدرة على التعديل الشامل.

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

روابط المكتبات

روابط مفيدة أخرى