Paquete gpdf

Descripcion general

El paquete gpdf es una fachada que reexporta funciones de uso comun de las capas internas. Puede importar gpdf por conveniencia o importar los paquetes especificos directamente.

import "github.com/gpdf-dev/gpdf"

// Using facade
doc := gpdf.NewDocument(gpdf.WithPageSize(gpdf.A4))

import (
    "github.com/gpdf-dev/gpdf/template"
    "github.com/gpdf-dev/gpdf/document"
)

// Using packages directly (recommended)
doc := template.New(template.WithPageSize(document.A4))

Funciones

NewDocument

func NewDocument(opts ...template.Option) *template.Document

Crea un nuevo constructor de documentos PDF. Este es el punto de entrada principal.

doc := gpdf.NewDocument(
    gpdf.WithPageSize(gpdf.A4),
    gpdf.WithMargins(document.UniformEdges(document.Mm(20))),
)

FromJSON

func FromJSON(schema []byte, data any, opts ...template.Option) (*template.Document, error)

Crea un Document a partir de una definicion de esquema JSON con enlace de datos opcional de Go template.

doc, err := gpdf.FromJSON(schema, map[string]any{"title": "Report"})

FromTemplate

func FromTemplate(tmpl *template.Template, data any, opts ...template.Option) (*template.Document, error)

Crea un Document ejecutando un Go template preparsado que produce salida de esquema JSON.

TemplateFuncMap

func TemplateFuncMap() template.FuncMap

Devuelve funciones auxiliares (toJSON, etc.) para usar al analizar Go templates.

Opciones del documento

Funcion	Descripcion
`WithPageSize(size)`	Establecer dimensiones de pagina (`A4`, `A3`, `Letter`, `Legal`)
`WithMargins(edges)`	Establecer margenes de pagina
`WithFont(family, data)`	Registrar una fuente TrueType (acepta `[]byte`)
`WithDefaultFont(family, size)`	Establecer la familia y tamano de fuente predeterminados
`WithMetadata(meta)`	Establecer metadatos del documento
`WithEncryption(opts...)`	Habilitar encriptación AES-256
`WithPDFA(opts...)`	Habilitar conformidad PDF/A

Metadatos del documento

gpdf.WithMetadata(document.DocumentMetadata{
    Title:   "Invoice #INV-2026-001",
    Author:  "ACME Corporation",
    Subject: "Monthly Invoice",
    Creator: "gpdf v1.0.4",
})

Tamanos de pagina

Constante	Dimensiones
`gpdf.A4` / `document.A4`	210mm x 297mm (595.28pt x 841.89pt)
`gpdf.A3` / `document.A3`	297mm x 420mm (841.89pt x 1190.55pt)
`gpdf.Letter` / `document.Letter`	8.5" x 11" (612pt x 792pt)
`gpdf.Legal` / `document.Legal`	8.5" x 14" (612pt x 1008pt)

Metodos del documento

AddPage

func (d *Document) AddPage() *PageBuilder

Agrega una nueva pagina y devuelve su constructor.

Header / Footer

func (d *Document) Header(fn func(p *PageBuilder))
func (d *Document) Footer(fn func(p *PageBuilder))

Define contenido que se repite en cada pagina.

Generate / Render

func (d *Document) Generate() ([]byte, error)
func (d *Document) Render(w io.Writer) error

Generate() devuelve el PDF como un segmento de bytes. Render() escribe directamente en un io.Writer.

Metodos de PageBuilder

Row

func (p *PageBuilder) Row(height document.Value, fn func(r *RowBuilder))
func (p *PageBuilder) AutoRow(fn func(r *RowBuilder))

Row() crea una fila de altura fija. AutoRow() crea una fila que se ajusta al contenido.

Metodos de RowBuilder

Col

func (r *RowBuilder) Col(span int, fn func(c *ColBuilder))

Crea una columna que abarca span de las 12 columnas de la cuadricula.

Metodos de ColBuilder

Metodo	Descripcion
`Text(text, opts...)`	Agregar texto con opciones de estilo
`Image(data, opts...)`	Agregar una imagen (bytes JPEG o PNG)
`Table(headers, rows, opts...)`	Agregar una tabla
`List(items, opts...)`	Agregar una lista desordenada
`OrderedList(items, opts...)`	Agregar una lista ordenada
`Line(opts...)`	Agregar una linea horizontal
`Spacer(height)`	Agregar espacio vertical
`QRCode(data, opts...)`	Agregar un codigo QR
`Barcode(data, opts...)`	Agregar un codigo de barras (Code 128)
`RichText(fn)`	Agregar texto en linea de estilo mixto
`PageNumber(opts...)`	Numero de pagina actual
`TotalPages(opts...)`	Total de paginas

Opciones de codigo QR

Funcion	Descripcion
`QRSize(value)`	Tamano de visualizacion (ancho = alto)
`QRErrorCorrection(level)`	Correccion de errores: `LevelL`, `LevelM`, `LevelQ`, `LevelH`
`QRScale(s)`	Pixeles por modulo QR

Opciones de codigo de barras

Funcion	Descripcion
`BarcodeWidth(value)`	Ancho de visualizacion
`BarcodeHeight(value)`	Alto de visualizacion
`BarcodeFormat(format)`	Formato de codigo de barras (predeterminado: Code 128)

Operaciones con PDF existente

Open

func Open(data []byte, opts ...template.Option) (*template.ExistingDocument, error)

Abre un PDF existente para lectura y modificacion. Devuelve un ExistingDocument que soporta operaciones de superposicion mediante Actualizacion Incremental (adicion no destructiva).

doc, err := gpdf.Open(pdfBytes)

Metodos de ExistingDocument

Metodo	Descripcion
`PageCount() (int, error)`	Devuelve el numero de paginas en el PDF
`Overlay(pageIndex int, fn func(p *PageBuilder)) error`	Agregar contenido sobre una pagina especifica (indice basado en 0)
`EachPage(fn func(pageIndex int, p *PageBuilder)) error`	Agregar contenido sobre cada pagina
`FlattenForms() error`	Aplanar todos los campos AcroForm en contenido de pagina estatico Since v1.0.4
`Save() ([]byte, error)`	Devuelve el PDF modificado como segmento de bytes

doc, err := gpdf.Open(pdfBytes, gpdf.WithFont("NotoSans", fontData))

// Add watermark on page 1
doc.Overlay(0, func(p *template.PageBuilder) {
    p.Absolute(document.Mm(40), document.Mm(120), func(c *template.ColBuilder) {
        c.Text("DRAFT", template.FontSize(72),
            template.TextColor(pdf.Gray(0.85)))
    })
})

// Add page numbers on every page
count, _ := doc.PageCount()
doc.EachPage(func(i int, p *template.PageBuilder) {
    p.Absolute(document.Mm(170), document.Mm(285), func(c *template.ColBuilder) {
        c.Text(fmt.Sprintf("%d / %d", i+1, count),
            template.FontSize(10), template.AlignRight())
    }, template.AbsoluteWidth(document.Mm(20)))
})

result, err := doc.Save()

Fusion de PDF Since v1.0.2

Merge

func Merge(sources []Source, opts ...MergeOption) ([]byte, error)

Combina paginas de multiples fuentes PDF en un solo PDF de salida.

Source

type Source struct {
    Data  []byte    // bytes PDF sin procesar
    Pages PageRange // paginas a incluir; valor cero = todas las paginas
}

PageRange

type PageRange struct {
    From int  // pagina inicial base 1; 0 = primera pagina
    To   int  // pagina final base 1; 0 = ultima pagina
}

Opciones de fusion

Funcion	Descripcion
`WithMergeMetadata(title, author, producer)`	Establecer informacion del documento (titulo, autor, productor) en la salida fusionada

Constructores de componentes

Funcion	Descripcion
`NewInvoice(data)`	Crear un PDF de factura
`NewReport(data)`	Crear un PDF de informe
`NewLetter(data)`	Crear un PDF de carta comercial

Consulte Componentes para uso detallado.