Managementul documentelor

Gestionarea documentelor

Document este punctul de intrare pentru fiecare operație de gestionare a documentelor acoperită aici: deschiderea și salvarea fișierelor, exportul în HTML, adăugarea de straturi de conținut opționale, crearea de PDF cu etichete, și citirea sau scrierea datelor AcroForm. Page și Form sunt accesate prin Document.Page(n) și Document.Form().

Deschiderea și salvarea documentelor

pdf.Open încarcă un PDF dintr-o cale de fișier; pdf.OpenWithPassword face același lucru pentru fișiere protejate prin parolă. Document.Save scrie rezultatul într-o nouă cale de fișier.

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")

Exportarea în HTML

Document.SaveHTML și Document.WriteHTML convertesc un document în HTML. HTMLSaveOptions.Mode selectează reprezentarea: HTMLModeText (text stilizat vizibil peste un fundal raster fără glife), HTMLModeNative (grafica paginii ca un singur strat SVG inline), sau HTMLModeFlow (reflowable HTML cu titluri și paragrafe în ordine de citire). Lăsând Mode nedefinit se produce valoarea implicită fidelă: un raster de pagină completă cu un strat de text selectabil transparent.

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"})

Gestionarea straturilor de conținut opționale

Document.AddLayer(name) creează un nou Grup de Conținut Opțional și returnează un *Layer; Document.Layers() listează fiecare strat deja existent. Page.BeginLayer / Page.EndLayer marchează conținutul paginii ca aparținând unui strat, iar Layer.SetVisible(false) ascunde acel conținut.

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")

Construirea de PDF-uri etichetate (accesibile)

Document.TaggedContent() returnează fațada *TaggedContent care deține arborele de structură logică al documentului și setează metadatele catalogului necesare de PDF/UA. Page.TagContent încadrează un apel de desen în conținut marcat și returnează un *StructElement pentru acel nod.

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")

Elementele grupate se imbrică, de asemenea, sub rădăcina arborelui:

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 })

Exportarea și importarea datelor de formular ca JSON

Form.ExportJSON serializează fiecare tip de câmp și valoare în JSON ({"name": {"type": "text", "value": "Jane"}, ...}); Form.ImportJSON aplică o sarcină JSON unui formular și returnează numărul de câmpuri actualizate. JSONExportOptions.Indent tipărește frumos rezultatul.

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)

Sfaturi și cele mai bune practici

• Alegeți HTMLModeNative pentru pagini cu mult conținut vectorial, HTMLModeFlow pentru citire în flux/rețea mobilă și setarea implicită de încredere (fără Mode setat) când fidelitatea vizuală este cea mai importantă.
• Apelă Layer.SetVisible(false) înainte de Save pentru a ascunde implicit marcajul sau straturile de adnotare, menținând în același timp conținutul adresabil prin obiectul Layer.
• Setează TaggedContent.SetTitle și SetLanguage înainte de a apela Page.TagContent, deoarece validarea PDF/UA verifică metadatele la nivel de catalog pe care acele metode le scriu.
• Apelă StructElement.SetAlt pe fiecare nod StructFigure — imaginile fără text alternativ eșuează validarea PDF/UA.
• Folosește JSONExportOptions.Indent pentru difuzarea lizibilă de către om a stării formularului exportat; omite-l pentru încărcături compacte de tip mașină-la-mașină.

Probleme comune

FAQ

Ce mod de export HTML ar trebui să folosesc?

HTMLModeText pentru cea mai mică ieșire complet selectabilă; HTMLModeNative când fidelitatea vectorială (curbe, contururi native) contează mai mult decât dimensiunea fișierului; HTMLModeFlow pentru un aranjament de lectură reîncărcabil, prietenos cu dispozitivele mobile. Lasă Mode nedefinit pentru setarea implicită fidelă raster-plus-text-transparent.

Pot exporta doar pagini specifice în HTML?

Da. Setează HTMLSaveOptions.Pages la o secvență de numere de pagină începând de la 1, de exemplu pdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []int{1, 3}}}}.

Cum pot ascunde implicit un strat, dar să permit vizualizatorului să îl reactiveze?

Apelează Layer.SetVisible(false) înainte de salvare. Stratul rămâne un Optional Content Group adresabil; Layer.IsVisible() raportează starea curentă a acestuia.

Exportul formularului JSON include tipurile de câmp?

Da. Fiecare câmp exportat este un obiect JSON cu cheile type și value, de exemplu {"subscribe": {"type": "checkbox", "value": true}}.

Trebuie să apelez TagContent pentru fiecare element sau pot imbrica grupurile direct?

Ambele. Page.TagContent învelește un apel de desenare și adaugă un element de structură leaf. Pentru elemente de grupare (tabele, liste), apelează StructElement.AddChild pe rădăcina arborelui sau pe un element părinte pentru a construi mai întâi imbricarea, apoi etichetează conținutul leaf dedesubt.

API Reference Rezumat

Vezi și:

• Aspose.PDF — Enterprise Documentation