Gestión de documentos

Gestión de Documentos

Document es el punto de entrada para cada operación de gestión de documentos cubierta aquí: abrir y guardar archivos, exportar a HTML, añadir capas de contenido opcional, crear PDF etiquetado y leer o escribir datos AcroForm. Page y Form se alcanzan a través de Document.Page(n) y Document.Form().

Abrir y Guardar Documentos

pdf.Open carga un PDF desde una ruta de archivo; pdf.OpenWithPassword hace lo mismo con archivos protegidos con contraseña. Document.Save escribe el resultado en una nueva ruta de archivo.

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

Exportar a HTML

Document.SaveHTML y Document.WriteHTML convierten un documento a HTML. HTMLSaveOptions.Mode selecciona la representación: HTMLModeText (texto con estilo visible sobre un fondo raster sin glifos), HTMLModeNative (gráficos de página como una sola capa SVG en línea), o HTMLModeFlow ( HTML refluible con encabezados y párrafos en orden de lectura). Dejar Mode sin establecer produce el valor predeterminado fiel: un raster de página completa con una capa de texto seleccionable y 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"})

Gestionar Capas de Contenido Opcional

Document.AddLayer(name) crea un nuevo Grupo de Contenido Opcional y devuelve un *Layer; Document.Layers() enumera cada capa ya presente. Page.BeginLayer / Page.EndLayer marcan el contenido de la página como perteneciente a una capa, y Layer.SetVisible(false) oculta ese contenido.

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

Creación de PDFs etiquetados (accesibles)

Document.TaggedContent() devuelve la fachada *TaggedContent que posee el árbol de estructura lógica del documento y establece los metadatos del catálogo que requiere PDF/UA. Page.TagContent encierra una llamada de dibujo en contenido marcado y devuelve un *StructElement para ese 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")

Los elementos de agrupación también se anidan bajo la raíz del árbol:

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

Exportar e importar datos de formularios como JSON

Form.ExportJSON serializa cada tipo de campo y valor a JSON ({"name": {"type": "text", "value": "Jane"}, ...}); Form.ImportJSON aplica una carga útil JSON a un formulario y devuelve el número de campos que actualizó. JSONExportOptions.Indent muestra la salida con formato legible.

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)

Consejos y mejores prácticas

• Elija HTMLModeNative para páginas con mucho vector, HTMLModeFlow para lectura refluida/móvil, y el predeterminado fiel (sin Mode configurado) cuando la fidelidad visual es lo más importante.
• Llame a Layer.SetVisible(false) antes de Save para ocultar la marca de agua o las capas de anotación de forma predeterminada mientras mantiene el contenido direccionable a través del objeto Layer.
• Establezca TaggedContent.SetTitle y SetLanguage antes de llamar a Page.TagContent, ya que la validación de PDF/UA verifica los metadatos a nivel de catálogo que esos métodos escriben.
• Ejecute StructElement.SetAlt en cada nodo StructFigure — las figuras sin texto alternativo no pasan la validación de PDF/UA.
• Utilice JSONExportOptions.Indent para la comparación legible por humanos del estado del formulario exportado; omítalo para cargas útiles compactas de máquina a máquina.

Problemas comunes

FAQ

¿Qué modo de exportación HTML debería usar?

HTMLModeText para la salida más pequeña y totalmente seleccionable; HTMLModeNative cuando la fidelidad vectorial (curvas, trazos nativos) es más importante que el tamaño del archivo; HTMLModeFlow para un diseño de lectura refluible y optimizado para móviles. Deje Mode sin establecer para el valor predeterminado de raster+texto transparente fiel.

¿Puedo exportar solo páginas específicas a HTML?

Sí. Establezca HTMLSaveOptions.Pages a una porción de números de página basados en 1, p. ej. pdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []intpdf.HTMLSaveOptions{Pages: []int{1, 3}}}}.

¿Cómo oculto una capa por defecto pero permito que el visor la vuelva a activar?

Llame a Layer.SetVisible(false) antes de guardar. La capa sigue siendo un Optional Content Group direccionable; Layer.IsVisible() informa su estado actual.

¿La exportación del formulario JSON incluye tipos de campo?

Sí. Cada campo exportado es un objeto JSON con claves type y value, p. ej. {"subscribe": {"type": "checkbox", "value": true}}.

¿Necesito llamar a TagContent para cada elemento, o puedo anidar los grupos directamente?

Ambos. Page.TagContent envuelve una llamada de dibujo y añade un elemento de estructura hoja. Para agrupar elementos (tablas, listas), llame a StructElement.AddChild en la raíz del árbol o en un elemento padre para crear primero la anidación, y luego etiquete el contenido hoja debajo.

API Reference Resumen

Ver también

• Aspose.PDF — Enterprise Documentation