gpdf 包

概述

gpdf 包是一个外观模式，从内部层重新导出常用函数。你可以导入 gpdf 以便使用，也可以直接导入特定的包。

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

函数

NewDocument

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

创建一个新的 PDF 文档构建器。这是主要入口点。

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)

从 JSON schema 定义创建 Document，支持可选的 Go 模板数据绑定。

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

FromTemplate

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

通过执行预解析的 Go 模板创建 Document，该模板生成 JSON schema 输出。

TemplateFuncMap

func TemplateFuncMap() template.FuncMap

返回辅助函数（toJSON 等），用于解析 Go 模板时使用。

文档选项

函数	说明
`WithPageSize(size)`	设置页面尺寸（`A4`、`A3`、`Letter`、`Legal`）
`WithMargins(edges)`	设置页面边距
`WithFont(family, data)`	注册 TrueType 字体（接受 `[]byte`）
`WithDefaultFont(family, size)`	设置默认字体族和字号
`WithMetadata(meta)`	设置文档元数据
`WithEncryption(opts...)`	启用 AES-256 加密
`WithPDFA(opts...)`	启用 PDF/A 合规

文档元数据

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

页面尺寸

常量	尺寸
`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)

Document 方法

AddPage

func (d *Document) AddPage() *PageBuilder

添加新页面并返回其构建器。

Header / Footer

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

定义在每一页重复的内容。

Generate / Render

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

Generate() 返回 PDF 的字节切片。Render() 直接写入 io.Writer。

PageBuilder 方法

Row

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

Row() 创建固定高度的行。AutoRow() 创建根据内容自适应的行。

RowBuilder 方法

Col

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

创建占 12 列网格中 span 列的列。

ColBuilder 方法

方法	说明
`Text(text, opts...)`	添加带样式选项的文本
`Image(data, opts...)`	添加图片（JPEG 或 PNG 字节）
`Table(headers, rows, opts...)`	添加表格
`List(items, opts...)`	添加无序列表
`OrderedList(items, opts...)`	添加有序列表
`Line(opts...)`	添加水平分割线
`Spacer(height)`	添加垂直间距
`QRCode(data, opts...)`	添加二维码
`Barcode(data, opts...)`	添加条形码（Code 128）
`RichText(fn)`	添加混合样式的行内文本
`PageNumber(opts...)`	当前页码
`TotalPages(opts...)`	总页数

二维码选项

函数	说明
`QRSize(value)`	显示尺寸（宽度 = 高度）
`QRErrorCorrection(level)`	纠错级别：`LevelL`、`LevelM`、`LevelQ`、`LevelH`
`QRScale(s)`	每个 QR 模块的像素数

条形码选项

函数	说明
`BarcodeWidth(value)`	显示宽度
`BarcodeHeight(value)`	显示高度
`BarcodeFormat(format)`	条形码格式（默认：Code 128）

已有 PDF 操作

Open

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

打开已有 PDF 进行读取和修改。返回支持通过增量更新（非破坏性追加）进行叠加操作的 ExistingDocument。

doc, err := gpdf.Open(pdfBytes)

ExistingDocument 方法

方法	说明
`PageCount() (int, error)`	返回 PDF 的页数
`Overlay(pageIndex int, fn func(p *PageBuilder)) error`	在指定页面上添加内容（从 0 开始索引）
`EachPage(fn func(pageIndex int, p *PageBuilder)) error`	在每一页上添加内容
`FlattenForms() error`	将所有 AcroForm 字段扁平化为静态页面内容 Since v1.0.4
`Save() ([]byte, error)`	返回修改后的 PDF 字节切片

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

PDF合并 Since v1.0.2

Merge

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

将多个PDF源的页面合并为一个输出PDF。

merged, err := gpdf.Merge([]gpdf.Source{
    {Data: cover},
    {Data: body},
})

Source

type Source struct {
    Data  []byte    // 原始PDF字节
    Pages PageRange // 包含的页面。零值 = 所有页面
}

PageRange

type PageRange struct {
    From int  // 基于1的起始页。0 = 第一页
    To   int  // 基于1的结束页。0 = 最后一页
}

合并选项

函数	描述
`WithMergeMetadata(title, author, producer)`	设置合并输出的文档信息（标题、作者、制作者）

merged, err := gpdf.Merge(
    []gpdf.Source{
        {Data: cover},
        {Data: body},
        {Data: appendix},
    },
    gpdf.WithMergeMetadata("Policy Bundle", "Example Ltd", "gpdf"),
)

组件构造函数

函数	说明
`NewInvoice(data)`	创建发票 PDF
`NewReport(data)`	创建报告 PDF
`NewLetter(data)`	创建商务信函 PDF

详见组件。