Pacote gpdf

Visao Geral

O pacote gpdf e uma facade que re-exporta funcoes comumente usadas das camadas internas. Voce pode importar gpdf por conveniencia ou importar os pacotes especificos diretamente.

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

Funcoes

NewDocument

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

Cria um novo builder de documento PDF. Este e o ponto 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)

Cria um Document a partir de uma definicao JSON schema com vinculacao opcional de dados via 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)

Cria um Document executando um Go template pre-analisado que produz saida em JSON schema.

TemplateFuncMap

func TemplateFuncMap() template.FuncMap

Retorna funcoes auxiliares (toJSON, etc.) para uso ao analisar Go templates.

Opcoes do Documento

Funcao	Descricao
`WithPageSize(size)`	Definir dimensoes da pagina (`A4`, `A3`, `Letter`, `Legal`)
`WithMargins(edges)`	Definir margens da pagina
`WithFont(family, data)`	Registrar uma fonte TrueType (aceita `[]byte`)
`WithDefaultFont(family, size)`	Definir a familia e tamanho de fonte padrao
`WithMetadata(meta)`	Definir metadados do documento
`WithEncryption(opts...)`	Habilitar criptografia AES-256
`WithPDFA(opts...)`	Habilitar conformidade PDF/A

Metadados do Documento

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

Tamanhos de Pagina

Constante	Dimensoes
`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 do Document

AddPage

func (d *Document) AddPage() *PageBuilder

Adiciona uma nova pagina e retorna seu builder.

Header / Footer

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

Define conteudo que se repete em cada pagina.

Generate / Render

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

Generate() retorna o PDF como um slice de bytes. Render() escreve diretamente em um io.Writer.

Metodos do PageBuilder

Row

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

Row() cria uma linha com altura fixa. AutoRow() cria uma linha que se ajusta ao conteudo.

Metodos do RowBuilder

Col

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

Cria uma coluna ocupando span de 12 colunas do grid.

Metodos do ColBuilder

Metodo	Descricao
`Text(text, opts...)`	Adicionar texto com opcoes de estilo
`Image(data, opts...)`	Adicionar uma imagem (bytes JPEG ou PNG)
`Table(headers, rows, opts...)`	Adicionar uma tabela
`List(items, opts...)`	Adicionar uma lista nao ordenada
`OrderedList(items, opts...)`	Adicionar uma lista ordenada
`Line(opts...)`	Adicionar uma linha horizontal
`Spacer(height)`	Adicionar espacamento vertical
`QRCode(data, opts...)`	Adicionar um QR code
`Barcode(data, opts...)`	Adicionar um codigo de barras (Code 128)
`RichText(fn)`	Adicionar texto inline com estilos mistos
`PageNumber(opts...)`	Numero da pagina atual
`TotalPages(opts...)`	Contagem total de paginas

Opcoes de QR Code

Funcao	Descricao
`QRSize(value)`	Tamanho de exibicao (largura = altura)
`QRErrorCorrection(level)`	Correcao de erro: `LevelL`, `LevelM`, `LevelQ`, `LevelH`
`QRScale(s)`	Pixels por modulo QR

Opcoes de Codigo de Barras

Funcao	Descricao
`BarcodeWidth(value)`	Largura de exibicao
`BarcodeHeight(value)`	Altura de exibicao
`BarcodeFormat(format)`	Formato do codigo de barras (padrao: Code 128)

Operacoes com PDF Existente

Open

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

Abre um PDF existente para leitura e modificacao. Retorna um ExistingDocument que suporta operacoes de overlay via Incremental Update (append nao destrutivo).

doc, err := gpdf.Open(pdfBytes)

Metodos do ExistingDocument

Metodo	Descricao
`PageCount() (int, error)`	Retorna o numero de paginas no PDF
`Overlay(pageIndex int, fn func(p *PageBuilder)) error`	Adicionar conteudo sobre uma pagina especifica (indice base 0)
`EachPage(fn func(pageIndex int, p *PageBuilder)) error`	Adicionar conteudo sobre todas as paginas
`FlattenForms() error`	Achatar todos os campos AcroForm em conteudo de pagina estatico Since v1.0.4
`Save() ([]byte, error)`	Retorna o PDF modificado como slice 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()

Fusao de PDF Since v1.0.2

Merge

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

Combina paginas de multiplas fontes PDF em um unico PDF de saida.

Source

type Source struct {
    Data  []byte    // bytes PDF brutos
    Pages PageRange // paginas a incluir; valor zero = todas as paginas
}

PageRange

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

Opcoes de fusao

Funcao	Descricao
`WithMergeMetadata(title, author, producer)`	Definir informacoes do documento (titulo, autor, produtor) na saida mesclada

Construtores de Componentes

Funcao	Descricao
`NewInvoice(data)`	Criar um PDF de fatura
`NewReport(data)`	Criar um PDF de relatorio
`NewLetter(data)`	Criar um PDF de carta comercial

Veja Componentes para uso detalhado.