Documentation
¶
Overview ¶
Package docx provides a comprehensive set of functions and structures for manipulating DOCX documents. It allows for the creation, modification, and retrieval of document elements such as paragraphs, styles, and images. The package is designed to be accessed through the RootDoc element or instances of inner elements, providing a flexible and intuitive API for working with Office Open XML (OOXML) documents.
// The RootDoc structure is initialized from the main godocx package, which provides methods for creating a new document from a default template or opening an existing document.
Index ¶
- func LoadStyles(fileName string, fileBytes []byte) (*ctypes.Styles, error)
- func MIMEFromExt(extension string) (string, error)
- type Background
- type Body
- type Cell
- func (c *Cell) AddEmptyPara() *Paragraph
- func (c *Cell) AddParagraph(text string) *Paragraph
- func (c *Cell) BackgroundColor(color string) *Cell
- func (c *Cell) Borders(top *ctypes.Border, left *ctypes.Border, bottom *ctypes.Border, ...) *Cell
- func (c *Cell) ColSpan(cols int) *Cell
- func (c *Cell) RowSpan() *Cell
- func (c *Cell) VerticalAlign(valign string) *Cell
- func (c *Cell) Width(width int, widthType stypes.TableWidth) *Cell
- type ContentTypes
- type CoreProperties
- type Default
- type Document
- type DocumentChild
- type ExtendedProperties
- type HeadingPairs
- type Hyperlink
- func (r *Hyperlink) Bold(value bool) *Hyperlink
- func (r *Hyperlink) Caps(value bool) *Hyperlink
- func (r *Hyperlink) Color(colorCode string) *Hyperlink
- func (r *Hyperlink) DoubleStrike(value bool) *Hyperlink
- func (r *Hyperlink) Emboss(value bool) *Hyperlink
- func (r *Hyperlink) Font(font string) *Hyperlink
- func (r *Hyperlink) HideText(value bool) *Hyperlink
- func (r *Hyperlink) Highlight(color string) *Hyperlink
- func (r *Hyperlink) Imprint(value bool) *Hyperlink
- func (r *Hyperlink) Italic(value bool) *Hyperlink
- func (r *Hyperlink) NoGrammer(value bool) *Hyperlink
- func (r *Hyperlink) Outline(value bool) *Hyperlink
- func (r *Hyperlink) Shading(shdType stypes.Shading, color, fill string) *Hyperlink
- func (r *Hyperlink) Shadow(value bool) *Hyperlink
- func (r *Hyperlink) Size(size uint64) *Hyperlink
- func (r *Hyperlink) SmallCaps(value bool) *Hyperlink
- func (r *Hyperlink) SnapToGrid(value bool) *Hyperlink
- func (r *Hyperlink) Spacing(value int) *Hyperlink
- func (r *Hyperlink) Strike(value bool) *Hyperlink
- func (r *Hyperlink) Style(value string) *Hyperlink
- func (r *Hyperlink) Underline(value stypes.Underline) *Hyperlink
- func (r *Hyperlink) VerticalAlign(value stypes.VerticalAlignRun) *Hyperlink
- type Override
- type Paragraph
- func (p *Paragraph) AddLink(text string, link string) *Hyperlink
- func (p *Paragraph) AddPicture(path string, width units.Inch, height units.Inch) (*PicMeta, error)
- func (p *Paragraph) AddRun() *Run
- func (p *Paragraph) AddText(text string) *Run
- func (p *Paragraph) GetCT() *ctypes.Paragraph
- func (p *Paragraph) GetStyle() (*ctypes.Style, error)
- func (p *Paragraph) Indent(indentProp *ctypes.Indent)
- func (p *Paragraph) Justification(value stypes.Justification)
- func (p *Paragraph) Numbering(id int, level int)
- func (p *Paragraph) Spacing(before uint64, after uint64)
- func (p *Paragraph) Style(value string)
- type PicMeta
- type Relationship
- type Relationships
- type RootDoc
- func (rd *RootDoc) AddEmptyParagraph() *Paragraph
- func (rd *RootDoc) AddHeading(text string, level uint) (*Paragraph, error)
- func (rd *RootDoc) AddPageBreak() *Paragraph
- func (rd *RootDoc) AddParagraph(text string) *Paragraph
- func (rd *RootDoc) AddPicture(path string, width units.Inch, height units.Inch) (*PicMeta, error)
- func (rd *RootDoc) AddTable() *Table
- func (rd *RootDoc) Close() error
- func (rd *RootDoc) GetStyleByID(styleID string, styleType stypes.StyleType) *ctypes.Style
- func (rd *RootDoc) Save() error
- func (rd *RootDoc) SaveTo(fileName string) error
- func (rd *RootDoc) Write(w io.Writer) error
- func (rd *RootDoc) WriteTo(w io.Writer) (int64, error)
- type Row
- type Run
- func (r *Run) AddBreak(breakType *stypes.BreakType)
- func (r *Run) Bold(value bool) *Run
- func (r *Run) Caps(value bool) *Run
- func (r *Run) Color(colorCode string) *Run
- func (r *Run) DoubleStrike(value bool) *Run
- func (r *Run) Emboss(value bool) *Run
- func (r *Run) Font(font string) *Run
- func (r *Run) HideText(value bool) *Run
- func (r *Run) Highlight(color string) *Run
- func (r *Run) Imprint(value bool) *Run
- func (r *Run) Italic(value bool) *Run
- func (r *Run) NoGrammer(value bool) *Run
- func (r *Run) Outline(value bool) *Run
- func (r *Run) Shading(shdType stypes.Shading, color, fill string) *Run
- func (r *Run) Shadow(value bool) *Run
- func (r *Run) Size(size uint64) *Run
- func (r *Run) SmallCaps(value bool) *Run
- func (r *Run) SnapToGrid(value bool) *Run
- func (r *Run) Spacing(value int) *Run
- func (r *Run) Strike(value bool) *Run
- func (r *Run) Style(value string) *Run
- func (r *Run) Underline(value stypes.Underline) *Run
- func (r *Run) VerticalAlign(value stypes.VerticalAlignRun) *Run
- type Table
- func (t *Table) AddRow() *Row
- func (t *Table) CellMargin(top *ctypes.TableWidth, left *ctypes.TableWidth, bottom *ctypes.TableWidth, ...) *Table
- func (t *Table) Grid(widths ...uint64) *Table
- func (t *Table) Indent(indent int)
- func (t *Table) Layout(layout stypes.TableLayout) *Table
- func (t *Table) Style(value string)
- func (t *Table) Width(v int, u stypes.TableWidth) *Table
- type TitlesOfParts
- type Variant
- type Vector
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadStyles ¶
Load styles.xml into Styles struct
func MIMEFromExt ¶
Types ¶
type Background ¶
type Background struct {
Color *string `xml:"color,attr,omitempty"`
ThemeColor *stypes.ThemeColor `xml:"themeColor,attr,omitempty"`
ThemeTint *string `xml:"themeTint,attr,omitempty"`
ThemeShade *string `xml:"themeShade,attr,omitempty"`
}
Specifies the background information for this document
This background shall be displayed on all pages of the document, behind all other document content.
func NewBackground ¶
func NewBackground() *Background
func (Background) MarshalXML ¶
func (b Background) MarshalXML(e *xml.Encoder, start xml.StartElement) error
type Body ¶
type Body struct {
XMLName xml.Name `xml:"http://schemas.openxmlformats.org/wordprocessingml/2006/main body"`
Children []DocumentChild
SectPr *ctypes.SectionProp
// contains filtered or unexported fields
}
This element specifies the contents of the body of the document – the main document editing surface.
func (Body) MarshalXML ¶
MarshalXML implements the xml.Marshaler interface for the Body type. It encodes the Body to its corresponding XML representation.
func (*Body) UnmarshalXML ¶
UnmarshalXML implements the xml.Unmarshaler interface for the Body type. It decodes the XML representation of the Body.
type Cell ¶
type Cell struct {
// contains filtered or unexported fields
}
Cell Wrapper
func (*Cell) AddEmptyPara ¶
Add empty paragraph without any text and returns Paragraph
func (*Cell) AddParagraph ¶
Adds paragraph with text and returns Paragraph
func (*Cell) BackgroundColor ¶
func (*Cell) RowSpan ¶
RowSpan sets the cell to span vertically in a table, indicating it is part of a vertically merged group of cells.
func (*Cell) VerticalAlign ¶
VerticalAlign sets the vertical alignment of a cell based on the provided string: "top", "center", "middle", or "bottom".
type ContentTypes ¶
type ContentTypes struct {
XMLName xml.Name `xml:"http://schemas.openxmlformats.org/package/2006/content-types Types"`
Default []Default `xml:"Default"`
Override []Override `xml:"Override"`
}
Types represents the root structure of the XML document.
func (*ContentTypes) AddExtension ¶
func (c *ContentTypes) AddExtension(extension, contentType string) error
func (*ContentTypes) AddOverride ¶
func (c *ContentTypes) AddOverride(partName, contentType string) error
type CoreProperties ¶
type CoreProperties struct {
Category string
ContentStatus string
Created string
Creator string
Description string
Identifier string
Keywords string
LastModifiedBy string
Modified string
Revision string
Subject string
Title string
Language string
Version string
}
CoreProperties represents the core properties of a document, such as title, creator, and version. It is used to store metadata information about the document.
func LoadDocProps ¶
func LoadDocProps(fileBytes []byte) (cp *CoreProperties, err error)
LoadDocProps decodes the provided XML data and returns a CoreProperties instance. It is used to load core properties from the document file.
Parameters:
- fileBytes: The XML data representing the core properties of the document.
Returns:
- cp: The CoreProperties instance containing the decoded core properties.
- err: An error, if any occurred during the decoding process.
type Default ¶
type Default struct {
Extension string `xml:"Extension,attr"`
ContentType string `xml:"ContentType,attr"`
}
Default represents the <Default> XML element.
type Document ¶
type Document struct {
// Reference to the RootDoc
Root *RootDoc
// Elements
Background *Background
Body *Body
// Non elements - helper fields
DocRels Relationships // DocRels represents relationships specific to the document.
RID int
// contains filtered or unexported fields
}
This element specifies the contents of a main document part in a WordprocessingML document.
func LoadDocXml ¶
LoadDocXml decodes the provided XML data and returns a Document instance. It is used to load the main document structure from the document file.
Parameters:
- fileName: The name of the document file.
- fileBytes: The XML data representing the main document structure.
Returns:
- doc: The Document instance containing the decoded main document structure.
- err: An error, if any occurred during the decoding process.
func (*Document) IncRelationID ¶
IncRelationID increments the relation ID of the document and returns the new ID. This method is used to generate unique IDs for relationships within the document.
func (Document) MarshalXML ¶
MarshalXML implements the xml.Marshaler interface for the Document type.
func (*Document) UnmarshalXML ¶
type DocumentChild ¶
DocumentChild represents a child element within a Word document, which can be a Paragraph or a Table.
type ExtendedProperties ¶
type ExtendedProperties struct {
Application string
ScaleCrop bool
DocSecurity int
Company string
LinksUpToDate bool
HyperlinksChanged bool
AppVersion string
}
ExtendedProperties represents extended properties of a document, such as application details and statistics. It is used to store additional metadata information about the document.
type HeadingPairs ¶
type HeadingPairs struct {
Vector Vector `xml:"HeadingPairs"`
}
HeadingPairs represents a set of heading pairs used in extended properties.
type Hyperlink ¶
type Hyperlink struct {
// contains filtered or unexported fields
}
func (*Hyperlink) Caps ¶
Display All Characters As Capital Letters Any lowercase characters in this text hyperlink shall be formatted for display only as their capital letter character equivalents
func (*Hyperlink) Color ¶
Sets the color of the Hyperlink.
Example:
modifiedHyperlink := hyperlink.Color("FF0000")
Parameters:
- colorCode: A string representing the color code (e.g., "FF0000" for red).
Returns:
- *Hyperlink: The modified Hyperlink instance with the updated color.
func (*Hyperlink) DoubleStrike ¶
Specifies that the contents of this hyperlink shall be displayed with two horizontal lines through each character displayed on the line
func (*Hyperlink) Shading ¶
Shading sets the shading properties (type, color, fill) for the hyperlink
func (*Hyperlink) Size ¶
Returns:
- *Hyperlink: The modified Hyperlink instance with the updated size.
func (*Hyperlink) SmallCaps ¶
Specifies that all small letter characters in this text hyperlink shall be formatted for display only as their capital letter character equivalents
func (*Hyperlink) SnapToGrid ¶
Use Document Grid Settings For Inter-Character Spacing
func (*Hyperlink) Strike ¶
Specifies that the contents of this hyperlink shall be displayed with a single horizontal line through the center of the line.
func (*Hyperlink) VerticalAlign ¶
func (r *Hyperlink) VerticalAlign(value stypes.VerticalAlignRun) *Hyperlink
VerticalAlign sets the vertical alignment for the hyperlink text.
Parameter: A value from the stypes.VerticalAlignRun type indicating the desired vertical alignment. One of:
VerticalAlignRunBaseline, VerticalAlignRunSuperscript, VerticalAlignRunSubscript
Returns: The modified Hyperlink instance with the updated vertical alignment.
type Override ¶
type Override struct {
PartName string `xml:"PartName,attr"`
ContentType string `xml:"ContentType,attr"`
}
Override represents the <Override> XML element.
type Paragraph ¶
type Paragraph struct {
// contains filtered or unexported fields
}
Paragraph represents a paragraph in a DOCX document.
func (*Paragraph) AddPicture ¶
func (*Paragraph) AddText ¶
Appends a new text to the Paragraph. Example:
paragraph := AddParagraph()
modifiedParagraph := paragraph.AddText("Hello, World!")
Parameters:
- text: A string representing the text to be added to the Paragraph.
Returns:
- *Run: The newly created Run instance added to the Paragraph.
func (*Paragraph) GetStyle ¶
GetStyle retrieves the style information applied to the Paragraph.
Returns:
- *ctypes.Style: The style information of the Paragraph.
- error: An error if the style information is not found.
func (*Paragraph) Indent ¶
Indent sets the paragraph indentation properties.
This function assigns an indent definition to the paragraph, which affects how exactly the paragraph is going to be indented.
Parameters:
- indentProp: A ctypes.Indent instance pointer representing exact indentation measurements to use.
Example:
var size360 int = 360
var sizeu420 uint64 = 420
indent360 := ctypes.Indent{Left: &size360, Hanging: &sizeu420}
p1 := document.AddParagraph("Example indented para")
p1.Indent(&indent360)
func (*Paragraph) Justification ¶
func (p *Paragraph) Justification(value stypes.Justification)
Justification sets the paragraph justification type.
Parameters:
- value: A value of type stypes.Justification representing the justification type. It can be one of the Justification type values defined in the stypes package.
Example:
p1 := document.AddParagraph("Example justified para")
p1.Justification(stypes.JustificationCenter) // Center justification
func (*Paragraph) Numbering ¶
Numbering sets the paragraph numbering properties.
This function assigns a numbering definition ID and a level to the paragraph, which affects how numbering is displayed in the document.
Parameters:
- id: An integer representing the numbering definition ID.
- level: An integer representing the level within the numbering definition.
Example:
p1 := document.AddParagraph("Example numbered para")
p1.Numbering(1, 0)
In this example, the paragraph p1 is assigned the numbering properties defined by numbering definition ID 1 and level 0.
func (*Paragraph) Spacing ¶
@param before: Spacing Above Paragraph in twips @param after: Spacing Below Paragraph in twips
type Relationship ¶
type Relationship struct {
XMLName xml.Name `xml:"Relationship"`
ID string `xml:"Id,attr"`
Type string `xml:"Type,attr"`
Target string `xml:"Target,attr"`
TargetMode string `xml:"TargetMode,attr,omitempty"`
}
Relationship represents a relationship between elements in an Office Open XML (OOXML) document. It includes essential information such as ID, type, target, and target mode.
func (Relationship) MarshalXML ¶
func (r Relationship) MarshalXML(e *xml.Encoder, start xml.StartElement) error
type Relationships ¶
type Relationships struct {
RelativePath string `xml:"-"`
XMLName xml.Name `xml:"Relationships"`
Xmlns string `xml:"xmlns,attr"`
Relationships []*Relationship `xml:"Relationship"`
}
Relationships represents a collection of relationships in an OOXML document. It includes the relative path, XML namespace, and a slice of Relationship instances.
type RootDoc ¶
type RootDoc struct {
Path string // Path represents the path of the document.
FileMap sync.Map // FileMap is a synchronized map for managing files related to the document.
RootRels Relationships // RootRels represents relationships at the root level.
ContentType ContentTypes
Document *Document // Document is the main document structure.
DocStyles *ctypes.Styles // Document styles
ImageCount uint
// contains filtered or unexported fields
}
RootDoc represents the root document of an Office Open XML (OOXML) document. It contains information about the document path, file map, the document structure, and relationships with other parts of the document.
func NewRootDoc ¶
func NewRootDoc() *RootDoc
NewRootDoc creates a new instance of the RootDoc structure.
func (*RootDoc) AddEmptyParagraph ¶
AddEmptyParagraph adds a new empty paragraph to the document. It returns the created Paragraph instance.
Returns:
- p: The created Paragraph instance.
func (*RootDoc) AddHeading ¶
Return a heading paragraph newly added to the end of the document. The heading paragraph will contain text and have its paragraph style determined by level. If level is 0, the style is set to Title. The style is set to Heading {level}. if level is outside the range 0-9, error will be returned
func (*RootDoc) AddPageBreak ¶
AddPageBreak adds a page break to the document by inserting a paragraph containing only a page break.
Returns:
- *Paragraph: A pointer to the newly created Paragraph object containing the page break.
Example:
document := godocx.NewDocument() para := document.AddPageBreak()
func (*RootDoc) AddParagraph ¶
AddParagraph adds a new paragraph with the specified text to the document. It returns the created Paragraph instance.
Parameters:
- text: The text to be added to the paragraph.
Returns:
- p: The created Paragraph instance.
func (*RootDoc) AddPicture ¶
AddPicture adds a new image to the document.
Example usage:
// Add a picture to the document
_, err = document.AddPicture("gopher.png", units.Inch(2.9), units.Inch(2.9))
if err != nil {
log.Fatal(err)
}
Parameters:
- path: The path of the image file to be added.
- width: The width of the image in inches.
- height: The height of the image in inches.
Returns:
- *PicMeta: Metadata about the added picture, including the Paragraph instance and Inline element.
- error: An error, if any occurred during the process.
func (*RootDoc) Close ¶
Close method is used to close the RootDoc. Currently, it does not perform any specific actions.
func (*RootDoc) GetStyleByID ¶
GetStyleByID retrieves a style from the document styles collection based on the given style ID and type.
Parameters:
- styleID: A string representing the ID of the style to retrieve.
- styleType: An stypes.StyleType indicating the type of style (e.g., paragraph, character, table).
Returns:
- *ctypes.Style: A pointer to the style matching the provided ID and type, if found; otherwise, nil.
This method searches through the document's style list to find a style with the specified ID and type. If no matching style is found or if the document styles collection is nil, it returns nil.
type Run ¶
type Run struct {
// contains filtered or unexported fields
}
func (*Run) Caps ¶
Display All Characters As Capital Letters Any lowercase characters in this text run shall be formatted for display only as their capital letter character equivalents
func (*Run) Color ¶
Sets the color of the Run.
Example:
modifiedRun := run.Color("FF0000")
Parameters:
- colorCode: A string representing the color code (e.g., "FF0000" for red).
Returns:
- *Run: The modified Run instance with the updated color.
func (*Run) DoubleStrike ¶
Specifies that the contents of this run shall be displayed with two horizontal lines through each character displayed on the line
func (*Run) SmallCaps ¶
Specifies that all small letter characters in this text run shall be formatted for display only as their capital letter character equivalents
func (*Run) SnapToGrid ¶
Use Document Grid Settings For Inter-Character Spacing
func (*Run) Strike ¶
Specifies that the contents of this run shall be displayed with a single horizontal line through the center of the line.
func (*Run) VerticalAlign ¶
func (r *Run) VerticalAlign(value stypes.VerticalAlignRun) *Run
VerticalAlign sets the vertical alignment for the run text.
Parameter: A value from the stypes.VerticalAlignRun type indicating the desired vertical alignment. One of:
VerticalAlignRunBaseline, VerticalAlignRunSuperscript, VerticalAlignRunSubscript
Returns: The modified Run instance with the updated vertical alignment.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
func (*Table) CellMargin ¶
func (t *Table) CellMargin(top *ctypes.TableWidth, left *ctypes.TableWidth, bottom *ctypes.TableWidth, right *ctypes.TableWidth) *Table
func (*Table) Grid ¶
The table grid is a definition of the set of grid columns which define all of the shared vertical edges of the table, as well as default widths for each of these grid columns. These grid column widths are then used to determine the size of the table based on the table layout algorithm used
func (*Table) Indent ¶
Indent sets the indent width for the table.
Parameters:
- indent: An integer specifying the indent width
func (*Table) Style ¶
Style sets the style for the table.
TableStyle represents the style of a table in a document. This is applicable when creating a new document. When using this style in a new document, you need to ensure that the specified style ID exists in your document's style base or is manually created through the library.
Some examples of predefined style IDs in the docx template that can be used are:
- "LightShading"
- "LightShading-Accent1"
- "LightShading-Accent2"
- "LightShading-Accent3"
- "LightShading-Accent4"
- "LightShading-Accent5"
- "LightShading-Accent6"
- "LightList"
- "LightList-Accent1"..."LightList-Accent6"
- "LightGrid"
- "LightGrid-Accent1"..."LightGrid-Accent6"
- "MediumShading"
- "MediumShading-Accent1"..."MediumShading-Accent6"
- "MediumShading2"
- "MediumShading2-Accent1"..."MediumShading2-Accent6"
- "MediumList1"
- "MediumList1-Accent1"..."MediumList1-Accent6"
- "MediumList2"
- "MediumList2-Accent1"..."MediumList2-Accent6"
- "TableGrid"
- "MediumGrid1"
- "MediumGrid1-Accent1"..."MediumGrid1-Accent6"
- "MediumGrid2"
- "MediumGrid2-Accent1"..."MediumGrid2-Accent6"
- "MediumGrid3"
- "MediumGrid3-Accent1"..."MediumGrid3-Accent6"
- "DarkList"
- "DarkList-Accent1"..."DarkList-Accent6"
- "ColorfulShading"
- "ColorfulShading-Accent1"..."ColorfulShading-Accent6"
- "ColorfulList"
- "ColorfulList-Accent1"..."ColorfulList-Accent6"
- "ColorfulGrid"
- "ColorfulGrid-Accent1"..."ColorfulGrid-Accent6"
Parameters:
- value: A string representing the style value. It should match a valid table style defined in the WordprocessingML specification.
type TitlesOfParts ¶
type TitlesOfParts struct {
Vector Vector `xml:"TitlesOfParts"`
}
TitlesOfParts represents a set of titles of parts used in extended properties.
type Variant ¶
type Variant struct {
LPStr string `xml:"http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes lpstr,omitempty"`
I4 int `xml:"http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes i4,omitempty"`
}
Variant represents a variant structure used in extended properties.