Управління документами

Управління документами

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) створює нову Optional Content Group і повертає *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 для зрозумілого для людини порівняння (diff) експортованого стану форми; опускайте його для компактних машинних навантажень.

Поширені проблеми

FAQ

Який режим експорту HTML слід використовувати?

HTMLModeText для найменшого, повністю вибираного виводу; HTMLModeNative, коли важливіша векторна точність (криві, нативні штрихи), ніж розмір файлу; HTMLModeFlow для перелічуваного, мобільно-дружнього макету читання. Залиште Mode незмінним для вірного за замовчуванням raster-plus-transparent-text.

Чи можу я експортувати лише конкретні сторінки до HTML?

Так. Встановіть HTMLSaveOptions.Pages у зріз номерів сторінок, починаючи з 1, наприклад 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