文档模型

概述

document 包（Layer 2）提供页面尺寸、单位、样式和文档节点树的类型。大多数用户通过这些类型进行配置，而非直接操作节点树。

import "github.com/gpdf-dev/gpdf/document"

页面尺寸

var (
    A4     = Size{Width: 595.28, Height: 841.89}   // 210mm x 297mm
    A3     = Size{Width: 841.89, Height: 1190.55}   // 297mm x 420mm
    Letter = Size{Width: 612, Height: 792}           // 8.5" x 11"
    Legal  = Size{Width: 612, Height: 1008}          // 8.5" x 14"
)

Size

type Size struct {
    Width, Height float64  // in points (1pt = 1/72 inch)
}

单位和值

Value

带单位的尺寸值：

type Value struct {
    Amount float64
    Unit   Unit
}

单位构造函数

函数	单位	示例
`Pt(v)`	点（1/72 英寸）	`Pt(12)` — 原生 PDF 单位
`Mm(v)`	毫米	`Mm(20)` — 20mm 边距
`Cm(v)`	厘米	`Cm(2.5)` — 2.5cm
`In(v)`	英寸	`In(1)` — 1 英寸
`Em(v)`	相对于字号	`Em(2)` — 2 倍字号
`Pct(v)`	父元素的百分比	`Pct(50)` — 50%

// Usage examples
document.Mm(20)   // 20 millimeters
document.Pt(12)   // 12 points
document.In(0.5)  // half inch
document.Pct(50)  // 50% of parent

Value 方法

func (v Value) Resolve(parentSize, fontSize float64) float64
func (v Value) IsAuto() bool

Resolve() 将任何单位转换为点。IsAuto() 检查是否为自适应尺寸值。

Edges（盒模型）

Edges

type Edges struct {
    Top, Right, Bottom, Left Value
}

UniformEdges

func UniformEdges(v Value) Edges

创建所有边相同值的边距：

document.UniformEdges(document.Mm(20))  // 20mm on all sides

自定义边距

document.Edges{
    Top:    document.Mm(25),
    Right:  document.Mm(15),
    Bottom: document.Mm(25),
    Left:   document.Mm(15),
}

Style

Style 结构体控制所有视觉属性：

type Style struct {
    // Font
    FontFamily     string
    FontSize       float64
    FontWeight     FontWeight    // WeightNormal (400) or WeightBold (700)
    FontStyle      FontStyle     // StyleNormal or StyleItalic

    // Color
    Color          pdf.Color
    Background     *pdf.Color

    // Text layout
    TextAlign      TextAlign     // AlignLeft, AlignCenter, AlignRight, AlignJustify
    LineHeight     float64
    LetterSpacing  float64
    TextIndent     Value
    TextDecoration TextDecoration
    VerticalAlign  VerticalAlign

    // Box model
    Margin  Edges
    Padding Edges
    Border  BorderEdges
}

TextAlign

const (
    AlignLeft    TextAlign = iota  // default
    AlignCenter
    AlignRight
    AlignJustify
)

FontWeight

const (
    WeightNormal FontWeight = 400
    WeightBold   FontWeight = 700
)

TextDecoration

const (
    DecorationNone          TextDecoration = 0
    DecorationUnderline     TextDecoration = 1
    DecorationStrikethrough TextDecoration = 2
    DecorationOverline      TextDecoration = 4
)

装饰可以通过位或运算组合。

VerticalAlign

const (
    VAlignTop    VerticalAlign = iota  // default
    VAlignMiddle
    VAlignBottom
)

用于表格单元格的垂直对齐：

template.TableCellVAlign(document.VAlignMiddle)

文档元数据

type DocumentMetadata struct {
    Title    string
    Author   string
    Subject  string
    Creator  string
    Producer string
}

template.WithMetadata(document.DocumentMetadata{
    Title:  "Quarterly Report",
    Author: "ACME Corp",
})

图片类型

ImageFitMode

const (
    FitContain  ImageFitMode = iota  // Scale to fit within bounds (preserve ratio)
    FitCover                          // Scale to fill bounds (may crop)
    FitStretch                        // Stretch to fill (distort)
    FitOriginal                       // Use original image dimensions
)

ImageFormat

const (
    ImageFormatJPEG ImageFormat = iota
    ImageFormatPNG
)

节点类型

文档树由节点组成：

const (
    NodeDocument NodeType = iota
    NodePage
    NodeBox
    NodeText
    NodeImage
    NodeTable
    NodeList
    NodeRichText
)

大多数用户无需直接操作节点 — 模板构建器会自动创建它们。

几何类型

type Rectangle struct {
    X, Y, Width, Height float64
}

type Point struct {
    X, Y float64
}