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スキーマ定義とオプションのGoテンプレートデータバインディングからDocumentを作成します。

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

FromTemplate

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

JSONスキーマ出力を生成するパース済みGoテンプレートを実行してDocumentを作成します。

TemplateFuncMap

func TemplateFuncMap() template.FuncMap

Goテンプレートのパース時に使用するヘルパー関数（toJSON など）を返します。

ドキュメントオプション

関数	説明
`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...)`	QRコードを追加
`Barcode(data, opts...)`	バーコードを追加（Code 128）
`RichText(fn)`	混合スタイルのインラインテキストを追加
`PageNumber(opts...)`	現在のページ番号
`TotalPages(opts...)`	合計ページ数

QRコードオプション

関数	説明
`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ソースのページを1つの出力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を作成

詳細はコンポーネントを参照してください。