إدارة المستندات

إدارة المستندات

Document هو نقطة الدخول لكل عملية إدارة مستندات مغطاة هنا: فتح وحفظ الملفات، التصدير إلى HTML، إضافة طبقات محتوى اختيارية، إنشاء PDF مع علامات، وقراءة أو كتابة بيانات AcroForm. يتم الوصول إلى Page وForm عبر Document.Page(n) وDocument.Form().

فتح وحفظ المستندات

pdf.Open يحمل ملف PDF من مسار ملف؛ pdf.OpenWithPassword يقوم بالمثل للملفات المحمية بكلمة مرور. Document.Save يكتب النتيجة إلى مسار ملف جديد.

doc, err := pdf.Open("input.pdf")
if err != nil {
	panic(err)
}

_, err = pdf.OpenWithPassword("locked.pdf", "userpassword")
if err != nil {
	panic(err)
}

err = doc.Save("output.pdf")

التصدير إلى HTML

Document.SaveHTML و Document.WriteHTML يحولان مستندًا إلى HTML. HTMLSaveOptions.Mode يختار التمثيل: HTMLModeText (نص مرئي منسق فوق خلفية نقطية بدون رموز)، HTMLModeNative (رسومات الصفحة كطبقة SVG مدمجة واحدة)، أو HTMLModeFlow (HTML قابل لإعادة التدفق مع عناوين وفقرة بترتيب القراءة). ترك Mode غير محدد ينتج الإعداد الافتراضي الدقيق: صفحة نقطية كاملة مع طبقة نص شفافة قابلة للتحديد.

doc, _ := pdf.Open("input.pdf")

// Faithful mode (default)
doc.SaveHTML("out.html")

// Visible-text mode
doc.SaveHTML("out.html", pdf.HTMLSaveOptions{Mode: pdf.HTMLModeText})

// Multi-file output: external resources plus one HTML file per page
doc.SaveHTML("site/doc.html", pdf.HTMLSaveOptions{
    Mode: pdf.HTMLModeNative, ResourceDir: "assets", SplitPages: true,
})

// Page subset, custom raster DPI and title
doc.SaveHTML("part.html", pdf.HTMLSaveOptions{Pages: []int{1, 3}, DPI: 96, Title: "Report"})

إدارة طبقات المحتوى الاختيارية

Document.AddLayer(name) ينشئ مجموعة محتوى اختيارية جديدة ويعيد *Layer; Document.Layers() يسرد كل الطبقة الموجودة بالفعل. Page.BeginLayer / Page.EndLayer يحددان محتوى الصفحة كجزء من طبقة، وLayer.SetVisible(false) يخفي ذلك المحتوى.

doc := pdf.NewDocumentFromFormat(pdf.PageFormatA4)
layer := doc.AddLayer("Watermark")

page, _ := doc.Page(1)
page.BeginLayer(layer)
page.AddText("DRAFT", pdf.TextStyle{Font: pdf.FontHelveticaBold, Size: 48},
    pdf.Rectangle{LLX: 150, LLY: 400, URX: 450, URY: 460})
page.EndLayer()

layer.SetVisible(false)
doc.Save("layered.pdf")

إنشاء ملفات PDF مُوسومة (قابلة للوصول)

Document.TaggedContent() يعيد الواجهة *TaggedContent التي تمتلك شجرة البنية المنطقية للمستند وتُعيّن بيانات تعريف الكتالوج التي يتطلبها PDF/UA. Page.TagContent يحيط استدعاء الرسم في المحتوى المعلَّم ويعيد *StructElement لتلك العقدة.

doc := pdf.NewDocumentFromFormat(pdf.PageFormatA4)
tc := doc.TaggedContent()
tc.SetTitle("Quarterly Report")
tc.SetLanguage("en-US")
page, _ := doc.Page(1)

page.TagContent(tc.Root(), pdf.StructH1, func() error {
    return page.AddText("Quarterly Report", pdf.TextStyle{Font: pdf.FontHelveticaBold, Size: 24},
        pdf.Rectangle{LLX: 50, LLY: 760, URX: 545, URY: 800})
})
fig, _ := page.TagContent(tc.Root(), pdf.StructFigure, func() error {
    return page.AddImage("chart.png", pdf.Rectangle{LLX: 50, LLY: 540, URX: 300, URY: 680})
})
fig.SetAlt("Bar chart of Q3 sales by region") // required for figures

doc.Save("accessible.pdf")

تجميع العناصر يتداخل أيضًا تحت جذر الشجرة:

doc := pdf.NewDocumentFromFormat(pdf.PageFormatA4)
tc := doc.TaggedContent()
page, _ := doc.Page(1)

tbl := tc.Root().AddChild(pdf.StructTable)
row := tbl.AddChild(pdf.StructTR)
cell := row.AddChild(pdf.StructTD)
page.TagContent(cell, pdf.StructP, func() error { return nil })

تصدير واستيراد بيانات النماذج كـ JSON

Form.ExportJSON يسلّس كل نوع حقل وقيمته إلى JSON ({"name": {"type": "text", "value": "Jane"}, ...}); Form.ImportJSON يطبق حمولة JSON على نموذج ويعيد عدد الحقول التي تم تحديثها. JSONExportOptions.Indent يطبع الإخراج بشكل مُنسّق.

doc, _ := pdf.Open("filled.pdf")
data, _ := doc.Form().ExportJSON(pdf.JSONExportOptions{Indent: true})

// Fill a template from a JSON payload; discard the applied-field count.
template, _ := pdf.Open("template.pdf")
_, _ = template.Form().ImportJSON(data)

نصائح وأفضل الممارسات

• اختر HTMLModeNative للصفحات ذات المحتوى المتجهي الكثيف، HTMLModeFlow للقراءة المتدفقة/المحمولة، والافتراضي الدقيق (بدون تعيين Mode) عندما تكون الدقة البصرية هي الأهم.
• استدعِ Layer.SetVisible(false) قبل Save لإخفاء طبقة العلامة المائية أو التعليقات التوضيحية افتراضيًا مع الحفاظ على إمكانية توجيه المحتوى عبر كائن Layer.
• عيّن TaggedContent.SetTitle وSetLanguage قبل استدعاء Page.TagContent، لأن التحقق من PDF/UA يراجع بيانات التعريف على مستوى الفهرس التي تكتبها تلك الطرق.
• استدعِ StructElement.SetAlt على كل عقدة StructFigure — الرسومات التي لا تحتوي على نص بديل تفشل في التحقق من PDF/UA.
• استخدم JSONExportOptions.Indent للمقارنة القابلة للقراءة من قبل الإنسان لحالة النموذج المصدَّر؛ احذفها للحمولات المدمجة بين الآلات.

المشكلات الشائعة

FAQ

أي وضع تصدير HTML يجب أن أستخدمه؟

HTMLModeText للحصول على أصغر إخراج قابل للتحديد بالكامل؛ HTMLModeNative عندما تكون دقة المتجهات (المنحنيات، الضربات الأصلية) أهم من حجم الملف؛ HTMLModeFlow لتخطيط قراءة قابل لإعادة التدفق ومناسب للهواتف المحمولة. اترك Mode غير مُعيّن للافتراضي الدقيق للراستر مع النص الشفاف.

هل يمكنني تصدير صفحات محددة فقط إلى HTML؟

نعم. اضبط HTMLSaveOptions.Pages على مقطع من أرقام الصفحات التي تبدأ من 1، مثال: pdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []int{1, 3}}}}.

كيف يمكنني إخفاء طبقة بشكل افتراضي ولكن أسمح للمشاهد بإعادة تشغيلها؟

استدعِ Layer.SetVisible(false) قبل الحفظ. تبقى الطبقة مجموعة محتوى اختيارية قابلة للعنونة؛ Layer.IsVisible() تُبلغ عن حالتها الحالية.

هل يتضمن تصدير نموذج JSON أنواع الحقول؟

نعم. كل حقل مُصدَّر هو كائن JSON يحتوي على مفاتيح type و value، مثال: {"subscribe": {"type": "checkbox", "value": true}}.

هل يجب علي استدعاء TagContent لكل عنصر، أم يمكنني تضمين المجموعات مباشرةً؟

كلاهما. Page.TagContent يلف استدعاء الرسم ويضيف عنصر بنية ورقي. لتجميع العناصر (الجداول، القوائم)، استدعِ StructElement.AddChild على جذر الشجرة أو عنصر أب لتكوين التضمين أولاً، ثم ضع علامة على المحتوى الورقي تحته.

API Reference ملخص

انظر أيضاً

• Aspose.PDF — Enterprise Documentation