office

package module

v0.0.0-...-9dee689 Latest Latest Go to latest Published: Jan 18, 2024 License: AGPL-3.0 Imports: 8 Imported by: 0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/devnw/ooxml

Links

Open Source Insights

README ¶

ooxml is a library for creation of Office Open XML documents (.docx, .xlsx and .pptx)

Status

Documents (docx) [Word]
- Read/Write/Edit
- Formatting
- Images
- Tables
Spreadsheets (xlsx) [Excel]
- Read/Write/Edit
- Cell formatting including conditional formatting
- Cell validation (drop down combobox, rules, etc.)
- Retrieve cell values as formatted by Excel (e.g. retrieve a date or number as displayed in Excel)
- Formula Evaluation (100+ functions supported currently, more will be added as required)
- Embedded Images
- All chart types
PowerPoint (pptx) [PowerPoint]
- Creation from templates
- Textboxes/shapes

Performance

There has been a great deal of interest in performance numbers for spreadsheet creation/reading lately, so here are office numbers for this benchmark which creates a sheet with 30k rows, each with 100 columns.

creating 30000 rows * 100 cells took 3.92506863s
saving took 89ns
reading took 9.522383048s

Creation is fairly fast, saving is very quick due to no reflection usage, and reading is a bit slower. The downside is that the binary is large (33MB) as it contains generated structs, serialization and deserialization code for all of DOCX/XLSX/PPTX.

Usage

go get -u go.devnw.com/ooxml

Document Examples

Simple Text Formatting Text font colors, sizes, highlighting, etc.
Auto Generated Table of Contents Creating document headings with an auto generated TOC based off of the headingds
Floating Image Placing an image somewhere on a page, absolutely positioned with different text wrapping.
Header & Footer Creating headers and footers including page numbering.
Multiple Headers & Footers Using different headers and footers depending on document section.
Inline Tables Adding an table with and without borders.
Using Existing Word Document as a Template Opening a document as a template to re-use the styles created in the document.
Filling out Form Fields Opening a document with embedded form fields, filling out the fields and saving the result as a new filled form.
Editing an existing document Open an existing document and replace/remove text without modifying formatting.

Spreadsheet Examples

Simple A simple sheet with a few cells
Named Cells Different ways of referencing rows and cells
Cell Number/Date/Time Formats Creating cells with various number/date/time formats
Line Chart/Line Chart 3D Line Charts
Bar Chart Bar Charts
Mutiple Charts Multiple charts on a single sheet
Named Cell Ranges Naming cell ranges
Merged Cells Merge and unmerge cells
Conditional Formatting Conditionally formatting cells, styling, gradients, icons, data bar
Complex Multiple charts, auto filtering and conditional formatting
Borders Individual cell borders and rectangular borders around a range of cells.
Validation Data validation including combo box dropdowns.
Frozen Rows/Cols A sheet with a frozen header column and row

Presentation Examples

Simple Text Boxes Simple text boxes and shapes
Images Simple image insertion
Template Creating a presentation from a template

Raw Types

The OOXML specification is large and creating a friendly API to cover the entire specification is a very time consuming endeavor. This library attempts to provide an easy to use API for common use cases in creating OOXML documents while allowing users to fall back to raw document manipulation should the library's API not cover a specific use case.

The raw XML based types reside in the schema/ directory. These types are accessible from the wrapper types via a X() method that returns the raw type.

For example, the library currently doesn't have an API for setting a document background color. However it's easy to do manually via editing the CT_Background element of the document.

dox := document.New()
doc.X().Background = wordprocessingml.NewCT_Background()
doc.X().Background.ColorAttr = &wordprocessingml.ST_HexColor{}
doc.X().Background.ColorAttr.ST_HexColorRGB = color.RGB(50, 50, 50).AsRGBString()

Documentation ¶

Overview ¶

Example (Document) ¶

package main

import (
	"go.devnw.com/ooxml/document"
)

func main() {
	// see the go.devnw.com/ooxml/document documentation or _examples/document
	// for more examples
	doc := document.New()
	doc.AddParagraph().AddRun().AddText("Hello World!")
	doc.SaveToFile("document.docx")
}

Output:

Example (Spreadsheeet) ¶

package main

import (
	"go.devnw.com/ooxml/spreadsheet"
)

func main() {
	// see the go.devnw.com/ooxml/spreadsheet documentation or _examples/spreadsheet
	// for more examples
	ss := spreadsheet.New()
	sheet := ss.AddSheet()
	sheet.AddRow().AddCell().SetString("Hello")
	sheet.Cell("B1").SetString("World!")
	ss.SaveToFile("workbook.xlsx")
}

Output:

Index ¶

Constants
Variables
func AbsoluteFilename(dt DocType, typ string, index int) string
func AbsoluteImageFilename(dt DocType, index int, fileExtension string) string
func AddPreserveSpaceAttr(se *xml.StartElement, s string)
func Bool(v bool) *bool
func DisableLogging()
func Float32(v float32) *float32
func Float64(v float64) *float64
func Int32(v int32) *int32
func Int64(v int64) *int64
func Int8(v int8) *int8
func NeedsSpacePreserve(s string) bool
func RegisterConstructor(ns, name string, fn interface{})
func RelativeFilename(dt DocType, relToTyp, typ string, index int) string
func RelativeImageFilename(dt DocType, relToTyp, typ string, index int, fileExtension string) string
func String(v string) *string
func Stringf(f string, args ...interface{}) *string
func Uint16(v uint16) *uint16
func Uint32(v uint32) *uint32
func Uint64(v uint64) *uint64
func Uint8(v uint8) *uint8
type Any
- func CreateElement(start xml.StartElement) (Any, error)
type DocType
type XSDAny
- func (x *XSDAny) MarshalXML(e *xml.Encoder, start xml.StartElement) error
- func (x *XSDAny) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

Constants ¶

View Source

const (
	ContentTypesFilename = "[Content_Types].xml"
	BaseRelsFilename     = "_rels/.rels"
)

Common filenames used in zip packages.

View Source

const (
	// Common strict
	OfficeDocumentTypeStrict     = "http://purl.oclc.org/ooxml/officeDocument/relationships/officeDocument"
	StylesTypeStrict             = "http://purl.oclc.org/ooxml/officeDocument/relationships/styles"
	ThemeTypeStrict              = "http://purl.oclc.org/ooxml/officeDocument/relationships/theme"
	SettingsTypeStrict           = "http://purl.oclc.org/ooxml/officeDocument/relationships/settings"
	ImageTypeStrict              = "http://purl.oclc.org/ooxml/officeDocument/relationships/image"
	CommentsTypeStrict           = "http://purl.oclc.org/ooxml/officeDocument/relationships/comments"
	ThumbnailTypeStrict          = "http://purl.oclc.org/ooxml/officeDocument/relationships/metadata/thumbnail"
	DrawingTypeStrict            = "http://purl.oclc.org/ooxml/officeDocument/relationships/drawing"
	ChartTypeStrict              = "http://purl.oclc.org/ooxml/officeDocument/relationships/chart"
	ExtendedPropertiesTypeStrict = "http://purl.oclc.org/ooxml/officeDocument/relationships/extendedProperties"
	CustomXMLTypeStrict          = "http://purl.oclc.org/ooxml/officeDocument/relationships/customXml"

	// SML strict
	WorksheetTypeStrict     = "http://purl.oclc.org/ooxml/officeDocument/relationships/worksheet"
	SharedStringsTypeStrict = "http://purl.oclc.org/ooxml/officeDocument/relationships/sharedStrings"
	// Deprecated: Renamed to SharedStringsTypeStrict, will be removed in next major version.
	SharedStingsTypeStrict = SharedStringsTypeStrict
	TableTypeStrict        = "http://purl.oclc.org/ooxml/officeDocument/relationships/table"

	// WML strict
	HeaderTypeStrict      = "http://purl.oclc.org/ooxml/officeDocument/relationships/header"
	FooterTypeStrict      = "http://purl.oclc.org/ooxml/officeDocument/relationships/footer"
	NumberingTypeStrict   = "http://purl.oclc.org/ooxml/officeDocument/relationships/numbering"
	FontTableTypeStrict   = "http://purl.oclc.org/ooxml/officeDocument/relationships/fontTable"
	WebSettingsTypeStrict = "http://purl.oclc.org/ooxml/officeDocument/relationships/webSettings"
	FootNotesTypeStrict   = "http://purl.oclc.org/ooxml/officeDocument/relationships/footnotes"
	EndNotesTypeStrict    = "http://purl.oclc.org/ooxml/officeDocument/relationships/endnotes"

	// PML strict
	SlideTypeStrict = "http://purl.oclc.org/ooxml/officeDocument/relationships/slide"

	// VML strict
	VMLDrawingTypeStrict = "http://purl.oclc.org/ooxml/officeDocument/relationships/vmlDrawing"

	// Common
	OfficeDocumentType     = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument"
	StylesType             = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles"
	ThemeType              = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
	ThemeContentType       = "application/vnd.openxmlformats-officedocument.theme+xml"
	SettingsType           = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings"
	ImageType              = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
	CommentsType           = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
	CommentsContentType    = "application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml"
	ThumbnailType          = "http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail"
	DrawingType            = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing"
	DrawingContentType     = "application/vnd.openxmlformats-officedocument.drawing+xml"
	ChartType              = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart"
	ChartContentType       = "application/vnd.openxmlformats-officedocument.drawingml.chart+xml"
	HyperLinkType          = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
	ExtendedPropertiesType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties"
	CorePropertiesType     = "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties"
	CustomPropertiesType   = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties"
	CustomXMLType          = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customXml"
	TableStylesType        = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/tableStyles"
	ViewPropertiesType     = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/viewProps"

	// SML
	WorksheetType        = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
	WorksheetContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"
	SharedStringsType    = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings"
	// Deprecated: Renamed to SharedStringsType, will be removed in next major version.
	SharedStingsType         = SharedStringsType
	SharedStringsContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml"
	SMLStyleSheetContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"
	TableType                = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table"
	TableContentType         = "application/vnd.openxmlformats-officedocument.spreadsheetml.table+xml"

	// WML
	HeaderType      = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header"
	FooterType      = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer"
	NumberingType   = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering"
	FontTableType   = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable"
	WebSettingsType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings"
	FootNotesType   = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes"
	EndNotesType    = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes"

	// PML
	SlideType                  = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide"
	SlideContentType           = "application/vnd.openxmlformats-officedocument.presentationml.slide+xml"
	SlideMasterType            = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster"
	SlideMasterContentType     = "application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml"
	SlideLayoutType            = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout"
	SlideLayoutContentType     = "application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml"
	PresentationPropertiesType = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/presProps"
	HandoutMasterType          = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/handoutMaster"
	NotesMasterType            = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesMaster"

	// VML
	VMLDrawingType        = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing"
	VMLDrawingContentType = "application/vnd.openxmlformats-officedocument.vmlDrawing"
)

Consts for content types used throughout the package

View Source

const MinGoVersion = requires_go_18

MinGoVersion is used to cause a compile time error if office is compiled with an older version of go. Specifically it requires a feature in go 1.8 regarding collecting all attributes from arbitrary xml used in decode office.XSDAny.

Variables ¶

View Source

var Log = log.Printf

Log is used to log content from within the library. The intent is to use logging sparingly, preferring to return an error. At the very least this allows redirecting logs to somewhere more appropriate than stdout.

Functions ¶

func AbsoluteFilename ¶

func AbsoluteFilename(dt DocType, typ string, index int) string

AbsoluteFilename returns the full path to a file from the root of the zip container. Index is used in some cases for files which there may be more than one of (e.g. worksheets/drawings/charts)

func AbsoluteImageFilename ¶

func AbsoluteImageFilename(dt DocType, index int, fileExtension string) string

AbsoluteImageFilename returns the full path to an image from the root of the zip container.

func AddPreserveSpaceAttr ¶

func AddPreserveSpaceAttr(se *xml.StartElement, s string)

AddPreserveSpaceAttr adds an xml:space="preserve" attribute to a start element if it is required for the string s.

func Bool ¶

func Bool(v bool) *bool

Bool returns a copy of v as a pointer.

func DisableLogging ¶

func DisableLogging()

DisableLogging sets the Log function to a no-op so that any log messages are silently discarded.

func Float32 ¶

func Float32(v float32) *float32

Float32 returns a copy of v as a pointer.

func Float64 ¶

func Float64(v float64) *float64

Float64 returns a copy of v as a pointer.

func Int32 ¶

func Int32(v int32) *int32

Int32 returns a copy of v as a pointer.

func Int64 ¶

func Int64(v int64) *int64

Int64 returns a copy of v as a pointer.

func Int8 ¶

func Int8(v int8) *int8

Int8 returns a copy of v as a pointer.

func NeedsSpacePreserve ¶

func NeedsSpacePreserve(s string) bool

NeedsSpacePreserve returns true if the string has leading or trailing space.

func RegisterConstructor ¶

func RegisterConstructor(ns, name string, fn interface{})

RegisterConstructor registers a constructor function used for unmarshaling xsd:any elements.

func RelativeFilename ¶

func RelativeFilename(dt DocType, relToTyp, typ string, index int) string

RelativeFilename returns a filename relative to the source file referenced from a relationships file. Index is used in some cases for files which there may be more than one of (e.g. worksheets/drawings/charts)

func RelativeImageFilename ¶

func RelativeImageFilename(dt DocType, relToTyp, typ string, index int, fileExtension string) string

RelativeImageFilename returns an image filename relative to the source file referenced from a relationships file. It is identical to RelativeFilename but is used particularly for images in order to handle different image formats.

func String ¶

func String(v string) *string

String returns a copy of v as a pointer.

func Stringf ¶

func Stringf(f string, args ...interface{}) *string

Stringf formats according to a format specifier and returns a pointer to the resulting string.

func Uint16 ¶

func Uint16(v uint16) *uint16

Uint16 returns a copy of v as a pointer.

func Uint32 ¶

func Uint32(v uint32) *uint32

Uint32 returns a copy of v as a pointer.

func Uint64 ¶

func Uint64(v uint64) *uint64

Uint64 returns a copy of v as a pointer.

func Uint8 ¶

func Uint8(v uint8) *uint8

Uint8 returns a copy of v as a pointer.

Types ¶

type Any ¶

type Any interface {
	MarshalXML(e *xml.Encoder, start xml.StartElement) error
	UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
}

Any is the interface used for marshaling/unmarshaling xsd:any

func CreateElement ¶

func CreateElement(start xml.StartElement) (Any, error)

CreateElement creates an element with the given namespace and name. It is used to unmarshal some xsd:any elements to the appropriate concrete type.

type DocType ¶

type DocType byte

DocType represents one of the three document types supported (docx/xlsx/pptx)

const (
	Unknown DocType = iota
	DocTypeSpreadsheet
	DocTypeDocument
	DocTypePresentation
)

Document Type constants

type XSDAny ¶

type XSDAny struct {
	XMLName xml.Name
	Attrs   []xml.Attr
	Data    []byte
	Nodes   []*XSDAny
}

XSDAny is used to marshal/unmarshal xsd:any types in the OOXML schema.

func (*XSDAny) MarshalXML ¶

func (x *XSDAny) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML implements the xml.Marshaler interface.

func (*XSDAny) UnmarshalXML ¶

func (x *XSDAny) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML implements the xml.Unmarshaler interface.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
algo
chart
cmd
catdoc
csv2xlsx
docx2md
test-open-write
unprotect-xlsx
xlsx2csv
color
common
license
document
drawing
examples
document/doc-custom-properties
document/doc-properties
document/edit-document
document/endnotes_footnotes
document/fill-out-form
document/header-footer
document/header-footer-multiple
document/hyperlink
document/image
document/line-spacing
document/mail-merge
document/page-numbers
document/paragraphs_in_table
document/pdf-export-ole
document/set-strict
document/simple
document/tables
document/toc
document/toc-generation-ole
document/use-template
presentation/complex
presentation/image
presentation/simple
presentation/use-template
presentation/use-template-with-image
spreadsheet/bar-chart
spreadsheet/borders
spreadsheet/bubble-chart
spreadsheet/cells-with-empty
spreadsheet/comments
spreadsheet/complex
spreadsheet/conditional-formatting
spreadsheet/flatten
spreadsheet/formula
spreadsheet/formula-evaluation
spreadsheet/freeze-rows-cols
spreadsheet/image
spreadsheet/insert-rows
spreadsheet/line-chart
spreadsheet/line-chart-3d
spreadsheet/line-chart-no-data
spreadsheet/lots-of-rows
spreadsheet/merged
spreadsheet/multiple-charts
spreadsheet/named-cells
spreadsheet/named-ranges
spreadsheet/number-date-time-formats
spreadsheet/pie-chart
spreadsheet/radar-chart
spreadsheet/remove-column
spreadsheet/rich-text
spreadsheet/rotated-cells
spreadsheet/shared-formula
spreadsheet/simple
spreadsheet/sort-filter
spreadsheet/surface-chart
spreadsheet/validation
spreadsheet/wrapped-text
internal
mergesort
wildcard
measurement
presentation
schema
purl.org/dc/elements
purl.org/dc/terms
soo/dml
soo/dml/chart
soo/dml/chartDrawing
soo/dml/diagram
soo/dml/lockedCanvas
soo/dml/picture
soo/dml/spreadsheetDrawing
soo/ofc/custom_properties
soo/ofc/docPropsVTypes
soo/ofc/extended_properties
soo/ofc/math
soo/ofc/relationships
soo/ofc/sharedTypes
soo/pkg/content_types
soo/pkg/metadata/core_properties
soo/pkg/relationships
soo/pml
soo/schemaLibrary
soo/sml
soo/wml
urn/schemas_microsoft_com/office/excel
urn/schemas_microsoft_com/office/powerpoint
urn/schemas_microsoft_com/office/word
urn/schemas_microsoft_com/vml
spreadsheet
format
formula The unit tests for this package are unique in that we can take advantage of "cached" formula results that Excel/LibreOffice write to the sheet.	The unit tests for this package are unique in that we can take advantage of "cached" formula results that Excel/LibreOffice write to the sheet.
reference
update
testhelper
vmldrawing
zippkg

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL