gpdf

Elementos

Texto

El elemento mas fundamental. Agregue texto con estilo opcional:

c.Text("Hello, World!")
c.Text("Styled text", template.FontSize(18), template.Bold())
c.Text("Red centered", template.TextColor(pdf.Red), template.AlignCenter())

Opciones de texto

OpcionDescripcion
FontSize(size)Tamano de fuente en puntos (predeterminado: 12)
Bold()Peso negrita
Italic()Estilo cursiva
FontFamily(name)Usar una fuente registrada
TextColor(color)Color de primer plano
BgColor(color)Color de fondo
AlignLeft()Alineacion izquierda (predeterminado)
AlignCenter()Alineacion centrada
AlignRight()Alineacion derecha
Underline()Decoracion de subrayado
Strikethrough()Decoracion de tachado
LetterSpacing(pts)Espacio adicional entre caracteres
TextIndent(value)Sangria de primera linea

Texto enriquecido

Texto en linea de estilo mixto usando RichText():

c.RichText(func(rt *template.RichTextBuilder) {
    rt.Span("Normal text ")
    rt.Span("bold", template.Bold())
    rt.Span(" and ")
    rt.Span("red", template.TextColor(pdf.Red))
    rt.Span(" in one line.")
})

┌─────────────────────────────────────────────┐
│  Normal text bold and red in one line.      │
│              ^^^^     ^^^                   │
│              bold     red color             │
└─────────────────────────────────────────────┘

Tabla

Tablas con encabezados y filas de datos:

// Basic table
c.Table(
    []string{"Name", "Age", "City"},
    [][]string{
        {"Alice", "30", "Tokyo"},
        {"Bob", "25", "New York"},
        {"Charlie", "35", "London"},
    },
)

┌──────────┬──────┬──────────┐
│  Name    │ Age  │  City    │ ← encabezado (negrita)
├──────────┼──────┼──────────┤
│  Alice   │  30  │  Tokyo   │
│  Bob     │  25  │  New York│
│  Charlie │  35  │  London  │
└──────────┴──────┴──────────┘

Tabla con estilo

darkBlue := pdf.RGBHex(0x1A237E)
lightGray := pdf.RGBHex(0xF5F5F5)

c.Table(
    []string{"Product", "Category", "Qty", "Unit Price", "Total"},
    [][]string{
        {"Laptop Pro 15", "Electronics", "2", "$1,299.00", "$2,598.00"},
        {"Wireless Mouse", "Accessories", "10", "$29.99", "$299.90"},
        {"USB-C Hub", "Accessories", "5", "$49.99", "$249.95"},
        {"Monitor 27\"", "Electronics", "3", "$399.00", "$1,197.00"},
        {"Keyboard", "Accessories", "10", "$79.99", "$799.90"},
        {"Webcam HD", "Electronics", "4", "$89.99", "$359.96"},
    },
    template.ColumnWidths(30, 20, 10, 20, 20),
    template.TableHeaderStyle(
        template.TextColor(pdf.White),
        template.BgColor(darkBlue),
    ),
    template.TableStripe(lightGray),
)

┌─────────────┬────────────┬─────┬───────────┬──────────┐
│  Product    │  Category  │ Qty │Unit Price │  Total   │ ← blanco sobre azul oscuro
├─────────────┼────────────┼─────┼───────────┼──────────┤
│  Laptop Pro │ Electronics│  2  │ $1,299.00 │$2,598.00 │ ← fondo blanco
│  Wireless.. │ Accessories│ 10  │    $29.99 │  $299.90 │ ← franja gris
│  USB-C Hub  │ Accessories│  5  │    $49.99 │  $249.95 │ ← fondo blanco
│  Monitor 27"│ Electronics│  3  │   $399.00 │$1,197.00 │ ← franja gris
│  Keyboard   │ Accessories│ 10  │    $79.99 │  $799.90 │ ← fondo blanco
│  Webcam HD  │ Electronics│  4  │    $89.99 │  $359.96 │ ← franja gris
└─────────────┴────────────┴─────┴───────────┴──────────┘

Opciones de tabla

OpcionDescripcion
ColumnWidths(widths...)Porcentajes de ancho de columna (deben sumar 100)
ColumnAlign(aligns...) Since v1.0.10 Alineacion horizontal por columna: AlignLeft, AlignCenter, AlignRight (se aplica al encabezado y al cuerpo)
TableHeaderStyle(opts...)Estilo para la fila de encabezado
TableStripe(color)Color de fondo alternado de filas
TableCellVAlign(align)Alineacion vertical: VAlignTop, VAlignMiddle, VAlignBottom
WithTableBorder(spec)Borde exterior de la tabla
WithTableCellBorder(spec)Mismo borde dibujado alrededor de cada celda de cabecera + cuerpo (rejilla estilo Excel)
WithTableBorderCollapse(b)Colapsar bordes de celdas adyacentes
WithTableBackground(color)Rellena el fondo de la caja exterior de la tabla

Bordes y fondos

Since v1.0.7

Anade un marco exterior, lineas de rejilla por celda o un relleno de fondo. Construye un BorderSpec con template.Border(...) y aplicalo via WithTableBorder (exterior) o WithTableCellBorder (cada celda):

outer := template.Border(
    template.BorderWidth(document.Pt(1)),
    template.BorderColor(pdf.RGBHex(0x1A237E)),
)
grid := template.Border(
    template.BorderWidth(document.Pt(0.5)),
    template.BorderColor(pdf.Gray(0.5)),
)

// Solo marco exterior
c.Table(header, rows, template.WithTableBorder(outer))

// Lineas de rejilla estilo Excel en cada celda
c.Table(header, rows, template.WithTableCellBorder(grid))

// Marco + rejilla + relleno
c.Table(header, rows,
    template.WithTableBorder(outer),
    template.WithTableCellBorder(grid),
    template.WithTableBackground(pdf.RGBHex(0xFAFAFA)),
)

// Rejilla discontinua
dashed := template.Border(
    template.BorderWidth(document.Pt(0.75)),
    template.BorderColor(pdf.RGBHex(0x0D47A1)),
    template.BorderLine(document.BorderDashed),
)
c.Table(header, rows, template.WithTableCellBorder(dashed))

Para la referencia completa del constructor BorderSpec, ver Bordes.

Alineacion vertical de tabla

c.Table(
    []string{"Align", "Short", "Long Content"},
    [][]string{
        {"Top", "A", "This is a longer text that wraps to multiple lines"},
        {"Middle", "B", "Another longer text for demonstration purposes"},
    },
    template.TableCellVAlign(document.VAlignMiddle),
)

Alineacion por columna

Since v1.0.10

Define la alineacion horizontal columna por columna — el caso de uso tipico es alinear a la derecha columnas numericas o monetarias. Cada argumento se aplica a la columna del mismo indice, tanto en el encabezado como en el cuerpo. Las columnas sin alineacion provista usan la alineacion izquierda por defecto.

c.Table(
    []string{"Producto", "Cant.", "Precio"},
    [][]string{
        {"Manzana", "3",   "$1.50"},
        {"Banana",  "12",  "$0.30"},
        {"Cereza",  "120", "$5.00"},
    },
    template.ColumnAlign(
        document.AlignLeft,   // Producto
        document.AlignRight,  // Cant.
        document.AlignRight,  // Precio
    ),
)

Imagen

Agregue imagenes JPEG o PNG:

imgData, _ := os.ReadFile("photo.jpg")

c.Image(imgData)
c.Image(imgData, template.FitWidth(document.Mm(80)))
c.Image(imgData, template.FitHeight(document.Mm(50)))

Opciones de imagen

OpcionDescripcion
FitWidth(value)Escalar al ancho especificado
FitHeight(value)Escalar a la altura especificada
WithFitMode(mode)Modo de ajuste: FitContain, FitCover, FitStretch, FitOriginal
WithAlign(align)Alineacion horizontal: AlignLeft, AlignCenter, AlignRight
MinDisplayWidth(v)Desbordar a la siguiente pagina si se reduce por debajo de este ancho
MinDisplayHeight(v)Desbordar a la siguiente pagina si se reduce por debajo de esta altura
WithImageBorder(spec)Borde alrededor de la imagen
WithImageBackground(color)Rellena el fondo de la caja de la imagen (util para PNG transparentes)

Modos de ajuste de imagen

// Contain: scale to fit, preserve aspect ratio (default)
c.Image(data, template.WithFitMode(document.FitContain))

// Cover: scale to fill, may crop
c.Image(data, template.WithFitMode(document.FitCover))

// Stretch: fill bounds, may distort
c.Image(data, template.WithFitMode(document.FitStretch))

// Original: use original dimensions
c.Image(data, template.WithFitMode(document.FitOriginal))

Alineacion de imagen

c.Image(data, template.FitWidth(document.Mm(40)), template.WithAlign(document.AlignCenter))
c.Image(data, template.FitWidth(document.Mm(40)), template.WithAlign(document.AlignRight))

Borde y fondo

Since v1.0.7

Enmarca una imagen y rellena su caja (util para PNG transparentes):

c.Image(pngData,
    template.FitWidth(document.Mm(60)),
    template.WithImageBorder(template.Border(
        template.BorderWidth(document.Pt(2)),
        template.BorderColor(pdf.RGBHex(0xE53935)),
    )),
    template.WithImageBackground(pdf.RGBHex(0xFFF8E1)),
)

Para la referencia completa del constructor BorderSpec, ver Bordes.

Caja

Since v1.0.7

Envuelve contenido arbitrario de columna en un contenedor rectangular con borde, relleno y padding. Util para llamadas, cajas de aviso o agrupar elementos relacionados:

c.Box(func(c *template.ColBuilder) {
    c.Text("Dentro de una caja", template.Bold())
    c.Text("con dos lineas de texto.")
},
    template.WithBoxBorder(template.Border(
        template.BorderWidth(document.Pt(1)),
        template.BorderColor(pdf.RGBHex(0x1A237E)),
    )),
    template.WithBoxBackground(pdf.RGBHex(0xE8EAF6)),
    template.WithBoxPadding(document.UniformEdges(document.Mm(4))),
)

Opciones de caja

OpcionDescripcion
WithBoxBorder(spec)Borde alrededor de la caja
WithBoxBackground(color)Color de relleno
WithBoxPadding(edges)Espaciado interior
WithBoxMargin(edges)Espaciado exterior
WithBoxWidth(value)Ancho explicito
WithBoxHeight(value)Altura explicita

Bordes

Since v1.0.7

template.Border(...) construye un BorderSpec reutilizable que se puede aplicar a tablas (WithTableBorder / WithTableCellBorder), imagenes (WithImageBorder), cajas (WithBoxBorder) y texto (WithTextBorder):

spec := template.Border(
    template.BorderWidth(document.Pt(1)),       // 4 lados uniformes
    template.BorderColor(pdf.RGBHex(0x1A237E)),
    template.BorderLine(document.BorderSolid),  // BorderSolid | BorderDashed | BorderDotted
)

Cuando no se especifica ancho, el valor por defecto es 1pt negro solido.

Helpers de borde

OpcionDescripcion
Border(opts...)Construye un BorderSpec
BorderWidth(v)Ancho uniforme en los 4 lados
BorderWidths(t, r, b, l)Anchos por lado en orden CSS: top, right, bottom, left
BorderColor(c)Color del borde
BorderLine(style)Estilo de linea: BorderSolid, BorderDashed, BorderDotted, BorderNone

Lista

Lista desordenada

c.List([]string{
    "Declarative document definition",
    "All element types supported",
    "Style options (bold, italic, color, align)",
    "Header and footer support",
})

┌─────────────────────────────────────────────┐
│  • Declarative document definition          │
│  • All element types supported              │
│  • Style options (bold, italic, color, ...)  │
│  • Header and footer support                │
└─────────────────────────────────────────────┘

Lista ordenada

c.OrderedList([]string{
    "Text with styles",
    "Tables with headers",
    "Lists (ordered/unordered)",
    "Lines and spacers",
    "QR codes and barcodes",
})

┌─────────────────────────────────────────────┐
│  1. Text with styles                        │
│  2. Tables with headers                     │
│  3. Lists (ordered/unordered)               │
│  4. Lines and spacers                       │
│  5. QR codes and barcodes                   │
└─────────────────────────────────────────────┘

Opciones de lista

OpcionDescripcion
ListIndent(value)Sangria desde la izquierda

Linea

Lineas horizontales con color y grosor opcionales:

// Default line (gray, 1pt)
c.Line()

// Colored line
c.Line(template.LineColor(pdf.Red))
c.Line(template.LineColor(pdf.Blue))

// Custom thickness
c.Line(template.LineThickness(document.Pt(0.5)))   // thin
c.Line(template.LineThickness(document.Pt(2)))     // medium
c.Line(template.LineThickness(document.Pt(5)))     // thick

// Color + thickness
c.Line(
    template.LineColor(pdf.RGBHex(0x1A237E)),
    template.LineThickness(document.Pt(2)),
)

┌─────────────────────────────────────────────┐
│  Default line:                              │
│  ─────────────────────────────── (gray 1pt) │
│  Red line:                                  │
│  ─────────────────────────────── (red)      │
│  Thin (0.5pt):                              │
│  ─────────────────────────────── (thin)     │
│  Thick (5pt):                               │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ (thick)    │
└─────────────────────────────────────────────┘

Opciones de linea

OpcionDescripcion
LineColor(color)Color de la linea
LineThickness(value)Grosor de la linea

Espaciador

Agregue espacio vertical entre elementos:

c.Text("Before spacer")
c.Spacer(document.Mm(10))    // 10mm gap
c.Text("After spacer")

c.Spacer(document.Mm(5))     // 5mm
c.Spacer(document.Mm(15))    // 15mm
c.Spacer(document.Mm(30))    // 30mm

┌─────────────────────────────────────────────┐
│  Before spacer                              │
│                                             │
│                  ↕ 10mm                     │
│                                             │
│  After spacer                               │
└─────────────────────────────────────────────┘

Codigo QR

Genere codigos QR a partir de texto o URLs:

// Basic QR code
c.QRCode("https://gpdf.dev")

// With custom size
c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(30)))

// With error correction level
c.QRCode("HELLO", template.QRSize(document.Mm(25)),
    template.QRErrorCorrection(qrcode.LevelH))

// Japanese content
c.QRCode("こんにちは世界", template.QRSize(document.Mm(30)))

Codigos QR con diferentes tamanos

page.AutoRow(func(r *template.RowBuilder) {
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("20mm", template.FontSize(9))
        c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(20)))
    })
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("30mm", template.FontSize(9))
        c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(30)))
    })
    r.Col(4, func(c *template.ColBuilder) {
        c.Text("40mm", template.FontSize(9))
        c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(40)))
    })
})

┌───────────────┬───────────────┬───────────────┐
│  20mm         │  30mm         │  40mm         │
│  ┌──┐         │  ┌────┐       │  ┌──────┐     │
│  │QR│         │  │ QR │       │  │  QR  │     │
│  └──┘         │  └────┘       │  │      │     │
│               │               │  └──────┘     │
└───────────────┴───────────────┴───────────────┘

Niveles de correccion de errores

NivelRecuperacionIdeal para
qrcode.LevelL~7%Entornos limpios
qrcode.LevelM~15%Uso general (predeterminado)
qrcode.LevelQ~25%Uso industrial
qrcode.LevelH~30%Entornos adversos
import "github.com/gpdf-dev/gpdf/qrcode"

c.QRCode("HELLO", template.QRErrorCorrection(qrcode.LevelH))

Opciones de codigo QR

OpcionDescripcion
QRSize(value)Tamano de visualizacion (ancho = alto)
QRMinSize(value)Tamano minimo — desborda a la siguiente pagina en lugar de encogerse por debajo
QRErrorCorrection(level)Nivel de correccion de errores
QRScale(s)Pixeles por modulo QR

Tamano minimo

Since v1.0.6

QRMinSize evita que el diseno reduzca un codigo QR por debajo de un minimo configurado. Cuando el espacio restante en la pagina actual forzaria al QR por debajo de ese tamano, desborda a la siguiente pagina en lugar de renderizarse con un tamano no escaneable.

c.QRCode("https://gpdf.dev",
    template.QRSize(document.Mm(30)),
    template.QRMinSize(document.Mm(20)))

Codigo de barras

Genere codigos de barras Code 128:

// Basic barcode
c.Barcode("INV-2026-0001")

// With custom width
c.Barcode("PRODUCT-A-12345", template.BarcodeWidth(document.Mm(80)))

// With custom height
c.Barcode("SMALL-BAR", template.BarcodeHeight(document.Mm(10)))

// Numeric data (automatically optimized with Code C)
c.Barcode("1234567890")

Codigos de barras en columnas

page.AutoRow(func(r *template.RowBuilder) {
    r.Col(6, func(c *template.ColBuilder) {
        c.Text("Item A", template.FontSize(9))
        c.Barcode("ITEM-A-001", template.BarcodeWidth(document.Mm(60)))
    })
    r.Col(6, func(c *template.ColBuilder) {
        c.Text("Item B", template.FontSize(9))
        c.Barcode("ITEM-B-002", template.BarcodeWidth(document.Mm(60)))
    })
})

┌────────────────────────┬────────────────────────┐
│  Item A                │  Item B                │
│  ║║│║║│║║║│║║│║║│      │  ║║│║║│║║║│║║│║║│      │
│  ITEM-A-001            │  ITEM-B-002            │
└────────────────────────┴────────────────────────┘

Opciones de codigo de barras

OpcionDescripcion
BarcodeWidth(value)Ancho de visualizacion
BarcodeHeight(value)Alto de visualizacion
BarcodeFormat(format)Formato del codigo de barras (predeterminado: Code 128)

Posicionamiento absoluto

Coloque elementos en coordenadas XY exactas en la pagina, fuera del flujo normal de la cuadricula. Util para marcas de agua, sellos, logotipos y superposiciones.

page.Absolute(document.Mm(120), document.Mm(20), func(c *template.ColBuilder) {
    c.Text("CONFIDENTIAL", template.FontSize(20), template.Bold(), template.TextColor(pdf.Red))
})

// With explicit size
page.Absolute(document.Mm(10), document.Mm(250), func(c *template.ColBuilder) {
    c.QRCode("https://gpdf.dev", template.QRSize(document.Mm(20)))
}, gpdf.AbsoluteWidth(document.Mm(25)), gpdf.AbsoluteHeight(document.Mm(25)))

// Use page corner as origin (ignores margins)
page.Absolute(document.Mm(0), document.Mm(0), func(c *template.ColBuilder) {
    c.Text("Top-left corner of page")
}, gpdf.AbsoluteOriginPage())

┌─ Page ──────────────────────────────────────────┐
│  ┌─ Content Area ───────────────────────────┐   │
│  │                                          │   │
│  │   [Normal flow content]                  │   │
│  │                                          │   │
│  │              ┌──────────────┐            │   │
│  │              │ CONFIDENTIAL │ ← absolute │   │
│  │              └──────────────┘   (120,20) │   │
│  │                                          │   │
│  │   ┌──┐                                   │   │
│  │   │QR│ ← absolute (10,250)               │   │
│  │   └──┘                                   │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

Origenes de coordenadas

OrigenDescripcionPredeterminado
Area de contenidoXY relativo a la esquina superior izquierda del area de contenido (dentro de margenes)Si
PaginaXY relativo a la esquina superior izquierda de la pagina (ignora margenes)No

Opciones de posicionamiento absoluto

OpcionDescripcion
AbsoluteWidth(value)Ancho explicito para el bloque absoluto
AbsoluteHeight(value)Alto explicito para el bloque absoluto
AbsoluteOriginPage()Usar esquina de pagina como origen en lugar del area de contenido

Numero de pagina / Total de paginas

Numeracion automatica de paginas en encabezados o pies de pagina:

// Current page number (e.g., "1", "2", "3")
c.PageNumber(template.AlignRight(), template.FontSize(8))

// Total page count (e.g., "4 total pages")
c.TotalPages(template.AlignRight(), template.FontSize(9))

Ambos aceptan opciones de texto estandar para el estilo.