Gerenciamento de Documentos

Gerenciamento de Documentos

Document é o ponto de entrada para todas as operações de gerenciamento de documentos abordadas aqui: abrir e salvar arquivos, exportar para HTML, adicionar camadas de conteúdo opcionais, criar PDF com tags e ler ou gravar dados AcroForm. Page e Form são acessados através de Document.Page(n) e Document.Form().

Abrindo e Salvando Documentos

pdf.Open carrega um PDF a partir de um caminho de arquivo; pdf.OpenWithPassword faz o mesmo para arquivos protegidos por senha. Document.Save grava o resultado em um novo caminho de arquivo.

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

Exportando para HTML

Document.SaveHTML e Document.WriteHTML convertem um documento para HTML. HTMLSaveOptions.Mode seleciona a representação: HTMLModeText (texto estilizado visível sobre um fundo raster sem glifos), HTMLModeNative (gráficos de página como uma camada SVG inline), ou HTMLModeFlow (refluível HTML com títulos e parágrafos na ordem de leitura). Deixar Mode não definido produz o padrão fiel: um raster de página inteira com uma camada de texto selecionável transparente.

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

Gerenciando Camadas de Conteúdo Opcional

Document.AddLayer(name) cria um novo Optional Content Group e retorna um *Layer; Document.Layers() lista todas as camadas já presentes. Page.BeginLayer / Page.EndLayer marcam o conteúdo da página como pertencente a uma camada, e Layer.SetVisible(false) oculta esse conteúdo.

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

Criando PDFs Tagged (Acessíveis)

Document.TaggedContent() retorna a fachada *TaggedContent que possui a árvore de estrutura lógica do documento e define os metadados do catálogo que PDF/UA exige. Page.TagContent envolve uma chamada de desenho em conteúdo marcado e retorna um *StructElement para esse nó.

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

Os elementos agrupados também são aninhados sob a raiz da árvore:

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

Exportando e importando dados de formulário como JSON

Form.ExportJSON serializa cada tipo de campo e valor para JSON ({"name": {"type": "text", "value": "Jane"}, ...}); Form.ImportJSON aplica uma carga JSON a um formulário e devolve o número de campos que atualizou. JSONExportOptions.Indent formata a saída de forma legível.

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)

Dicas e melhores práticas

• Escolha HTMLModeNative para páginas com muitos vetores, HTMLModeFlow para leitura reflow/móvel, e o padrão fiel (sem Mode definido) quando a fidelidade visual é mais importante.
• Chame Layer.SetVisible(false) antes de Save para ocultar marcas d’água ou camadas de anotação por padrão, mantendo o conteúdo endereçável através do objeto Layer.
• Defina TaggedContent.SetTitle e SetLanguage antes de chamar Page.TagContent, pois a validação PDF/UA verifica os metadados ao nível do catálogo que esses métodos gravam.
• Chame StructElement.SetAlt em cada nó StructFigure — figuras sem texto alternativo falham na validação PDF/UA.
• Use JSONExportOptions.Indent para diff legível por humanos do estado do formulário exportado; omita-o para cargas úteis compactas de máquina-para-máquina.

Problemas comuns

FAQ

Qual modo de exportação HTML devo usar?

HTMLModeText para a saída mais pequena e totalmente selecionável; HTMLModeNative quando a fidelidade vetorial (curvas, traços nativos) é mais importante que o tamanho do arquivo; HTMLModeFlow para um layout de leitura refluível e amigável a dispositivos móveis. Deixe Mode não definido para o padrão de raster-mais-texto-transparente fiel.

Posso exportar apenas páginas específicas para HTML?

Sim. Defina HTMLSaveOptions.Pages como uma fatia de números de página baseados em 1, por exemplo pdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []int{1, 3}}}}.

Como oculto uma camada por padrão, mas permito que o visualizador a ative novamente?

Chame Layer.SetVisible(false) antes de salvar. A camada continua sendo um Optional Content Group endereçável; Layer.IsVisible() informa seu estado atual.

A exportação de formulário JSON inclui tipos de campo?

Sim. Cada campo exportado é um objeto JSON com chaves type e value, por exemplo {"subscribe": {"type": "checkbox", "value": true}}.

Preciso chamar TagContent para cada elemento, ou posso aninhar grupos diretamente?

Ambos. Page.TagContent envolve uma chamada de desenho e adiciona um elemento de estrutura final. Para agrupar elementos (tabelas, listas), chame StructElement.AddChild na raiz da árvore ou em um elemento pai para criar a hierarquia primeiro, e então marque o conteúdo final abaixo.

API Reference Resumo

Ver também

• Aspose.PDF — Enterprise Documentation