مدیریت اسناد

مدیریت اسناد

Document نقطه ورود برای هر عملیات مدیریت اسناد که در اینجا پوشش داده شده است: باز کردن و ذخیره‌سازی فایل‌ها، صادر کردن به HTML، افزودن لایه‌های محتوای اختیاری، ایجاد Tagged 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 façade را برمی‌گرداند که درخت ساختار منطقی سند را در اختیار دارد و متادیتای کاتالوگ را که 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) را زمانی که دقت بصری بیشترین اهمیت را دارد، استفاده کنید.
• قبل از Save، Layer.SetVisible(false) را فراخوانی کنید تا به‌طور پیش‌فرض لایه‌های واترمارک یا حاشیه‌نویسی پنهان شوند، در حالی که محتوا از طریق شیء Layer قابل آدرس‌گذاری باقی می‌ماند.
• قبل از فراخوانی Page.TagContent، TaggedContent.SetTitle و SetLanguage را تنظیم کنید، زیرا اعتبارسنجی PDF/UA متادیتای سطح فهرست را که این روش‌ها می‌نویسند بررسی می‌کند.
• در هر گره StructFigure، StructElement.SetAlt را فراخوانی کنید — شکل‌هایی که متن جایگزین ندارند، اعتبارسنجی PDF/UA را رد می‌کنند.
• برای مقایسهٔ قابل خواندن توسط انسان از وضعیت فرم صادر شده از JSONExportOptions.Indent استفاده کنید؛ برای بارهای دادهٔ فشردهٔ ماشین-به-ماشین آن را حذف کنید.

مشکلات رایج

FAQ

کدام حالت صادرات HTML را باید استفاده کنم؟

HTMLModeText برای کوچک‌ترین خروجی که به‌طور کامل قابل انتخاب است؛ HTMLModeNative وقتی که دقت برداری (منحنی‌ها، خطوط بومی) مهم‌تر از اندازهٔ فایل است؛ HTMLModeFlow برای یک طرح خواندن قابل باز‌جریان و مناسب برای موبایل. برای تنظیم پیش‌فرض رستر-به‌همراه-متن-شفاف، Mode را خالی بگذارید.

آیا می‌توانم فقط صفحات خاصی را به HTML صادر کنم؟

بله. HTMLSaveOptions.Pages را به یک برش از شماره‌های صفحات ۱-محور تنظیم کنید، مثلاً pdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []int{1, 3}}}}.

چگونه می‌توانم یک لایه را به‌طور پیش‌فرض مخفی کنم اما به کاربر اجازه دهم آن را دوباره فعال کند؟

Layer.SetVisible(false) را قبل از ذخیره‌سازی فراخوانی کنید. لایه به‌عنوان یک Optional Content Group قابل دسترسی باقی می‌ماند؛ Layer.IsVisible() وضعیت فعلی آن را گزارش می‌دهد.

آیا صادرات فرم JSON شامل انواع فیلدها می‌شود؟

بله. هر فیلد صادر شده یک شیء JSON با کلیدهای type و value است، مثلاً {"subscribe": {"type": "checkbox", "value": true}}.

آیا باید برای هر عنصر TagContent را فراخوانی کنم، یا می‌توانم گروه‌ها را مستقیماً تو در تو کنم؟

هر دو. Page.TagContent یک فراخوانی رسم را می‌پیچد و یک عنصر ساختار برگ اضافه می‌کند. برای گروه‌بندی عناصر (جدول‌ها، فهرست‌ها)، ابتدا StructElement.AddChild را روی ریشه درخت یا یک عنصر والد فراخوانی کنید تا تو در تویی را بسازید، سپس محتوای برگ زیرین را برچسب‌گذاری کنید.

API Reference خلاصه

همچنین ببینید:

• Aspose.PDF — Enterprise Documentation