Referência da API Go

O módulo github.com/yfedoseev/pdf_oxide/go envolve o núcleo Rust via CGo. Desde a v0.3.27 ele linka a biblioteca Rust como staticlib, gerando binários Go totalmente autocontidos — sem necessidade de configurar bibliotecas em tempo de execução.

go get github.com/yfedoseev/pdf_oxide/go

import pdfoxide "github.com/yfedoseev/pdf_oxide/go"

Há dois backends. O backend cgo padrão (CGO_ENABLED=1) expõe a superfície completa documentada aqui. Um backend purego (CGO_ENABLED=0) entrega um subconjunto — abertura, extração, conversão, busca, edição básica, redação e leitura de assinaturas; os métodos ausentes nele retornam ErrNotImplementedInPurego. DocumentBuilder, OCR, renderização e geração de códigos de barras são exclusivos do cgo.

Para outras linguagens, veja Python, Node.js, C# ou Rust. Para a documentação gerada completa, veja pkg.go.dev/github.com/yfedoseev/pdf_oxide/go.

---

Funções do pacote

Abertura

func Open(path string) (*PdfDocument, error)                       // open a PDF file (read-only)
func OpenFromBytes(data []byte) (*PdfDocument, error)              // open from in-memory bytes
func OpenWithPassword(path, password string) (*PdfDocument, error) // open an encrypted PDF
func OpenReader(r io.Reader) (*PdfDocument, error)                 // open by reading an io.Reader fully
func OpenEditor(path string) (*DocumentEditor, error)             // open a file for editing
func OpenEditorFromBytes(data []byte) (*DocumentEditor, error)    // open bytes for editing

Documentos do Office

func OpenFromDocxBytes(data []byte) (*PdfDocument, error)  // convert DOCX bytes and open as a PDF
func OpenFromPptxBytes(data []byte) (*PdfDocument, error)  // convert PPTX bytes and open as a PDF
func OpenFromXlsxBytes(data []byte) (*PdfDocument, error)  // convert XLSX bytes and open as a PDF

Criação

func FromMarkdown(md string) (*PdfCreator, error)            // build a PDF from Markdown
func FromHtml(html string) (*PdfCreator, error)             // build a PDF from HTML
func FromText(text string) (*PdfCreator, error)             // build a PDF from plain text
func FromImage(path string) (*PdfCreator, error)            // single-page PDF from an image file
func FromImageBytes(data []byte) (*PdfCreator, error)       // single-page PDF from image bytes
func Merge(paths []string) ([]byte, error)                  // merge several PDFs into one byte slice
func FromHTMLCSS(html, css string, fontBytes []byte) (*PdfCreator, error)               // HTML + CSS with one font
func FromHTMLCSSWithFonts(html, css string, fonts []FontEntry) (*PdfCreator, error)     // HTML + CSS with named fonts

Códigos de barras

func GenerateQRCode(data string, errorCorrection, sizePx int) (*BarcodeImage, error) // errorCorrection: 0=Low..3=High
func GenerateBarcode(data string, format, sizePx int) (*BarcodeImage, error)         // 1D/2D barcode

OCR (build tag: ocr)

func NewOcrEngine(detModelPath, recModelPath, dictPath string) (*OcrEngine, error) // construct a PaddleOCR engine

Assinatura

func LoadCertificate(data []byte, password string) (*Certificate, error)            // load PKCS#12 / DER cert
func LoadCertificateFromPem(certPem, keyPem string) (*Certificate, error)           // load PEM cert + key
func SignPdfBytes(pdfData []byte, cert *Certificate, reason, location string) ([]byte, error)   // CMS sign in-place
func SignPdfBytesPAdES(pdfData []byte, cert *Certificate, opts PAdESOptions) ([]byte, error)    // PAdES B-B/B-T/B-LT
func SignPdfBytesPAdESOpts(pdfData []byte, cert *Certificate, opts PAdESOptions) ([]byte, error) // PAdES with full options

Carimbos de tempo (RFC 3161)

func ParseTimestamp(data []byte) (*Timestamp, error)        // parse a DER TimeStampToken / TSTInfo
func NewTsaClientOptions(url string) TsaClientOptions       // default TSA options for a URL
func NewTsaClient(opts TsaClientOptions) (*TsaClient, error) // construct a TSA HTTP client

Construtor de documentos e fontes

func NewDocumentBuilder() (*DocumentBuilder, error)                          // fluent multi-page builder
func EmbeddedFontFromFile(path string) (*EmbeddedFont, error)                // load a TTF/OTF font from disk
func EmbeddedFontFromBytes(data []byte, name string) (*EmbeddedFont, error)  // load a font from bytes

Logging e ajustes globais

func SetLogLevel(level LogLevel)                  // set library log verbosity
func GetLogLevel() LogLevel                       // read current log verbosity
func SetMaxOpsPerStream(limit int64) int64        // content-stream op limit (returns prior value)
func SetPreserveUnmappedGlyphs(preserve int) int  // keep unmapped glyphs (returns prior value)

Gerenciamento de modelos de OCR

func PrefetchModels(langs ...string) (string, error) // download OCR models for languages
func ModelManifest() string                          // JSON manifest of available OCR models
func PrefetchAvailable() bool                        // whether model prefetch is supported in this build

Provedor de criptografia / FIPS

func ActiveCryptoProvider() string       // name of the active crypto backend
func IsFipsCryptoAvailable() bool         // whether a FIPS provider is available
func UseFipsCryptoProvider() error        // switch to the FIPS crypto provider
func SetCryptoPolicy(spec string) error   // install a crypto policy (set-once, fail-closed)
func CryptoPolicy() string                // currently installed crypto policy
func CryptoInventory() []string           // list of available crypto algorithms
func CryptoCBOM() string                  // cryptographic bill of materials (JSON)

Opções de extração automática

Opções funcionais passadas para PdfDocument.ExtractPageAuto:

func WithMode(mode string) AutoOption          // extraction mode (e.g. "ocr", "native")
func WithImageTables(yes bool) AutoOption       // detect tables inside images
func WithPlaceholders(yes bool) AutoOption      // emit placeholders for non-text content
func WithOCRLanguages(langs ...string) AutoOption // OCR language hints
func WithForceOCRPages(pages ...uint) AutoOption  // force OCR on specific pages

---

PdfDocument

Acesso somente leitura. As leituras são protegidas por um sync.RWMutex interno — seguras para uso concorrente entre goroutines.

Ciclo de vida

func (d *PdfDocument) Close() error                          // release the native handle
func (d *PdfDocument) IsClosed() bool                        // whether Close has been called
func (d *PdfDocument) IsEncrypted() bool                     // whether the PDF is encrypted
func (d *PdfDocument) Authenticate(password string) (bool, error) // authenticate after opening

Informações do documento

func (d *PdfDocument) PageCount() (int, error)               // number of pages
func (d *PdfDocument) Version() (major, minor uint8, err error) // PDF version
func (d *PdfDocument) HasStructureTree() (bool, error)       // whether the PDF is tagged
func (d *PdfDocument) PageInfo(page int) (*PageInfo, error)  // dimensions and page boxes

Classificação

func (d *PdfDocument) ClassifyPage(page int) (string, error) // classify a single page (text/scanned/mixed)
func (d *PdfDocument) ClassifyDocument() (string, error)     // classify the whole document

Páginas (v0.3.34)

func (d *PdfDocument) Page(index int) (*Page, error)         // lightweight page handle
func (d *PdfDocument) Pages() ([]*Page, error)               // handles for every page

Page despacha todos os métodos de extração para o documento pai:

type Page struct {
    Index int
}

func (p *Page) Text() (string, error)                        // plain text
func (p *Page) Markdown() (string, error)                    // Markdown
func (p *Page) Html() (string, error)                        // HTML
func (p *Page) PlainText() (string, error)                   // layout-aware plain text
func (p *Page) Chars() ([]Char, error)                       // per-character data
func (p *Page) Words() ([]Word, error)                       // words with bounding boxes
func (p *Page) Lines() ([]TextLine, error)                   // text lines
func (p *Page) Tables() ([]Table, error)                     // detected tables
func (p *Page) Images() ([]Image, error)                     // embedded images
func (p *Page) Paths() ([]Path, error)                       // vector paths
func (p *Page) Fonts() ([]Font, error)                       // fonts used
func (p *Page) Annotations() ([]Annotation, error)           // annotations
func (p *Page) Info() (*PageInfo, error)                     // page dimensions and boxes
func (p *Page) Search(term string, caseSensitive bool) ([]SearchResult, error) // search on this page
func (p *Page) NeedsOcr() (bool, error)                      // whether the page needs OCR
func (p *Page) TextWithOcr(engine *OcrEngine) (string, error) // OCR text extraction

Extração de texto

func (d *PdfDocument) ExtractText(page int) (string, error)  // plain text for one page
func (d *PdfDocument) ExtractAllText() (string, error)       // plain text for all pages
func (d *PdfDocument) ExtractTextAuto(page int) (string, error)                       // auto native/OCR selection
func (d *PdfDocument) ExtractPageAuto(page int, opts ...AutoOption) (string, error)   // auto extraction with options
func (d *PdfDocument) ExtractStructured(page int) (string, error)                     // structured JSON for one page

Conversão

func (d *PdfDocument) ToMarkdown(page int) (string, error)   // one page to Markdown
func (d *PdfDocument) ToMarkdownAll() (string, error)        // all pages to Markdown
func (d *PdfDocument) ToHtml(page int) (string, error)       // one page to HTML
func (d *PdfDocument) ToHtmlAll() (string, error)            // all pages to HTML
func (d *PdfDocument) ToPlainText(page int) (string, error)  // one page to layout-aware text
func (d *PdfDocument) ToPlainTextAll() (string, error)       // all pages to layout-aware text

Exportação para Office e PDF/A

func (d *PdfDocument) ToDocxBytes() ([]byte, error)          // export to DOCX
func (d *PdfDocument) ToPptxBytes() ([]byte, error)          // export to PPTX
func (d *PdfDocument) ToXlsxBytes() ([]byte, error)          // export to XLSX
func (d *PdfDocument) ConvertToPdfA(level int) (bool, error) // convert to PDF/A (returns compliance)
func (d *PdfDocument) SourceBytes() ([]byte, error)          // raw source bytes of the document

Extração estruturada

func (d *PdfDocument) ExtractWords(page int) ([]Word, error)         // words with bounding boxes
func (d *PdfDocument) ExtractTextLines(page int) ([]TextLine, error) // text lines
func (d *PdfDocument) ExtractChars(page int) ([]Char, error)         // per-character data
func (d *PdfDocument) ExtractTables(page int) ([]Table, error)       // detected tables
func (d *PdfDocument) ExtractPaths(page int) ([]Path, error)         // vector paths / shapes

Extração por região

func (d *PdfDocument) ExtractTextInRect(page int, x, y, w, h float32) (string, error)    // text in a rectangle
func (d *PdfDocument) ExtractWordsInRect(page int, x, y, w, h float32) ([]Word, error)   // words in a rectangle
func (d *PdfDocument) ExtractImagesInRect(page int, x, y, w, h float32) (int, error)     // image count in a rectangle

Recursos

func (d *PdfDocument) Fonts(page int) ([]Font, error)               // fonts on a page
func (d *PdfDocument) Images(page int) ([]Image, error)             // embedded images on a page
func (d *PdfDocument) Annotations(page int) ([]Annotation, error)   // annotations on a page
func (d *PdfDocument) PageElements(page int) ([]Element, error)     // layout elements on a page
func (d *PdfDocument) FormFields() ([]FormField, error)             // all form fields
func (d *PdfDocument) HasXfa() bool                                 // whether the document has XFA forms
func (d *PdfDocument) ExportFormData(format int) ([]byte, error)    // export form data (FDF/XFDF)

Limpeza de páginas

func (d *PdfDocument) RemoveHeaders(threshold float32) (int, error)   // strip repeated headers
func (d *PdfDocument) RemoveFooters(threshold float32) (int, error)   // strip repeated footers
func (d *PdfDocument) RemoveArtifacts(threshold float32) (int, error) // strip page artifacts

Busca

func (d *PdfDocument) SearchPage(page int, query string, caseSensitive bool) ([]SearchResult, error) // search one page
func (d *PdfDocument) SearchAll(query string, caseSensitive bool) ([]SearchResult, error)            // search all pages
func (d *PdfDocument) SearchAllVerbose(query string, caseSensitive bool) ([]SearchResult, error)     // search with bbox accessors

Estrutura e metadados do documento

func (d *PdfDocument) PageLabels() (string, error)                  // page-label ranges (JSON)
func (d *PdfDocument) XmpMetadata() (string, error)                 // XMP metadata (XML)
func (d *PdfDocument) Outline() (string, error)                     // bookmarks / TOC (JSON)
func (d *PdfDocument) PlanSplitByBookmarks(opts SplitByBookmarksOptions) ([]SplitSegment, error) // plan a bookmark split

OCR

func (d *PdfDocument) NeedsOcr(page int) (bool, error)                          // whether a page needs OCR
func (d *PdfDocument) ExtractTextWithOcr(page int, engine *OcrEngine) (string, error) // OCR text (nil = default engine)

Validação

func (d *PdfDocument) ValidatePdfA(level int) (*PdfAResult, error)   // PDF/A compliance (0=A1b..5=A3b)
func (d *PdfDocument) ValidatePdfUa() (bool, []string, error)        // PDF/UA accessibility
func (d *PdfDocument) ValidatePdfX(level int) (bool, []string, error) // PDF/X compliance

Renderização

func (d *PdfDocument) RenderPage(page, format int) (*RenderedImage, error)                  // render a page
func (d *PdfDocument) RenderPageZoom(page int, zoom float32, format int) (*RenderedImage, error) // render at a zoom factor
func (d *PdfDocument) RenderPageFit(page, fitWidth, fitHeight, format int) (*RenderedImage, error) // fit within a box
func (d *PdfDocument) RenderThumbnail(page, size, format int) (*RenderedImage, error)       // small thumbnail
func (d *PdfDocument) RenderPageRaw(page, dpi int) (RgbaPixmap, error)                       // raw premultiplied RGBA
func (d *PdfDocument) RenderPageWithOptions(page int, opts RenderOptions) (*RenderedImage, error) // full render options
func (d *PdfDocument) RenderPageWithOptionsEx(page int, opts RenderOptions, excludedLayers []string) (*RenderedImage, error) // render excluding OCG layers

Valores de format: 0 = PNG, 1 = JPEG.

Assinaturas

func (d *PdfDocument) SignatureCount() (int, error)             // number of signatures
func (d *PdfDocument) Signatures() ([]*Signature, error)        // all signatures
func (d *PdfDocument) DSS() (*DSS, error)                       // Document Security Store (nil if absent)
func (d *PdfDocument) HasDocumentTimestamp() (bool, error)      // whether a document-level timestamp exists

---

DocumentEditor

Serializa as escritas internamente — seguro para uma goroutine por editor, mas não distribua edições independentes em pipeline entre várias goroutines.

Ciclo de vida e informações

func (e *DocumentEditor) Close()                                 // release the native handle
func (e *DocumentEditor) IsModified() (bool, error)             // whether unsaved edits exist
func (e *DocumentEditor) SourcePath() (string, error)          // path the editor was opened from
func (e *DocumentEditor) Version() (major, minor uint8, err error) // PDF version
func (e *DocumentEditor) PageCount() (int, error)               // number of pages

Metadados

func (e *DocumentEditor) Title() (string, error)                // get title
func (e *DocumentEditor) SetTitle(title string) error           // set title
func (e *DocumentEditor) Author() (string, error)               // get author
func (e *DocumentEditor) SetAuthor(author string) error         // set author
func (e *DocumentEditor) Subject() (string, error)              // get subject
func (e *DocumentEditor) SetSubject(subject string) error       // set subject
func (e *DocumentEditor) Producer() (string, error)             // get producer
func (e *DocumentEditor) SetProducer(producer string) error     // set producer
func (e *DocumentEditor) CreationDate() (string, error)         // get creation date
func (e *DocumentEditor) SetCreationDate(date string) error     // set creation date
func (e *DocumentEditor) Keywords() (string, error)             // get keywords
func (e *DocumentEditor) SetKeywords(keywords string) error     // set keywords
func (e *DocumentEditor) ApplyMetadata(meta Metadata) error     // apply non-empty metadata fields at once

Páginas

func (e *DocumentEditor) DeletePage(page int) error                          // delete a page
func (e *DocumentEditor) MovePage(from, to int) error                        // move a page
func (e *DocumentEditor) PageRotation(page int) (int, error)                 // current rotation
func (e *DocumentEditor) SetPageRotation(page, degrees int) error            // set absolute rotation
func (e *DocumentEditor) RotatePageBy(page, degrees int) error               // add to current rotation
func (e *DocumentEditor) RotateAllPages(degrees int) error                   // rotate every page
func (e *DocumentEditor) GetPageMediaBox(page int) (x, y, w, h float64, err error)  // get MediaBox
func (e *DocumentEditor) SetPageMediaBox(page int, x, y, w, h float64) error        // set MediaBox
func (e *DocumentEditor) GetPageCropBox(page int) (x, y, w, h float64, err error)   // get CropBox
func (e *DocumentEditor) SetPageCropBox(page int, x, y, w, h float64) error         // set CropBox
func (e *DocumentEditor) CropMargins(left, right, top, bottom float32) error        // crop all page margins

Apagar / whiteout

func (e *DocumentEditor) EraseRegion(page int, x, y, w, h float32) error // erase one rectangle
func (e *DocumentEditor) EraseRegions(page int, rects [][4]float64) error // erase several rectangles
func (e *DocumentEditor) ClearEraseRegions(page int) error               // clear pending erases

Anotações e formulários

func (e *DocumentEditor) FlattenAnnotations(page int) error      // flatten annotations on a page
func (e *DocumentEditor) FlattenAllAnnotations() error           // flatten all annotations
func (e *DocumentEditor) IsPageMarkedForFlatten(page int) bool   // whether a page is marked for flatten
func (e *DocumentEditor) UnmarkPageForFlatten(page int) error    // unmark a page for flatten
func (e *DocumentEditor) FlattenForms() error                    // flatten all form fields
func (e *DocumentEditor) FlattenFormsOnPage(page int) error      // flatten forms on a page
func (e *DocumentEditor) FlattenWarnings() []string              // warnings from the last flatten
func (e *DocumentEditor) SetFormFieldValue(name, value string) error // set a form field value

Redação e sanitização

func (e *DocumentEditor) AddRedaction(page int, rect [4]float64, fill *[3]float64) error // mark a redaction
func (e *DocumentEditor) RedactionCount(page int) (int, error)        // pending redactions on a page
func (e *DocumentEditor) ApplyRedactions(scrubMetadata bool) (int, error) // apply all redactions
func (e *DocumentEditor) ApplyPageRedactions(page int) error          // apply redactions on a page
func (e *DocumentEditor) ApplyAllRedactions() error                   // apply all pending redactions
func (e *DocumentEditor) IsPageMarkedForRedaction(page int) bool      // whether a page is marked for redaction
func (e *DocumentEditor) UnmarkPageForRedaction(page int) error       // unmark a page for redaction
func (e *DocumentEditor) SanitizeDocument() (int, error)              // remove hidden / risky content

Mesclagem e incorporação

func (e *DocumentEditor) MergeFrom(path string) (int, error)     // merge pages from a file
func (e *DocumentEditor) MergeFromBytes(data []byte) (int, error) // merge pages from bytes
func (e *DocumentEditor) EmbedFile(name string, data []byte) error // attach a file
func (e *DocumentEditor) ConvertToPdfA(level int) error           // convert to PDF/A in place

Salvamento

func (e *DocumentEditor) Save(path string) error                                            // save to a file
func (e *DocumentEditor) SaveEncrypted(path, user, owner string) error                      // save AES-256 encrypted
func (e *DocumentEditor) SaveToBytes() ([]byte, error)                                       // serialize to bytes
func (e *DocumentEditor) SaveToBytesWithOptions(compress, garbageCollect, linearize bool) ([]byte, error) // serialize with options
func (e *DocumentEditor) SaveEncryptedToBytes(user, owner string) ([]byte, error)           // encrypted bytes
func (e *DocumentEditor) ExtractPagesToBytes(pageIndices []int) ([]byte, error)             // a subset of pages as a new PDF

---

PdfCreator

Retornado pela família FromMarkdown/FromHtml/FromText/FromImage. Não é seguro para uso concorrente entre goroutines.

func (c *PdfCreator) Save(path string) error          // write to disk
func (c *PdfCreator) SaveToBytes() ([]byte, error)    // serialize to bytes
func (c *PdfCreator) PageCount() (int, error)         // number of pages produced
func (c *PdfCreator) Close()                          // release the native handle

---

DocumentBuilder (somente CGo)

Construtor fluente de múltiplas páginas. //go:build cgo — sob CGO_ENABLED=0 ele fica indisponível.

func NewDocumentBuilder() (*DocumentBuilder, error)

// Document-level metadata & structure
func (b *DocumentBuilder) Title(title string) error               // set title
func (b *DocumentBuilder) Author(author string) error             // set author
func (b *DocumentBuilder) Subject(subject string) error           // set subject
func (b *DocumentBuilder) Keywords(keywords string) error         // set keywords
func (b *DocumentBuilder) Creator(creator string) error           // set creator
func (b *DocumentBuilder) OnOpen(script string) error             // document open JavaScript
func (b *DocumentBuilder) TaggedPdfUa1() error                    // enable Tagged PDF/UA-1 output
func (b *DocumentBuilder) Language(lang string) error             // set document language
func (b *DocumentBuilder) RoleMap(custom, standard string) error  // map custom structure type to standard
func (b *DocumentBuilder) RegisterEmbeddedFont(name string, font *EmbeddedFont) error // register a font

// Pages
func (b *DocumentBuilder) A4Page() (*PageBuilder, error)               // start an A4 page
func (b *DocumentBuilder) LetterPage() (*PageBuilder, error)           // start a US Letter page
func (b *DocumentBuilder) Page(width, height float32) (*PageBuilder, error) // start a custom-size page

// Output
func (b *DocumentBuilder) Build() ([]byte, error)                                      // serialize to bytes
func (b *DocumentBuilder) Save(path string) error                                      // write to disk
func (b *DocumentBuilder) SaveEncrypted(path, user, owner string) error                // write AES-256 encrypted
func (b *DocumentBuilder) ToBytesEncrypted(user, owner string) ([]byte, error)         // encrypted bytes
func (b *DocumentBuilder) Close() error                                                // release the native handle

EmbeddedFont

func (f *EmbeddedFont) Close() error  // release the font handle

---

PageBuilder (somente CGo)

Retornado por DocumentBuilder.A4Page / LetterPage / Page. Cada método de conteúdo retorna *PageBuilder para encadeamento; chame Done para voltar ao construtor pai.

Texto e layout

func (p *PageBuilder) Font(name string, size float32) *PageBuilder // set the current font
func (p *PageBuilder) At(x, y float32) *PageBuilder                // set the cursor position
func (p *PageBuilder) Text(text string) *PageBuilder              // draw text at the cursor
func (p *PageBuilder) Heading(level uint8, text string) *PageBuilder // draw a heading
func (p *PageBuilder) Paragraph(text string) *PageBuilder         // wrapped paragraph
func (p *PageBuilder) Space(points float32) *PageBuilder          // vertical space
func (p *PageBuilder) HorizontalRule() *PageBuilder               // horizontal divider
func (p *PageBuilder) Columns(columnCount uint, gapPt float32, text string) *PageBuilder // multi-column text
func (p *PageBuilder) Footnote(refMark, noteText string) *PageBuilder // footnote reference + note
func (p *PageBuilder) TextInRect(x, y, w, h float32, text string, align Alignment) *PageBuilder // text in a box
func (p *PageBuilder) NewPageSameSize() *PageBuilder              // start a new page of the same size
func (p *PageBuilder) Measure(text string) float32               // measured width of text
func (p *PageBuilder) RemainingSpace() float32                   // vertical space left on the page

Trechos inline

func (p *PageBuilder) Inline(text string) *PageBuilder                       // append an inline run
func (p *PageBuilder) InlineBold(text string) *PageBuilder                   // bold inline run
func (p *PageBuilder) InlineItalic(text string) *PageBuilder                 // italic inline run
func (p *PageBuilder) InlineColor(r, g, b float32, text string) *PageBuilder // colored inline run
func (p *PageBuilder) Newline() *PageBuilder                                 // line break in inline flow

Anotações

func (p *PageBuilder) LinkURL(url string) *PageBuilder            // URL link annotation
func (p *PageBuilder) LinkPage(pageIndex uint) *PageBuilder       // intra-document page link
func (p *PageBuilder) LinkNamed(destination string) *PageBuilder  // named-destination link
func (p *PageBuilder) LinkJavascript(script string) *PageBuilder  // JavaScript-action link
func (p *PageBuilder) Highlight(r, g, b float32) *PageBuilder     // highlight annotation
func (p *PageBuilder) Underline(r, g, b float32) *PageBuilder     // underline annotation
func (p *PageBuilder) Strikeout(r, g, b float32) *PageBuilder     // strikeout annotation
func (p *PageBuilder) Squiggly(r, g, b float32) *PageBuilder      // squiggly annotation
func (p *PageBuilder) StickyNote(text string) *PageBuilder        // sticky note at the cursor
func (p *PageBuilder) StickyNoteAt(x, y float32, text string) *PageBuilder // sticky note at a point
func (p *PageBuilder) Watermark(text string) *PageBuilder         // custom watermark
func (p *PageBuilder) WatermarkConfidential() *PageBuilder        // "CONFIDENTIAL" watermark
func (p *PageBuilder) WatermarkDraft() *PageBuilder               // "DRAFT" watermark
func (p *PageBuilder) Stamp(typeName string) *PageBuilder         // rubber-stamp annotation
func (p *PageBuilder) FreeText(x, y, w, h float32, text string) *PageBuilder // free-text annotation

Widgets de formulário e ações JavaScript

func (p *PageBuilder) TextField(name string, x, y, w, h float32, defaultValue string) *PageBuilder  // text field
func (p *PageBuilder) Checkbox(name string, x, y, w, h float32, checked bool) *PageBuilder           // checkbox
func (p *PageBuilder) ComboBox(name string, x, y, w, h float32, options []string, selected string) *PageBuilder // dropdown
func (p *PageBuilder) RadioGroup(name string, buttons []RadioButton, selected string) *PageBuilder   // radio group
func (p *PageBuilder) PushButton(name string, x, y, w, h float32, caption string) *PageBuilder       // push button
func (p *PageBuilder) SignatureField(name string, x, y, w, h float32) *PageBuilder                   // signature field
func (p *PageBuilder) OnOpen(script string) *PageBuilder          // page open action
func (p *PageBuilder) OnClose(script string) *PageBuilder         // page close action
func (p *PageBuilder) FieldKeystroke(script string) *PageBuilder  // field keystroke action
func (p *PageBuilder) FieldFormat(script string) *PageBuilder     // field format action
func (p *PageBuilder) FieldValidate(script string) *PageBuilder   // field validate action
func (p *PageBuilder) FieldCalculate(script string) *PageBuilder  // field calculate action

Imagens e códigos de barras

func (p *PageBuilder) Image(bytes []byte, x, y, w, h float32) *PageBuilder                    // place an image
func (p *PageBuilder) ImageWithAlt(bytes []byte, x, y, w, h float32, altText string) *PageBuilder // image with alt text
func (p *PageBuilder) ImageArtifact(bytes []byte, x, y, w, h float32) *PageBuilder            // decorative (artifact) image
func (p *PageBuilder) Barcode1d(barcodeType int, data string, x, y, w, h float32) *PageBuilder // 1D barcode
func (p *PageBuilder) BarcodeQr(data string, x, y, size float32) *PageBuilder                 // QR code

Primitivas gráficas

func (p *PageBuilder) Rect(x, y, w, h float32) *PageBuilder                       // outlined rectangle
func (p *PageBuilder) FilledRect(x, y, w, h, r, g, b float32) *PageBuilder        // filled rectangle
func (p *PageBuilder) Line(x1, y1, x2, y2 float32) *PageBuilder                   // line
func (p *PageBuilder) StrokeRect(x, y, w, h, width, r, g, b float32) *PageBuilder // stroked rectangle
func (p *PageBuilder) StrokeLine(x1, y1, x2, y2, width, r, g, b float32) *PageBuilder // stroked line
func (p *PageBuilder) StrokeRectDashed(x, y, w, h, width, r, g, b float32, dash []float32, phase float32) *PageBuilder // dashed rectangle
func (p *PageBuilder) StrokeLineDashed(x1, y1, x2, y2, width, r, g, b float32, dash []float32, phase float32) *PageBuilder // dashed line

Tabelas

func (p *PageBuilder) Table(spec TableSpec) *PageBuilder                       // buffered table
func (p *PageBuilder) StreamingTable(cfg StreamingTableConfig) *StreamingTable // row-at-a-time streaming table

Finalização

func (p *PageBuilder) Done() (*DocumentBuilder, error) // commit the page and return to the builder
func (p *PageBuilder) Close() error                    // discard the page

Exemplo

font, _ := pdfoxide.EmbeddedFontFromFile("DejaVuSans.ttf")
defer font.Close()

builder, _ := pdfoxide.NewDocumentBuilder()
page, _ := builder.LetterPage()
page.Font("Helvetica", 12).
    At(72, 720).Text("Hello").
    Heading(1, "Title").
    Paragraph("Body text with automatic wrapping.").
    LinkURL("https://example.com").
    Highlight(1.0, 1.0, 0.0).
    TextField("name", 150, 400, 200, 20, "Jane Doe").
    Checkbox("agree", 72, 380, 15, 15, true).
    FilledRect(50, 260, 500, 2, 0.9, 0.9, 0.9)
builder, _ = page.Done()
_ = builder.Save("out.pdf")

---

StreamingTable (somente CGo)

Adaptador de tabela linha a linha retornado por PageBuilder.StreamingTable.

func (t *StreamingTable) PushRow(cells []string) error      // append a row
func (t *StreamingTable) PushRowSpan(cells []SpanCell) error // append a row with rowspans
func (t *StreamingTable) PendingRowCount() int              // buffered rows not yet flushed
func (t *StreamingTable) BatchCount() int                   // number of flushed batches
func (t *StreamingTable) Flush() error                      // flush buffered rows to the native layer
func (t *StreamingTable) Finish() *PageBuilder              // finalize and return the page builder

---

OcrEngine (build tag ocr)

func (o *OcrEngine) Close()  // release the engine

A extração de texto por OCR é feita pelos métodos do documento NeedsOcr, ExtractTextWithOcr e pelo handle Page.TextWithOcr. Compile com go build -tags ocr ./....

---

RenderedImage

Saída da família RenderPage*.

func (i *RenderedImage) Data() []byte              // encoded PNG/JPEG bytes
func (i *RenderedImage) SaveToFile(path string) error // write the image to disk
func (i *RenderedImage) Close()                    // release the native buffer

RenderedImage também carrega os campos Width e Height (em pixels).

RenderOptions

type RenderOptions struct {
    Dpi                   int          // resolution; 0 => 150
    Format                RenderFormat // RenderFormatPng (0) or RenderFormatJpeg (1)
    Background            [4]float32   // RGBA 0.0–1.0; all-zero => opaque white
    TransparentBackground bool         // drop the background fill entirely
    RenderAnnotations     bool         // draw the annotation layer (default on)
    JpegQuality           int          // 1–100; 0 => 85
}

func (opts RenderOptions) WithAnnotationsOff() RenderOptions // disable annotation rendering deliberately
func (opts RenderOptions) WithAnnotationsOn() RenderOptions  // enable annotation rendering deliberately

RgbaPixmap

type RgbaPixmap struct {
    Data          []byte // premultiplied RGBA8888 pixels
    Width, Height int
}

---

BarcodeImage

Saída de GenerateQRCode / GenerateBarcode.

func (bc *BarcodeImage) PNGData() ([]byte, error)   // encoded PNG bytes
func (bc *BarcodeImage) SVGData() (string, error)   // SVG markup
func (bc *BarcodeImage) SourceData() string         // the data encoded in the barcode
func (bc *BarcodeImage) Close()                      // release the native handle

---

Assinaturas e carimbos de tempo

Certificate

func (cert *Certificate) Subject() (string, error)  // certificate subject DN
func (cert *Certificate) Issuer() (string, error)   // issuer DN
func (cert *Certificate) Serial() (string, error)   // serial number (hex)
func (cert *Certificate) Validity() (notBefore, notAfter time.Time, err error) // validity window
func (cert *Certificate) IsValid() (bool, error)    // whether valid right now
func (cert *Certificate) Close()                     // release the native handle

Signature

func (s *Signature) SignerName() (string, error)               // signer common name
func (s *Signature) Reason() (string, error)                   // signing reason
func (s *Signature) Location() (string, error)                 // signing location
func (s *Signature) SigningTime() (int64, error)               // Unix signing time
func (s *Signature) Verify() (bool, error)                     // verify the embedded signature
func (s *Signature) VerifyDetached(pdfData []byte) (bool, error) // verify against full PDF bytes
func (s *Signature) PAdESLevel() (PAdESLevel, error)           // detected PAdES level
func (s *Signature) Close()                                     // release the native handle

Timestamp

func (t *Timestamp) Time() (int64, error)                          // Unix timestamp time
func (t *Timestamp) Serial() (string, error)                       // serial number
func (t *Timestamp) PolicyOid() (string, error)                    // TSA policy OID
func (t *Timestamp) TsaName() (string, error)                      // TSA name
func (t *Timestamp) HashAlgorithm() (TimestampHashAlgorithm, error) // imprint hash algorithm
func (t *Timestamp) MessageImprint() ([]byte, error)               // message imprint bytes
func (t *Timestamp) Verify() (bool, error)                         // verify the timestamp
func (t *Timestamp) Close()                                         // release the native handle

TsaClient

func (c *TsaClient) RequestTimestamp(data []byte) (*Timestamp, error)                            // timestamp over data
func (c *TsaClient) RequestTimestampHash(hash []byte, algo TimestampHashAlgorithm) (*Timestamp, error) // timestamp over a digest
func (c *TsaClient) Close()                                                                       // release the client

Tipos auxiliares

type PAdESLevel int32
const (
    PAdESBB  PAdESLevel = 0 // CAdES-B-B
    PAdESBT  PAdESLevel = 1 // B-B + RFC 3161 signature timestamp
    PAdESBLt PAdESLevel = 2 // B-T + Document Security Store
    PAdESBLta PAdESLevel = 3 // reserved (not produced in this release)
)

type PAdESOptions struct {
    Level      PAdESLevel
    TSAURL     string              // required for Level >= PAdESBT
    Reason     string
    Location   string
    Revocation *RevocationMaterial // B-LT DSS material
}

type RevocationMaterial struct {
    Certs [][]byte // DER X.509 certificates
    CRLs  [][]byte // DER CRLs
    OCSPs [][]byte // DER OCSP responses
}

type DSS struct {
    Certs    [][]byte // document-level certificates
    CRLs     [][]byte // document-level CRLs
    OCSPs    [][]byte // document-level OCSP responses
    VRICount int      // per-signature /VRI entries
}

type TimestampHashAlgorithm int32
const (
    TimestampHashUnknown TimestampHashAlgorithm = 0
    TimestampHashSha1    TimestampHashAlgorithm = 1
    TimestampHashSha256  TimestampHashAlgorithm = 2
    TimestampHashSha384  TimestampHashAlgorithm = 3
    TimestampHashSha512  TimestampHashAlgorithm = 4
)

type TsaClientOptions struct {
    URL            string
    Username       string // optional
    Password       string // optional
    TimeoutSeconds int32  // 0 => 30s
    HashAlgorithm  TimestampHashAlgorithm
    UseNonce       bool
    CertReq        bool
}

---

Erros

Sentinelas

var (
    ErrInvalidPath              error
    ErrDocumentNotFound         error
    ErrInvalidFormat            error
    ErrExtractionFailed         error
    ErrParseError               error // deprecated alias for ErrInvalidFormat
    ErrInvalidPageIndex         error
    ErrSearchFailed             error
    ErrInternal                 error
    ErrDocumentClosed           error
    ErrEditorClosed             error
    ErrCreatorClosed            error
    ErrIndexOutOfBounds         error
    ErrEmptyContent             error
    ErrNotImplementedInPurego   error
    ErrCryptoPolicyInvalidArg   error
    ErrCryptoPolicyParse        error
    ErrCryptoPolicyAlreadySet   error
)

Use errors.Is para verificá-los. Para códigos numéricos e mensagens, use errors.As com *pdfoxide.Error.

Tipo de erro

type Error struct {
    Code    int
    Message string
}

func (e *Error) Error() string         // human-readable description
func (e *Error) Unwrap() error         // canonical sentinel (for errors.Is)
func (e *Error) Is(target error) bool  // compares by sentinel or Code

---

Tipos de dados

type SearchResult struct {
    Text          string
    Page          int
    X, Y          float32
    Width, Height float32
}

type Word struct {
    Text                string
    X, Y, Width, Height float32
    FontName            string
    FontSize            float32
    IsBold              bool
}

type TextLine struct {
    Text                string
    X, Y, Width, Height float32
    WordCount           int
}

type Char struct {
    Char                rune
    X, Y, Width, Height float32
    FontName            string
    FontSize            float32
}

type Table struct {
    RowCount  int
    ColCount  int
    HasHeader bool
}

func (t *Table) CellText(row, col int) string // text of one cell

type Path struct {
    X, Y, W, H     float32
    StrokeWidth    float32
    HasStroke      bool
    HasFill        bool
    OperationCount int
}

type Image struct {
    Width, Height    int
    Format           string
    Colorspace       string
    BitsPerComponent int
    Data             []byte
}

type Font struct {
    Name       string
    Type       string
    Encoding   string
    IsEmbedded bool
    IsSubset   bool
    Size       float32
}

type Annotation struct {
    Type, Subtype    string
    Content          string
    X, Y             float32
    Width, Height    float32
    Author           string
    BorderWidth      float32
    Color            uint32
    CreationDate     int64
    ModificationDate int64
    LinkURI          string
    TextIconName     string
    IsHidden         bool
    IsPrintable      bool
    IsReadOnly       bool
    IsMarkedDeleted  bool
}

type Element struct {
    Type          string
    Text          string
    X, Y          float32
    Width, Height float32
}

type FormField struct {
    Name     string
    Type     string
    Value    string
    ReadOnly bool
    Required bool
}

type Rect struct {
    X, Y, Width, Height float32
}

type PageInfo struct {
    Width    float32
    Height   float32
    Rotation int
    MediaBox Rect
    CropBox  Rect
    ArtBox   Rect
    BleedBox Rect
    TrimBox  Rect
}

type Metadata struct {
    Title        string
    Author       string
    Subject      string
    Producer     string
    CreationDate string
}

type PdfAResult struct {
    Compliant bool
    Errors    []string
    Warnings  []string
}

type SplitSegment struct {
    Index     int
    StartPage int
    EndPage   int
    Title     *string
    FileStem  string
    PageLabel *string
}

type SplitByBookmarksOptions struct {
    TitlePrefix        *string
    IgnoreCase         bool
    Level              int  // 0 = all depths, 1 = top-level only, n = up to depth n
    IncludeFrontMatter bool
}

Campos de string vazios em Metadata são tratados como “não alterar” por ApplyMetadata.

Tipos de valor do construtor (somente CGo)

type Alignment int
const (
    AlignLeft   Alignment = 0
    AlignCenter Alignment = 1
    AlignRight  Alignment = 2
)

type Column struct {
    Header string
    Width  float32
    Align  Alignment
}

type TableSpec struct {
    Columns   []Column
    Rows      [][]string
    HasHeader bool
}

type TableModeKind int
const (
    TableModeFixed  TableModeKind = 0 // use each Column.Width as-is
    TableModeSample TableModeKind = 1 // measure the first N rows, then freeze widths
)

type TableMode struct {
    Kind          TableModeKind
    SampleRows    int     // default 20
    MinColWidthPt float32 // default 0
    MaxColWidthPt float32 // default 9999
}

type StreamingTableConfig struct {
    Columns      []Column
    RepeatHeader bool
    Mode         TableMode
    MaxRowspan   int // >=2 enables PushRowSpan
    BatchSize    int // default 256
}

type SpanCell struct {
    Text    string
    Rowspan int
}

type RadioButton struct {
    Value      string
    X, Y, W, H float32
}

type FontEntry struct {
    Family string
    Bytes  []byte
}

Nível de logging

type LogLevel int
const (
    LogOff   LogLevel = 0
    LogError LogLevel = 1
    LogWarn  LogLevel = 2
    LogInfo  LogLevel = 3
    LogDebug LogLevel = 4
    LogTrace LogLevel = 5
)

---

Resumo de segurança entre threads

• Leituras em *PdfDocument — seguras para goroutines concorrentes (sync.RWMutex).
• *DocumentEditor — serialize as edições em uma única goroutine.
• *PdfCreator / *DocumentBuilder / *PageBuilder — não foram projetados para serem compartilhados entre goroutines.

Veja o guia de concorrência para conhecer os padrões.

---

Other Language Bindings

O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Python, Node.js, WASM, C#, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C e Elixir.

Próximos Passos

• Tipos e Enums — todos os tipos e enums compartilhados
• Referência da API Page — iteração consistente por página entre os bindings
• Primeiros Passos com Go — tutorial