document

Documentation

Overview

Package document opens a .docx (OOXML) package and exposes an in-memory model of its body: paragraphs, text runs, tables, and the formatting needed to lay them out (bold, italic, underline, font family, size, alignment, explicit page breaks, table column widths, cell merging/borders/shading).

The model is read eagerly on Open, so it is self-contained: the underlying ZIP is closed before Open returns and the returned Document does not depend on any open file handle.

Rendering of a Document into a paginated PDF: text measurement, word-wrap, per-run formatting, alignment, column and page breaks, headers and footers. The simplest entry points are the Document methods WritePDF (to a file) and WritePDFTo (to an io.Writer); ConvertToPdf exposes the same rendering as a reusable Converter.

Index

• Constants
• type Alignment
• type Anchor
• type BodyElement
• type BorderSide
• type Cell
• type CellBorders
• type CellMargins
• type Column
• type Converter
  • func ConvertToPdf(doc *Document) *Converter
  • func (c *Converter) Write(w io.Writer) error
  • func (c *Converter) WriteToFile(path string) error
• type Document
  • func Open(path string) (*Document, error)
  • func (d *Document) Close() error
  • func (d *Document) WritePDF(path string) error
  • func (d *Document) WritePDFTo(w io.Writer) error
• type Image
• type Indent
• type LineSpacingRule
• type PageGeometry
  • func DefaultPageGeometry() PageGeometry
• type Paragraph
• type ParagraphProperties
• type Row
• type RowHeightRule
• type Run
• type RunProperties
• type Section
• type Spacing
• type Table
• type TableFloat
• type TextDirection
• type VMergeState
• type VerticalAlign

Constants

const (
	FieldPage     = "PAGE"
	FieldNumPages = "NUMPAGES"
)

Field kinds a Run may carry (see Run.Field). Only page-number fields are computed; every other Word field renders its cached result text verbatim.

Types

type Alignment

type Alignment int

Alignment is a paragraph's horizontal alignment.

const (
	AlignLeft Alignment = iota
	AlignCenter
	AlignRight
	AlignJustify
)

type Anchor

type Anchor int

Anchor is what a floating table's position is measured from (w:horzAnchor / w:vertAnchor).

const (
	// AnchorText is the default: the position is measured from the text column
	// the table sits in.
	AnchorText Anchor = iota
	// AnchorMargin measures from the page's margin.
	AnchorMargin
	// AnchorPage measures from the edge of the page.
	AnchorPage
)

type BodyElement

type BodyElement struct {
	Paragraph *Paragraph
	Table     *Table
}

BodyElement is one paragraph- or table-level child of a Document's body, in document order. Exactly one of Paragraph or Table is non-nil.

type BorderSide

type BorderSide struct {
	Style   string // raw w:val (e.g. "single", "double"); "" means no border
	WidthPt float64
	Color   string // "#RRGGBB"; "" when undeclared or "auto"
}

BorderSide is one border's style, width, and color. A zero value means no border is drawn on that side.

type Cell

type Cell struct {
	Paragraphs []Paragraph
	// ColSpan is the number of grid columns this cell spans (from
	// w:gridSpan); 1 when absent.
	ColSpan int
	VMerge  VMergeState
	Borders CellBorders
	// Shading is the cell's background color ("#RRGGBB"), or "" when
	// undeclared or "auto"/"nil".
	Shading string
	// Margins is the cell's inner padding, resolved from w:tcMar, the table's
	// w:tblCellMar (inline then from its style), or Word's defaults.
	Margins CellMargins
	// TextDirection is which way the cell's text runs (w:textDirection).
	TextDirection TextDirection
	// VAlign is where the content sits within the cell's height (w:vAlign).
	VAlign VerticalAlign
	// Nested is the first table found directly inside this cell, or nil.
	Nested *Table
}

Cell is one table cell: its paragraphs, horizontal/vertical merge state, resolved borders, shading, margins, text direction and vertical alignment, and an optional nested table.

type CellBorders

type CellBorders struct {
	Top, Bottom, Left, Right BorderSide
	// DiagDown runs from the cell's top-left to its bottom-right (w:tl2br);
	// DiagUp runs from the bottom-left to the top-right (w:tr2bl).
	DiagDown, DiagUp BorderSide
}

CellBorders holds a cell's resolved per-side border (w:tcBorders overriding the table's w:tblBorders) plus its two diagonals, which only a cell can declare (w:tl2br, w:tr2bl).

type CellMargins

type CellMargins struct {
	TopPt, BottomPt, LeftPt, RightPt float64
	// The *Pct fields are sides declared as a percentage of the table's width
	// (w:type="pct") rather than in points; they are resolved against the table's
	// resolved width when it is laid out, and are zero for an ordinary side.
	TopPct, BottomPct, LeftPct, RightPct float64
}

CellMargins is a cell's inner padding, from w:tcMar (or the table's w:tblCellMar). The Word default is 108 dxa (5.4 pt) left and right, none top and bottom.

type Column

type Column struct {
	WidthPt, SpaceAfterPt float64
}

Column is one column of a Section: its width and the gap that separates it from the next column (zero on the last one).

type Converter

type Converter struct {
	// contains filtered or unexported fields
}

Converter renders a document to PDF. Create one with ConvertToPdf.

func ConvertToPdf

func ConvertToPdf(doc *Document) *Converter

ConvertToPdf returns a Converter that renders doc's body as flowed PDF text.

func (*Converter) Write

func (c *Converter) Write(w io.Writer) error

Write renders the document and writes the complete PDF byte stream to w.

func (*Converter) WriteToFile

func (c *Converter) WriteToFile(path string) error

WriteToFile renders the document and writes the PDF to path. It returns a non-nil error if the destination cannot be created or written; it never panics.

type Document

type Document struct {
	Body []BodyElement
	// Geometry is the page size and margins of the document's first section,
	// from w:sectPr.
	Geometry PageGeometry
	// Sections are the document's sections in order, each covering the range of
	// Body that ends at its End index. There is always at least one.
	Sections []Section
	// contains filtered or unexported fields
}

Document is the in-memory model of a .docx body.

func Open

func Open(path string) (*Document, error)

Open opens a .docx file, reads its word/document.xml main part, and returns an in-memory Document. It returns a nil Document and a non-nil error when the file does not exist, is not a valid ZIP archive, or lacks word/document.xml.

func (*Document) Close

func (d *Document) Close() error

Close releases resources held since Open. Because Open reads eagerly and closes the underlying package itself, Close only guards against double invocation; it is safe to call more than once and never panics.

func (*Document) WritePDF

func (d *Document) WritePDF(path string) error

WritePDF renders the document and writes the PDF to path, in one call:

doc, err := document.Open("in.docx")
...
err = doc.WritePDF("out.pdf")

func (*Document) WritePDFTo

func (d *Document) WritePDFTo(w io.Writer) error

WritePDFTo renders the document and writes the complete PDF byte stream to w.

type Image

type Image struct {
	// Name is the media part's name in the package (e.g. word/media/image1.png),
	// unique per picture, which the PDF backend uses as its cache key so an
	// image reused across the document is embedded once.
	Name string
	// Type is the encoded format: "PNG", "JPG" or "GIF".
	Type string
	Data []byte
	// WidthPt/HeightPt are the drawn size, from the picture's declared extent or
	// - when it declares none - its intrinsic pixel size at 96 dpi.
	WidthPt, HeightPt float64
}

Image is a picture embedded in the document, ready to be drawn: the media part's bytes together with the size the document draws it at.

type Indent

type Indent struct {
	LeftPt, RightPt float64
	// FirstLineOffsetPt shifts only the paragraph's first line: positive for
	// w:firstLine (indented further right), negative for w:hanging (indented
	// further left of the rest of the paragraph). Zero when neither is
	// declared.
	FirstLineOffsetPt float64
}

Indent is a paragraph's indentation in points, from w:ind.

type LineSpacingRule

type LineSpacingRule int

LineSpacingRule is how a paragraph's line height is determined, from w:spacing's w:lineRule.

const (
	// LineSpacingSingle means no w:line was declared; the renderer applies its
	// own default line-height multiplier.
	LineSpacingSingle LineSpacingRule = iota
	// LineSpacingMultiple (w:lineRule="auto") multiplies the line's font size;
	// LineValue is the multiple (w:line ÷ 240).
	LineSpacingMultiple
	// LineSpacingExact (w:lineRule="exact") fixes the line height; LineValue is
	// that height in points (w:line ÷ 20).
	LineSpacingExact
	// LineSpacingAtLeast (w:lineRule="atLeast") is a minimum line height;
	// LineValue is that minimum in points (w:line ÷ 20).
	LineSpacingAtLeast
)

type PageGeometry

type PageGeometry struct {
	WidthPt, HeightPt                                        float64
	MarginTopPt, MarginRightPt, MarginBottomPt, MarginLeftPt float64
}

PageGeometry is the document's page size and margins in points, resolved from the body-level w:sectPr (w:pgSz/w:pgMar). When the document declares no section geometry, it defaults to A4 (595.28 × 841.89 pt) with one-inch (72 pt) margins on all sides.

func DefaultPageGeometry

func DefaultPageGeometry() PageGeometry

DefaultPageGeometry returns the fallback geometry used when a document declares no section geometry: A4 with one-inch margins.

type Paragraph

type Paragraph struct {
	Runs  []Run
	Props ParagraphProperties
}

Paragraph is an ordered sequence of runs plus its paragraph properties.

type ParagraphProperties

type ParagraphProperties struct {
	Alignment Alignment
	// PageBreak reports whether an explicit page break precedes this paragraph
	// (a <w:br w:type="page"/> in one of its runs or <w:pageBreakBefore/>).
	PageBreak bool
	// ColumnBreak reports an explicit column break (<w:br w:type="column"/>)
	// preceding this paragraph: in a multi-column section it moves to the next
	// column, and on the last column to the next page.
	ColumnBreak bool
	// Indent is the paragraph's left/right/first-line indentation (from
	// w:ind), in points. The zero value is no indent.
	Indent Indent
	// Spacing is the paragraph's space-before/space-after (from w:spacing),
	// in points. The zero value is no added spacing.
	Spacing Spacing
	// Shading is the paragraph's background color as "#RRGGBB" (from w:shd), or
	// "" when it has none. It is painted across the paragraph's indented text
	// area, behind its lines.
	Shading string
}

ParagraphProperties is the paragraph-level formatting needed for layout.

type Row

type Row struct {
	Cells []Cell
	// Header reports a header row (w:tblHeader): one repeated at the top of each
	// page the table spills onto.
	Header bool
	// HeightPt and HeightRule are the row's declared height (w:trHeight); the
	// rule is RowHeightAuto when it declares none.
	HeightPt   float64
	HeightRule RowHeightRule
}

Row is an ordered sequence of cells.

type RowHeightRule

type RowHeightRule int

RowHeightRule is how a row's declared height (w:trHeight) constrains it.

const (
	// RowHeightAuto means the row declares no height: it is as tall as its
	// content needs.
	RowHeightAuto RowHeightRule = iota
	// RowHeightAtLeast (w:hRule="atLeast") floors the row's height.
	RowHeightAtLeast
	// RowHeightExact (w:hRule="exact") fixes it, even below what the content
	// needs.
	RowHeightExact
)

type Run

type Run struct {
	Text      string
	Props     RunProperties
	LineBreak bool
	// Image is the picture this run draws instead of Text (an inline w:drawing
	// or a picture bullet); nil for a text run.
	Image *Image
	// MinWidthPt floors the run's advance width, so what follows it starts at
	// least that far along: a list marker's tab suffix reserves the level's
	// hanging indent this way, putting the paragraph's text at the tab stop
	// Word aligns it to. Zero for an ordinary run.
	MinWidthPt float64
	// Field, when set, marks this run as a computed field the renderer fills in
	// at draw time: FieldPage → the page's own number, FieldNumPages → the total
	// page count. Text holds the value cached in the .docx, used as-is until the
	// renderer overwrites it. "" for an ordinary run.
	Field string
}

Run is a span of text sharing one set of character-formatting properties, an inline image, or an explicit in-paragraph line break. When LineBreak is true the run carries no text and Props is unset; it marks a `<w:br/>` at its position among the paragraph's runs.

type RunProperties

type RunProperties struct {
	Bold       bool
	Italic     bool
	Underline  bool
	FontFamily string
	SizePt     float64
	// Color is the run's resolved text color as "#RRGGBB", or "" when
	// undeclared, "auto", or an unresolved theme reference - the renderer draws
	// "" as the backend default (black).
	Color string
	// Shading is the run's background color as "#RRGGBB", or "" when it has
	// none: the run's w:highlight, or - when it carries none - its w:shd, which
	// the highlight would paint over anyway.
	Shading string
}

RunProperties is the character formatting a Run needs for layout.

type Section

type Section struct {
	Geometry PageGeometry
	// Columns always holds at least one column; a single full-width column is
	// the default when the section declares no w:cols.
	Columns []Column
	// Separator draws a vertical rule down the middle of each inter-column gap
	// (w:cols/@w:sep); only meaningful with more than one column.
	Separator bool
	// End is the exclusive index into Document.Body where this section ends -
	// Body[Start:End] with Start being the previous section's End.
	End int
	// Continuous reports a w:type="continuous" section break: the new section
	// resumes on the current page instead of starting a new one.
	Continuous bool
	// Header/Footer are the default page's content; FirstHeader/FirstFooter
	// replace them on the section's first page when TitlePage is set (an empty
	// slice then means "no header on the title page", which is what Word draws).
	Header, Footer           []BodyElement
	FirstHeader, FirstFooter []BodyElement
	TitlePage                bool
	// HeaderOffsetPt/FooterOffsetPt are w:pgMar's w:header/w:footer: the header's
	// distance from the top edge of the page, and the footer's from the bottom.
	HeaderOffsetPt, FooterOffsetPt float64
}

Section is one w:sectPr's worth of a document: the page geometry, column layout, and header/footer content that apply to the body elements it covers.

type Spacing

type Spacing struct {
	BeforePt, AfterPt float64
	// LineRule and LineValue describe line spacing; LineRule is
	// LineSpacingSingle (and LineValue 0) when w:line is absent.
	LineRule  LineSpacingRule
	LineValue float64
}

Spacing is a paragraph's space-before/space-after and line spacing, from w:spacing. The zero value is no added spacing and single (default) line spacing.

type Table

type Table struct {
	Rows []Row
	// ColumnWidths is each column's width in points. A zero width means the
	// column declares none and is sized from its content when the table is laid
	// out (Word's auto-fit), possibly via ColumnPercents.
	ColumnWidths []float64
	// ColumnPercents is each column's width as a percentage of the available
	// width (from a w:tcW of type "pct"), or zero when it declares none. Only
	// consulted for a column whose ColumnWidths entry is zero.
	ColumnPercents []float64
	// IndentPt is the table's resolved left indent in points (from
	// w:tblInd, inline winning over the table's named style). Zero when
	// neither declares one.
	IndentPt float64
	// HeaderRows is how many leading rows are marked as header rows
	// (w:tblHeader) and are therefore repeated at the top of every page the
	// table continues onto.
	HeaderRows int
	// FixedLayout reports w:tblLayout w:type="fixed": the declared widths are the
	// widths, and the content never gets a say. A column left undeclared then
	// takes an equal share of what the others leave, instead of being sized from
	// what is in it.
	FixedLayout bool
	// WidthPt and WidthPct are the table's own declared width (w:tblW), in points
	// or as a percentage of the width available to it; both are zero for an "auto"
	// width. The columns are scaled to whichever is declared.
	WidthPt  float64
	WidthPct float64
	// Float is a floating table's placement (w:tblpPr), or nil for one that flows
	// with the text.
	Float *TableFloat
}

Table is a parsed <w:tbl>: an ordered sequence of rows plus each column's resolved width in points (from w:tblGrid, or - when absent - the widest w:tcW seen for that column).

type TableFloat

type TableFloat struct {
	XPt, YPt               float64
	HorzAnchor, VertAnchor Anchor
	// XSpec/YSpec are w:tblpXSpec/w:tblpYSpec ("left"/"center"/"right",
	// "top"/"center"/"bottom"); "" means the offset is used instead.
	XSpec, YSpec string
}

TableFloat is a floating table's placement (w:tblpPr): an offset from its anchor, or - when the document names one instead - an alignment against it.

type TextDirection

type TextDirection int

TextDirection is how a cell's text runs (w:textDirection).

const (
	// TextDirectionHorizontal is ordinary left-to-right text (the default, and
	// w:val="lrTb").
	TextDirectionHorizontal TextDirection = iota
	// TextDirectionBTLR rotates the text 90° counter-clockwise, so it reads
	// bottom-to-top (w:val="btLr").
	TextDirectionBTLR
	// TextDirectionTBRL rotates the text 90° clockwise, so it reads top-to-bottom
	// down the right (w:val="tbRl"/"tbRlV").
	TextDirectionTBRL
)

type VMergeState

type VMergeState int

VMergeState is a cell's role in a vertical merge (w:vMerge).

const (
	// VMergeNone means the cell does not participate in a vertical merge.
	VMergeNone VMergeState = iota
	// VMergeRestart means the cell starts a new vertical merge, absorbing the
	// VMergeContinue cells below it in the same column.
	VMergeRestart
	// VMergeContinue means the cell continues the vertical merge started by
	// the VMergeRestart cell above it; its own content is not drawn.
	VMergeContinue
)

type VerticalAlign

type VerticalAlign int

VerticalAlign is where a cell's content sits within its height (w:vAlign).

const (
	// VAlignTop is the default: content starts at the cell's top margin.
	VAlignTop VerticalAlign = iota
	VAlignCenter
	VAlignBottom
)