README.md

   1 <p align="center"><img width="650" src="./excelize.svg" alt="Excelize logo"></p>
   2
   3 <p align="center">
   4     <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>
   5     <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>
   6     <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>
   7     <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>
   8     <a href="https://opensource.org/licenses/BSD-3-Clause"><img src="https://img.shields.io/badge/license-bsd-orange.svg" alt="Licenses"></a>
   9     <a href="https://www.paypal.com/paypalme/xuri"><img src="https://img.shields.io/badge/Donate-PayPal-green.svg" alt="Donate"></a>
  10 </p>
  11
  12 # Excelize
  13
  14 ## Introduction
  15
  16 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/).
  17
  18 ## Basic Usage
  19
  20 ### Installation
  21
  22 ```bash
  23 go get github.com/xuri/excelize
  24 ```
  25
  26 - If your packages are managed using [Go Modules](https://go.dev/blog/using-go-modules), please install with following command.
  27
  28 ```bash
  29 go get github.com/xuri/excelize/v2
  30 ```
  31
  32 ### Create spreadsheet
  33
  34 Here is a minimal example usage that will create spreadsheet file.
  35
  36 ```go
  37 package main
  38
  39 import (
  40     "fmt"
  41
  42     "github.com/xuri/excelize/v2"
  43 )
  44
  45 func main() {
  46     f := excelize.NewFile()
  47     defer func() {
  48         if err := f.Close(); err != nil {
  49             fmt.Println(err)
  50         }
  51     }()
  52     // Create a new sheet.
  53     index, err := f.NewSheet("Sheet2")
  54     if err != nil {
  55         fmt.Println(err)
  56         return
  57     }
  58     // Set value of a cell.
  59     f.SetCellValue("Sheet2", "A2", "Hello world.")
  60     f.SetCellValue("Sheet1", "B2", 100)
  61     // Set active sheet of the workbook.
  62     f.SetActiveSheet(index)
  63     // Save spreadsheet by the given path.
  64     if err := f.SaveAs("Book1.xlsx"); err != nil {
  65         fmt.Println(err)
  66     }
  67 }
  68 ```
  69
  70 ### Reading spreadsheet
  71
  72 The following constitutes the bare to read a spreadsheet document.
  73
  74 ```go
  75 package main
  76
  77 import (
  78     "fmt"
  79
  80     "github.com/xuri/excelize/v2"
  81 )
  82
  83 func main() {
  84     f, err := excelize.OpenFile("Book1.xlsx")
  85     if err != nil {
  86         fmt.Println(err)
  87         return
  88     }
  89     defer func() {
  90         // Close the spreadsheet.
  91         if err := f.Close(); err != nil {
  92             fmt.Println(err)
  93         }
  94     }()
  95     // Get value from cell by given worksheet name and cell reference.
  96     cell, err := f.GetCellValue("Sheet1", "B2")
  97     if err != nil {
  98         fmt.Println(err)
  99         return
 100     }
 101     fmt.Println(cell)
 102     // Get all the rows in the Sheet1.
 103     rows, err := f.GetRows("Sheet1")
 104     if err != nil {
 105         fmt.Println(err)
 106         return
 107     }
 108     for _, row := range rows {
 109         for _, colCell := range row {
 110             fmt.Print(colCell, "\t")
 111         }
 112         fmt.Println()
 113     }
 114 }
 115 ```
 116
 117 ### Add chart to spreadsheet file
 118
 119 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.
 120
 121 <p align="center"><img width="650" src="./test/images/chart.png" alt="Excelize"></p>
 122
 123 ```go
 124 package main
 125
 126 import (
 127     "fmt"
 128
 129     "github.com/xuri/excelize/v2"
 130 )
 131
 132 func main() {
 133     f := excelize.NewFile()
 134     defer func() {
 135         if err := f.Close(); err != nil {
 136             fmt.Println(err)
 137         }
 138     }()
 139     for idx, row := range [][]interface{}{
 140         {nil, "Apple", "Orange", "Pear"}, {"Small", 2, 3, 3},
 141         {"Normal", 5, 2, 4}, {"Large", 6, 7, 8},
 142     } {
 143         cell, err := excelize.CoordinatesToCellName(1, idx+1)
 144         if err != nil {
 145             fmt.Println(err)
 146             return
 147         }
 148         f.SetSheetRow("Sheet1", cell, &row)
 149     }
 150     if err := f.AddChart("Sheet1", "E1", &excelize.Chart{
 151         Type: excelize.Col3DClustered,
 152         Series: []excelize.ChartSeries{
 153             {
 154                 Name:       "Sheet1!$A$2",
 155                 Categories: "Sheet1!$B$1:$D$1",
 156                 Values:     "Sheet1!$B$2:$D$2",
 157             },
 158             {
 159                 Name:       "Sheet1!$A$3",
 160                 Categories: "Sheet1!$B$1:$D$1",
 161                 Values:     "Sheet1!$B$3:$D$3",
 162             },
 163             {
 164                 Name:       "Sheet1!$A$4",
 165                 Categories: "Sheet1!$B$1:$D$1",
 166                 Values:     "Sheet1!$B$4:$D$4",
 167             }},
 168         Title: []excelize.RichTextRun{
 169             {
 170                 Text: "Fruit 3D Clustered Column Chart",
 171             },
 172         },
 173     }); err != nil {
 174         fmt.Println(err)
 175         return
 176     }
 177     // Save spreadsheet by the given path.
 178     if err := f.SaveAs("Book1.xlsx"); err != nil {
 179         fmt.Println(err)
 180     }
 181 }
 182 ```
 183
 184 ### Add picture to spreadsheet file
 185
 186 ```go
 187 package main
 188
 189 import (
 190     "fmt"
 191     _ "image/gif"
 192     _ "image/jpeg"
 193     _ "image/png"
 194
 195     "github.com/xuri/excelize/v2"
 196 )
 197
 198 func main() {
 199     f, err := excelize.OpenFile("Book1.xlsx")
 200     if err != nil {
 201         fmt.Println(err)
 202         return
 203     }
 204     defer func() {
 205         // Close the spreadsheet.
 206         if err := f.Close(); err != nil {
 207             fmt.Println(err)
 208         }
 209     }()
 210     // Insert a picture.
 211     if err := f.AddPicture("Sheet1", "A2", "image.png", nil); err != nil {
 212         fmt.Println(err)
 213     }
 214     // Insert a picture to worksheet with scaling.
 215     if err := f.AddPicture("Sheet1", "D2", "image.jpg",
 216         &excelize.GraphicOptions{ScaleX: 0.5, ScaleY: 0.5}); err != nil {
 217         fmt.Println(err)
 218     }
 219     // Insert a picture offset in the cell with printing support.
 220     enable, disable := true, false
 221     if err := f.AddPicture("Sheet1", "H2", "image.gif",
 222         &excelize.GraphicOptions{
 223             PrintObject:     &enable,
 224             LockAspectRatio: false,
 225             OffsetX:         15,
 226             OffsetY:         10,
 227             Locked:          &disable,
 228         }); err != nil {
 229         fmt.Println(err)
 230     }
 231     // Save the spreadsheet with the origin path.
 232     if err = f.Save(); err != nil {
 233         fmt.Println(err)
 234     }
 235 }
 236 ```
 237
 238 ## Contributing
 239
 240 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/).
 241
 242 ## Licenses
 243
 244 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).
 245
 246 The Excel logo is a trademark of [Microsoft Corporation](https://aka.ms/trademarks-usage). This artwork is an adaptation.
 247
 248 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/).