goffice

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 14, 2025 License: MIT Imports: 8 Imported by: 0

README

goffice is a library for creation of Office Open XML documents (.docx, .xlsx and .pptx). It's goal is to be the most compatible and highest performance Go library for creation and editing of docx/xlsx/pptx files.

Requires go1.8+, builds are tested with 1.8, 1.9 and tip.

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

Installation

go get github.com/dhx007/goffice@latest

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

Package goffice provides creation, reading, and writing of ECMA 376 Office Open XML documents, spreadsheets and presentations. It is still early in development, but is progressing quickly. This library takes a slightly different approach from others, in that it starts by trying to support all of the ECMA-376 standard when marshaling/unmarshaling XML documents. From there it adds wrappers around the ECMA-376 derived types that provide a more convenient interface.

The raw XML based types reside in the `schema/“ directory. These types are always accessible from the wrapper types via a `X() method that returns the raw type. Except for the base documents (document.Document, spreadsheet.Workbook and presentation.Presentation), the other wrapper types are value types with non-pointer methods. They exist solely to modify and return data from one or more XML types.

The packages of interest are github.com/dhx007/goffice/document, unidoc/goffice/spreadsheet and github.com/dhx007/goffice/presentation.

Example (Document) 
package main

import (
	"github.com/dhx007/goffice/document"
)

func main() {
	// see the github.com/dhx007/goffice/document documentation or _examples/document
	// for more examples
	doc := document.New()
	doc.AddParagraph().AddRun().AddText("Hello World!")
	doc.SaveToFile("document.docx")
}
Example (Spreadsheeet) 
package main

import (
	"github.com/dhx007/goffice/spreadsheet"
)

func main() {
	// see the github.com/dhx007/goffice/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")
}

Index

Examples

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 goffice 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 goffice.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
_examples
document/doc-custom-properties command
document/doc-properties command
document/edit-document command
document/endnotes_footnotes command
document/fill-out-form command
document/header-footer command
document/header-footer-multiple command
document/hyperlink command
document/image command
document/line-spacing command
document/mail-merge command
document/page-numbers command
document/paragraphs_in_table command
document/pdf-export-ole command
document/set-strict command
document/simple command
document/tables command
document/toc command
document/toc-generation-ole command
document/use-template command
presentation/complex command
presentation/image command
presentation/simple command
presentation/use-template command
presentation/use-template-with-image command
spreadsheet/bar-chart command
spreadsheet/borders command
spreadsheet/bubble-chart command
spreadsheet/cells-with-empty command
spreadsheet/comments command
spreadsheet/complex command
spreadsheet/conditional-formatting command
spreadsheet/flatten command
spreadsheet/formula command
spreadsheet/formula-evaluation command
spreadsheet/freeze-rows-cols command
spreadsheet/image command
spreadsheet/insert-rows command
spreadsheet/line-chart command
spreadsheet/line-chart-3d command
spreadsheet/line-chart-no-data command
spreadsheet/lots-of-rows command
spreadsheet/merged command
spreadsheet/multiple-charts command
spreadsheet/named-cells command
spreadsheet/named-ranges command
spreadsheet/number-date-time-formats command
spreadsheet/pie-chart command
spreadsheet/radar-chart command
spreadsheet/remove-column command
spreadsheet/rich-text command
spreadsheet/rotated-cells command
spreadsheet/shared-formula command
spreadsheet/simple command
spreadsheet/sort-filter command
spreadsheet/surface-chart command
spreadsheet/validation command
spreadsheet/wrapped-text command
cmd
catdoc command
csv2xlsx command
docx2md command
test-open-write command
unprotect-xlsx command
xlsx2csv command
Package color provides color handling structures and functions for use across all of the document types.
 Package color provides color handling structures and functions for use across all of the document types.
Package common contains wrapper types and utilities common to all of the OOXML document formats.
 Package common contains wrapper types and utilities common to all of the OOXML document formats.
Package document provides creation, reading, and writing of ECMA 376 Open Office XML documents.
 Package document provides creation, reading, and writing of ECMA 376 Open Office XML documents.
internal
mergesort
Package mergesort provides an implementation for merge sort sorting algorithm
 Package mergesort provides an implementation for merge sort sorting algorithm
wildcard
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
format
Package format provides support for parsing and evaluating spreadsheetml/Excel number formats.
 Package format provides support for parsing and evaluating spreadsheetml/Excel number formats.
formula
Package formula provides formula parsing and evaluation.
 Package formula provides formula parsing and evaluation.
reference
update
Package update contains definitions needed for updating references after removing rows/columns.
 Package update contains definitions needed for updating references after removing rows/columns.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.