Go API 参考
github.com/yfedoseev/pdf_oxide/go 模块通过 CGo 封装 Rust 内核。自 v0.3.27 起，它将 Rust 库以 staticlib 形式链接，生成完全自包含的 Go 二进制 — 运行时无需任何库配置。
go get github.com/yfedoseev/pdf_oxide/go
import pdfoxide "github.com/yfedoseev/pdf_oxide/go"
提供两种后端。默认的 cgo 后端（CGO_ENABLED=1）暴露本文档记录的全部接口。purego 后端（CGO_ENABLED=0）提供一个子集 — 打开、提取、转换、搜索、基础编辑、涂黑以及签名读取；该后端缺失的方法会返回 ErrNotImplementedInPurego。DocumentBuilder、OCR、渲染和条码生成仅在 cgo 下可用。
其他语言请参见 Python、Node.js、C# 或 Rust。完整的自动生成文档见 pkg.go.dev/github.com/yfedoseev/pdf_oxide/go。
包级函数
打开
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
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
生成
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
条码
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
签名
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
时间戳（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
文档构建器与字体
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
日志与全局可调项
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)
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
加密提供方 / 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)
自动提取选项
传给 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
只读访问。读取由内部的 sync.RWMutex 保护 — 可安全地在多个 goroutine 中并发使用。
生命周期
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
文档信息
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
分类
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
页面（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 会把所有提取方法转发给父文档：
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
文本提取
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
转换
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
Office 导出与 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
结构化提取
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
区域提取
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
资源
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)
页面清理
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
搜索
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
文档结构与元数据
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)
校验
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
渲染
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
format 取值：0 = PNG，1 = JPEG。
签名
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
写入在内部串行化 — 单个 goroutine 独占一个 editor 时是安全的，但不要跨 goroutine 以流水线方式提交互不相关的编辑。
生命周期与信息
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
元数据
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
页面
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
擦除 / 涂白
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
注释与表单
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
涂黑与净化
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
合并与嵌入
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
保存
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
由 FromMarkdown/FromHtml/FromText/FromImage 系列返回。不可在多个 goroutine 间并发使用。
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（仅 CGo）
流式多页构建器。//go:build cgo — 在 CGO_ENABLED=0 下不可用。
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（仅 CGo）
由 DocumentBuilder.A4Page / LetterPage / Page 返回。每个内容方法都返回 *PageBuilder 以便链式调用；调用 Done 返回到父构建器。
文本与布局
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
行内片段
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
注释
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
表单控件与 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
图像与条码
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
图形基元
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
表格
func (p *PageBuilder) Table(spec TableSpec) *PageBuilder // buffered table
func (p *PageBuilder) StreamingTable(cfg StreamingTableConfig) *StreamingTable // row-at-a-time streaming table
收尾
func (p *PageBuilder) Done() (*DocumentBuilder, error) // commit the page and return to the builder
func (p *PageBuilder) Close() error // discard the page
示例
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（仅 CGo）
由 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
OCR 文本提取通过文档方法 NeedsOcr、ExtractTextWithOcr 以及 Page.TextWithOcr 句柄完成。请使用 go build -tags ocr ./... 构建。
RenderedImage
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 还携带 Width 与 Height 字段（像素）。
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
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
签名与时间戳
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
配套类型
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
}
错误
哨兵错误
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
)
使用 errors.Is 进行判断。要获取数字码与消息，请用 errors.As 配合 *pdfoxide.Error。
错误类型
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
数据类型
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
}
Metadata 中为空字符串的字段会被 ApplyMetadata 视为「不修改」。
构建器值类型（仅 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
}
日志级别
type LogLevel int
const (
LogOff LogLevel = 0
LogError LogLevel = 1
LogWarn LogLevel = 2
LogInfo LogLevel = 3
LogDebug LogLevel = 4
LogTrace LogLevel = 5
)
线程安全总览
*PdfDocument读取 — 可在多个 goroutine 中并发安全使用（sync.RWMutex）。*DocumentEditor— 请在单个 goroutine 上串行化编辑。*PdfCreator/*DocumentBuilder/*PageBuilder— 不应在多个 goroutine 间共享。
模式参见并发指南。
Other Language Bindings
PDF Oxide 为所有主流生态系统提供原生绑定：Rust, Python, Node.js, WASM, C#, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir。
下一步
- 类型与枚举 — 所有共享类型与枚举
- Page API 参考 — 各绑定间一致的逐页迭代方式
- Go 快速上手 — 教程