gooxml

package module
v1.0.3 Latest Latest
Warning

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

Go to latest
Published: Jul 14, 2021 License: AGPL-3.0 Imports: 21 Imported by: 0

README

gooxml 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

Performance

There has been a great deal of interest in performance numbers for spreadsheet creation/reading lately, so here are gooxml 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.

Installation

go get git.yingcaibx.com/root/gooxml/
go build -i git.yingcaibx.com/root/gooxml/...

Document Examples

Spreadsheet Examples

Presentation Examples

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()

Contribution guidelines

All contributors are must sign a contributor license agreement before their code will be reviewed and merged.

Licensing

This library is offered under a dual license. It is freely available for use under the terms of AGPLv3. If you would like to use this library for a closed source project, please contact sales@api/util.

There are no differences in functionality between the open source and commercial versions. You are encouraged to use the open source version to evaluate the library before purchasing a commercial license.

Documentation

Overview

Package gooxml 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 git.yingcaibx.com/root/gooxml/document, baliance/gooxml/spreadsheet and git.yingcaibx.com/root/gooxml/presentation.

Example (Document)
package main

import (
	"git.yingcaibx.com/root/gooxml/document"
)

func main() {
	// see the git.yingcaibx.com/root/gooxml/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 (
	"git.yingcaibx.com/root/gooxml/spreadsheet"
)

func main() {
	// see the git.yingcaibx.com/root/gooxml/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

Examples

Constants

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

Common filenames used in zip packages.

View Source
const (
	// 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"

	// SML
	WorksheetType            = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
	WorksheetContentType     = "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"
	SharedStingsType         = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings"
	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"
	ViewPropertiesType       = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/viewProps"
	TableStylesType          = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/tableStyles"

	// 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"

	// 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 gooxml 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 gooxml.XSDAny.

View Source
const OpenSourceLicense = `` /* 271-byte string literal not displayed */

OpenSourceLicense is the AGPL open source license. It is installed by default if no license has previously been installed.

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.

View Source
var ReleaseDate = time.Date(2018, 9, 14, 0, 0, 0, 0, time.UTC)

ReleaseDate is the release date of the source code for licensing purposes.

View Source
var ReleaseVersion = "v0.8000"

Release is the last release version of the software.

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 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 InstallLicense

func InstallLicense(s string) error

InstallLicense installs a license, returning an error if the license is invalid or expired. Expiration checks the ReleaseDate variable in version.go.

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 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 License

type License struct {
	Name        string
	Signature   string `json:",omitempty"`
	Expiration  time.Time
	LicenseType LicenseType
}

License holds the gooxml license information.

func GetLicense

func GetLicense() License

GetLicense returns the current license. This can be used by commercial customers to assist in ensuring that their license hasn't expired.

func (License) Encoded

func (l License) Encoded() string

Encoded returns a base64 encoded version of the license for use with InstallLicense.

func (*License) Sign

func (l *License) Sign(privKey *rsa.PrivateKey) error

Sign signs a license with a private key, setting the license's signature value

func (License) String

func (l License) String() string

func (License) Verify

func (l License) Verify(pubKey *rsa.PublicKey) error

Verify verifies a license by checking the license content and signature against a public key.

type LicenseType

type LicenseType byte

LicenseType is the type of license

const (
	LicenseTypeInvalid LicenseType = iota
	LicenseTypeAGPL
	LicenseTypeCommercial
)

LicenseType constants

func (LicenseType) String

func (i LicenseType) String() string

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.

Directories

Path Synopsis
cmd
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.
schema
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.

Jump to

Keyboard shortcuts

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