Gestione dei documenti

Gestione Documenti

Document è il punto di ingresso per ogni operazione di gestione dei documenti coperta qui: apertura e salvataggio dei file, esportazione in HTML, aggiunta di livelli di contenuto opzionali, creazione di PDF Tagged e lettura o scrittura dei dati AcroForm. Page e Form sono raggiunti tramite Document.Page(n) e Document.Form().

Apertura e Salvataggio dei Documenti

pdf.Open carica un PDF da un percorso file; pdf.OpenWithPassword fa lo stesso per file protetti da password. Document.Save scrive il risultato in un nuovo percorso file.

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

Esportazione in HTML

Document.SaveHTML e Document.WriteHTML convertono un documento in HTML. HTMLSaveOptions.Mode seleziona la rappresentazione: HTMLModeText (testo stilizzato visibile su uno sfondo raster senza glifi), HTMLModeNative (grafica della pagina come un unico livello SVG in linea), o HTMLModeFlow (reflowable HTML con titoli e paragrafi nell’ordine di lettura). Lasciare Mode non impostato produce il valore predefinito fedele: un raster a pagina intera con un livello di testo selezionabile trasparente.

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

Gestione dei Livelli di Contenuto Opzionali

Document.AddLayer(name) crea un nuovo Optional Content Group e restituisce un *Layer; Document.Layers() elenca tutti i layer già presenti. Page.BeginLayer / Page.EndLayer contrassegnano il contenuto della pagina come appartenente a un layer, e Layer.SetVisible(false) nasconde quel contenuto.

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

Creazione di PDF con Tag (Accessibili)

Document.TaggedContent() restituisce la *TaggedContent facade che possiede l’albero della struttura logica del documento e imposta i metadati del catalogo richiesti da PDF/UA. Page.TagContent incornicia una chiamata di disegno in contenuto marcato e restituisce un *StructElement per quel nodo.

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

Anche gli elementi di raggruppamento si annidano sotto la radice dell’albero:

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

Esportazione e importazione dei dati del modulo come JSON

Form.ExportJSON serializza ogni tipo di campo e valore in JSON ({"name": {"type": "text", "value": "Jane"}, ...}); Form.ImportJSON applica un payload JSON a un modulo e restituisce il numero di campi aggiornati. JSONExportOptions.Indent stampa l’output in modo leggibile.

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)

Suggerimenti e migliori pratiche

• Scegli HTMLModeNative per pagine ricche di vettoriali, HTMLModeFlow per la lettura a flusso/mobile, e il valore predefinito fedele (nessun Mode impostato) quando la fedeltà visiva è fondamentale.
• Chiama Layer.SetVisible(false) prima di Save per nascondere i livelli di filigrana o annotazione per impostazione predefinita mantenendo il contenuto indirizzabile tramite l’oggetto Layer.
• Imposta TaggedContent.SetTitle e SetLanguage prima di chiamare Page.TagContent, poiché la convalida PDF/UA verifica i metadati a livello di catalogo scritti da quei metodi.
• Chiama StructElement.SetAlt su ogni nodo StructFigure — le figure senza testo alternativo non superano la convalida PDF/UA.
• Usa JSONExportOptions.Indent per il diff leggibile dall’uomo dello stato del modulo esportato; omettilo per payload compatti macchina-a-macchina.

Problemi comuni

FAQ

Quale modalità di esportazione HTML devo usare?

HTMLModeText per l’output più piccolo e completamente selezionabile; HTMLModeNative quando la fedeltà vettoriale (curve, tratti nativi) è più importante della dimensione del file; HTMLModeFlow per un layout di lettura riformattabile e ottimizzato per mobile. Lascia Mode non impostato per il valore predefinito raster-plus-testo-trasparente fedele.

Posso esportare solo pagine specifiche in HTML?

Sì. Imposta HTMLSaveOptions.Pages su una sequenza di numeri di pagina basati su 1, ad es. pdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []int{1, 3}}}}.

Come nascondere un livello per impostazione predefinita ma consentire a un visualizzatore di riattivarlo?

Chiama Layer.SetVisible(false) prima di salvare. Il livello rimane un Optional Content Group indirizzabile; Layer.IsVisible() segnala il suo stato attuale.

L’esportazione del modulo JSON include i tipi di campo?

Sì. Ogni campo esportato è un oggetto JSON con chiavi type e value, ad es. {"subscribe": {"type": "checkbox", "value": true}}.

Devo chiamare TagContent per ogni elemento, o posso annidare i gruppi direttamente?

Entrambe. Page.TagContent avvolge una chiamata di disegno e aggiunge un elemento di struttura foglia. Per raggruppare elementi (tabelle, elenchi), chiama StructElement.AddChild sulla radice dell’albero o su un elemento genitore per costruire prima l’annidamento, quindi etichetta il contenuto foglia sottostante.

API Reference Riepilogo

Vedi anche

• Aspose.PDF — Enterprise Documentation