Pure go library for creating and processing Office Word (.docx), Excel (.xlsx) and Powerpoint (.pptx) documents.

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

[![Build Status](https://travis-ci.org/unidoc/unioffice.svg?branch=master)](https://travis-ci.org/unidoc/unioffice)
[![GitHub (pre-)release](https://img.shields.io/github/release/unidoc/unioffice/all.svg)](https://github.com/unidoc/unioffice/releases)
[![License: UniDoc EULA](https://img.shields.io/badge/license-UniDoc%20EULA-blue)](https://unidoc.io/eula/)
[![ApiDocs](https://img.shields.io/badge/godoc-reference-blue.svg)](https://apidocs.unidoc.io/unioffice/latest/)


![https://github.com/unidoc/unioffice/](./.github/preview.png "unioffice")

## Status ##

- Documents (docx) [Word]
	- Read/Write/Edit
	- Formatting
	- Images
	- Tables
	- Word to PDF (docx to pdf)
- 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 unioffice numbers for this
[benchmark](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/lots-of-rows)
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 github.com/unidoc/unioffice/

## License key
This software package (unioffice) is a commercial product and requires a license code to operate.

To Get a Metered License API Key in the Free Tier, sign up on https://cloud.unidoc.io

## Document Examples ##

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

## Spreadsheet Examples ##
- [Simple](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/simple) A simple sheet with a few cells
- [Named Cells](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/named-cells) Different ways of referencing rows and cells
- [Cell Number/Date/Time Formats](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/number-date-time-formats) Creating cells with various number/date/time formats
- [Line Chart](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/line-chart)/[Line Chart 3D](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/line-chart-3d) Line Charts
- [Bar Chart](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/bar-chart) Bar Charts
- [Mutiple Charts](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/multiple-charts) Multiple charts on a single sheet
- [Named Cell Ranges](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/named-ranges) Naming cell ranges
- [Merged Cells](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/merged) Merge and unmerge cells
- [Conditional Formatting](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/conditional-formatting) Conditionally formatting cells, styling, gradients, icons, data bar
- [Complex](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/complex) Multiple charts, auto filtering and conditional formatting
- [Borders](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/borders) Individual cell borders and rectangular borders around a range of cells.
- [Validation](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/validation) Data validation including combo box dropdowns.
- [Frozen Rows/Cols](https://github.com/unidoc/unioffice-examples/tree/master/spreadsheet/freeze-rows-cols) A sheet with a frozen header column and row

## Presentation Examples ##

- [Simple Text Boxes](https://github.com/unidoc/unioffice-examples/tree/master/presentation/simple) Simple text boxes and shapes
- [Images](https://github.com/unidoc/unioffice-examples/tree/master/presentation/image) Simple image insertion
- [Template](https://github.com/unidoc/unioffice-examples/tree/master/presentation/use-template/simple) 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.

    doc := 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 ###

If you are interested in contributing, please contact us.

## Development Notes

The bash script file `run_test.sh` could be used to run test and update the test result (if required). This script could receive the following parameter:
- `-s`: Save a baseline, updates all the test result.
- `-v`: Run the test in verbose mode.
- `t` or `--testname` [test name]: Run a specific test name. For example `-t AddImage` would be running a `TestAddImage` test.

To run the script in dockerized environment, use the provided `Makefile` such as:

```bash
make docker-test
```
or

```bash
make docker-update-testdata
```

## Go Version Compatibility

Officially we support three latest Go versions, but internally we would test the build with up to five latest Go versions in our CI runner.

## Support and consulting ##

Please email us at support@unidoc.io for any queries.

If you have any specific tasks that need to be done, we offer consulting in certain cases.
Please contact us with a brief summary of what you need and we will get back to you with a quote, if appropriate.

## License agreement ##

The use of this software package is governed by the end-user license agreement 
(EULA) available at: https://unidoc.io/eula/



unioffice

Golang library for reading and writing Microsoft Excel&trade; (XLSX) files.

<img width="650" src="./excelize.svg" alt="Excelize logo">


 <a href="https://github.com/xuri/excelize/actions/workflows/go.yml"><img src="https://github.com/xuri/excelize/actions/workflows/go.yml/badge.svg" alt="Build Status"></a>
 <a href="https://codecov.io/gh/qax-os/excelize"><img src="https://codecov.io/gh/qax-os/excelize/branch/master/graph/badge.svg" alt="Code Coverage"></a>
 <a href="https://goreportcard.com/report/github.com/xuri/excelize/v2"><img src="https://goreportcard.com/badge/github.com/xuri/excelize/v2" alt="Go Report Card"></a>
 <a href="https://pkg.go.dev/github.com/xuri/excelize/v2"><img src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white" alt="go.dev"></a>
 <a href="https://opensource.org/licenses/BSD-3-Clause"><img src="https://img.shields.io/badge/license-bsd-orange.svg" alt="Licenses"></a>
 <a href="https://www.paypal.com/paypalme/xuri"><img src="https://img.shields.io/badge/Donate-PayPal-green.svg" alt="Donate"></a>


# Excelize

## Introduction

Excelize is a library written in pure Go providing a set of functions that allow you to write to and read from XLAM / XLSM / XLSX / XLTM / XLTX files. Supports reading and writing spreadsheet documents generated by Microsoft Excel&trade; 2007 and later. Supports complex components by high compatibility, and provided streaming API for generating or reading data from a worksheet with huge amounts of data. This library needs Go version 1.18 or later. There are some [incompatible changes](https://github.com/golang/go/issues/61881) in the Go 1.21.0, the Excelize library can not working with that version normally, if you are using the Go 1.21.x, please upgrade to the Go 1.21.1 and later version. The full docs can be seen using go's built-in documentation tool, or online at [go.dev](https://pkg.go.dev/github.com/xuri/excelize/v2) and [docs reference](https://xuri.me/excelize/).

## Basic Usage

### Installation

```bash
go get github.com/xuri/excelize
```

- If your packages are managed using [Go Modules](https://go.dev/blog/using-go-modules), please install with following command.

```bash
go get github.com/xuri/excelize/v2
```

### Create spreadsheet

Here is a minimal example usage that will create spreadsheet file.

```go
package main

import (
 "fmt"

 "github.com/xuri/excelize/v2"
)

func main() {
 f := excelize.NewFile()
 defer func() {
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 // Create a new sheet.
 index, err := f.NewSheet("Sheet2")
 if err != nil {
 fmt.Println(err)
 return
 }
 // Set value of a cell.
 f.SetCellValue("Sheet2", "A2", "Hello world.")
 f.SetCellValue("Sheet1", "B2", 100)
 // Set active sheet of the workbook.
 f.SetActiveSheet(index)
 // Save spreadsheet by the given path.
 if err := f.SaveAs("Book1.xlsx"); err != nil {
 fmt.Println(err)
 }
}
```

### Reading spreadsheet

The following constitutes the bare to read a spreadsheet document.

```go
package main

import (
 "fmt"

 "github.com/xuri/excelize/v2"
)

func main() {
 f, err := excelize.OpenFile("Book1.xlsx")
 if err != nil {
 fmt.Println(err)
 return
 }
 defer func() {
 // Close the spreadsheet.
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 // Get value from cell by given worksheet name and cell reference.
 cell, err := f.GetCellValue("Sheet1", "B2")
 if err != nil {
 fmt.Println(err)
 return
 }
 fmt.Println(cell)
 // Get all the rows in the Sheet1.
 rows, err := f.GetRows("Sheet1")
 if err != nil {
 fmt.Println(err)
 return
 }
 for _, row := range rows {
 for _, colCell := range row {
 fmt.Print(colCell, "\t")
 }
 fmt.Println()
 }
}
```

### Add chart to spreadsheet file

With Excelize chart generation and management is as easy as a few lines of code. You can build charts based on data in your worksheet or generate charts without any data in your worksheet at all.

<img width="650" src="./test/images/chart.png" alt="Excelize">

```go
package main

import (
 "fmt"

 "github.com/xuri/excelize/v2"
)

func main() {
 f := excelize.NewFile()
 defer func() {
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 for idx, row := range [][]interface{}{
 {nil, "Apple", "Orange", "Pear"}, {"Small", 2, 3, 3},
 {"Normal", 5, 2, 4}, {"Large", 6, 7, 8},
 } {
 cell, err := excelize.CoordinatesToCellName(1, idx+1)
 if err != nil {
 fmt.Println(err)
 return
 }
 f.SetSheetRow("Sheet1", cell, &row)
 }
 if err := f.AddChart("Sheet1", "E1", &excelize.Chart{
 Type: excelize.Col3DClustered,
 Series: []excelize.ChartSeries{
 {
 Name: "Sheet1!$A$2",
 Categories: "Sheet1!$B$1:$D$1",
 Values: "Sheet1!$B$2:$D$2",
 },
 {
 Name: "Sheet1!$A$3",
 Categories: "Sheet1!$B$1:$D$1",
 Values: "Sheet1!$B$3:$D$3",
 },
 {
 Name: "Sheet1!$A$4",
 Categories: "Sheet1!$B$1:$D$1",
 Values: "Sheet1!$B$4:$D$4",
 }},
 Title: []excelize.RichTextRun{
 {
 Text: "Fruit 3D Clustered Column Chart",
 },
 },
 }); err != nil {
 fmt.Println(err)
 return
 }
 // Save spreadsheet by the given path.
 if err := f.SaveAs("Book1.xlsx"); err != nil {
 fmt.Println(err)
 }
}
```

### Add picture to spreadsheet file

```go
package main

import (
 "fmt"
 _ "image/gif"
 _ "image/jpeg"
 _ "image/png"

 "github.com/xuri/excelize/v2"
)

func main() {
 f, err := excelize.OpenFile("Book1.xlsx")
 if err != nil {
 fmt.Println(err)
 return
 }
 defer func() {
 // Close the spreadsheet.
 if err := f.Close(); err != nil {
 fmt.Println(err)
 }
 }()
 // Insert a picture.
 if err := f.AddPicture("Sheet1", "A2", "image.png", nil); err != nil {
 fmt.Println(err)
 }
 // Insert a picture to worksheet with scaling.
 if err := f.AddPicture("Sheet1", "D2", "image.jpg",
 &excelize.GraphicOptions{ScaleX: 0.5, ScaleY: 0.5}); err != nil {
 fmt.Println(err)
 }
 // Insert a picture offset in the cell with printing support.
 enable, disable := true, false
 if err := f.AddPicture("Sheet1", "H2", "image.gif",
 &excelize.GraphicOptions{
 PrintObject: &enable,
 LockAspectRatio: false,
 OffsetX: 15,
 OffsetY: 10,
 Locked: &disable,
 }); err != nil {
 fmt.Println(err)
 }
 // Save the spreadsheet with the origin path.
 if err = f.Save(); err != nil {
 fmt.Println(err)
 }
}
```

## Contributing

Contributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature or change. XML is compliant with [part 1 of the 5th edition of the ECMA-376 Standard for Office Open XML](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/).

## Licenses

This program is under the terms of the BSD 3-Clause License. See [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause).

The Excel logo is a trademark of [Microsoft Corporation](https://aka.ms/trademarks-usage). This artwork is an adaptation.

gopher.{ai,svg,png} was created by [Takuya Ueda](https://twitter.com/tenntenn). Licensed under the [Creative Commons 3.0 Attributions license](http://creativecommons.org/licenses/by/3.0/).

excelize

Excel binding to struct written in Go.(Only supports Go1.18+)

# exl
Excel binding to struct written in Go.(Only supports Go1.18+)

[![CircleCI](https://circleci.com/gh/go-the-way/exl/tree/main.svg?style=shield)](https://circleci.com/gh/go-the-way/exl/tree/main)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/go-the-way/exl)
[![codecov](https://codecov.io/gh/go-the-way/exl/branch/main/graph/badge.svg?token=8MAR3J959H)](https://codecov.io/gh/go-the-way/exl)
[![Go Report Card](https://goreportcard.com/badge/github.com/go-the-way/exl)](https://goreportcard.com/report/github.com/go-the-way/exl)
[![GoDoc](https://pkg.go.dev/badge/github.com/go-the-way/exl?status.svg)](https://pkg.go.dev/github.com/go-the-way/exl?tab=doc)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#microsoft-excel)

## usage

### Read Excel

```go
package main

import (
	"fmt"
	
	"github.com/go-the-way/exl"
)

type ReadExcel struct {
	ID   int    `excel:"ID"`
	Name string `excel:"Name"`
}

func (*ReadExcel) ReadConfigure(rc *exl.ReadConfig) {}

func main() {
	if models, err := exl.ReadFile[*ReadExcel]("/to/path.xlsx"); err != nil {
		fmt.Println("read excel err:" + err.Error())
	} else {
		fmt.Printf("read excel num: %d\n", len(models))
	}
}
```

### Write Excel

```go
package main

import (
	"fmt"
	
	"github.com/go-the-way/exl"
)

type WriteExcel struct {
	ID   int    `excel:"ID"`
	Name string `excel:"Name"`
}

func (m *WriteExcel) WriteConfigure(wc *exl.WriteConfig) {}

func main() {
	if err := exl.Write("/to/path.xlsx", []*WriteExcel{{100, "apple"}, {200, "pear"}}); err != nil {
		fmt.Println("write excel err:" + err.Error())
	} else {
		fmt.Println("write excel done")
	}
}
```

## Writer

```go
package main

import (
	"fmt"

	"github.com/go-the-way/exl"
)

func main() {
	w := exl.NewWriter()
	if err := w.Write("int", []int{1, 2}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("float", []float64{1.1, 2.2}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("string", []string{"hello", "world"}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("map", []map[string]string{{"id":"1000","name":"hello"},{"id":"2000","name":"world"}}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("structWithField", []struct{ID int}{{1000},{2000}}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("structWithTag", []struct{ID int `excel:"编号"`}{{1000},{2000}}); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Write("structWithTagAndIgnore", []struct{
		ID int `excel:"编号"`
		Extra int `excel:"-"`
		Name string `excel:"名称"`
	}{{1000,0,"Coco"},{2000,0,"Apple"}}); err != nil {
		fmt.Println(err)
		return
	} 
	if err := w.SaveTo("dist.xlsx"); err != nil {
		fmt.Println(err)
		return
	}
}
```


The Best Go Libraries For Microsoft Office (3)

unioffice

excelize

exl