go-excel

To handle complex data types (like JSON strings in a cell), implement the encoding.BinaryUnmarshaler interface on your custom type. The library will automatically use UnmarshalBinary to populate the field.

type Temp struct {
	Foo string
}

// UnmarshalBinary allows custom logic for cell values
func (t *Temp) UnmarshalBinary(d []byte) error {
	return json.Unmarshal(d, t)
}

Install the library using go get:

go get github.com/szyhf/go-excel

You can pass an excel.Config object to customize how sheets are identified and how rows are processed.

Key configuration fields:

• Sheet: Defines the sheet to use (string name, index, or object with GetXLSXSheetName()).
• TitleRowIndex: The index of the row used as the title row (default is 0). Rows before this are ignored.
• Skip: Number of rows to skip after the title row (default is 0).
• Prefix: Auto-prefix for the sheet name.
• Suffix: Auto-suffix for the sheet name.

type Config struct {
	Sheet         interface{}
	TitleRowIndex int
	Skip          int
	Prefix        string
	Suffix        string
}

For simple use cases, use excel.UnmarshalXLSX to read an entire XLSX file directly into a slice of structs. By default, it assumes the sheet name matches the struct name.

type Standard struct {
	ID      int
	Name    string `xlsx:"column(NameOf)"`
	Age     int    `xlsx:"AgeOf"` 
}

func simpleUsage() {
	var stdList []Standard
	err := excel.UnmarshalXLSX("./testdata/simple.xlsx", &stdList)
	if err != nil {
		panic(err)
	}
}

If struct tags are insufficient or difficult to manage (e.g., due to complex escape characters), you can implement the GetXLSXFieldConfigs() map[string]FieldConfig method on your struct. This method takes precedence over struct tags.

// Implementation detail: implement this on your struct to override tags
// func (s *Standard) GetXLSXFieldConfigs() map[string]FieldConfig { ... }

The Config struct allows you to define how a sheet is identified and how rows are parsed.

Key fields:

• Sheet: Defines which sheet to target. It accepts:
  • string: The exact sheet name.
  • int: The 1-based index of the sheet (note: hidden sheets are included in the count).
  • An object implementing GetXLSXSheetName() string.
  • A struct (the name is inferred via reflection).
  • A slice (the element type is used to infer the name).
• TitleRowIndex: The 0-based index of the row used as the header/title. Rows before this index are ignored. Defaults to 0.
• Skip: The number of rows to skip immediately after the title row. Empty rows are not counted. Defaults to 0.
• Prefix / Suffix: Strings to automatically prefix or suffix the sheet name.

config := &excel.Config{
    Sheet:         "Sheet1",
    TitleRowIndex: 1,
    Skip:          2,
}

The ReadAll(container interface{}) method reads all remaining rows in the worksheet and populates a slice container.

Requirements for container:

• It must be a pointer to a slice (e.g., *[]MyStruct or *[]map[string]string).
• If the slice contains structs, the fields will be mapped according to the worksheet's title row.

If the container is not a pointer to a slice, it returns ErrInvalidConatiner.

var allRows []MyStruct
err := rd.ReadAll(&allRows)
if err != nil {
    // handle error
}

If you prefer not to use struct tags, you can implement the ExcelFiledConfiger interface on your struct. This allows you to provide a map of FieldConfig objects, which takes precedence over struct tags.

Implementing GetXLSXFieldConfigs() map[string]FieldConfig allows you to define mapping logic programmatically.

type MyStruct struct {
	Name string
}

// Implement ExcelFiledConfiger
func (m *MyStruct) GetXLSXFieldConfigs() map[string]excel.FieldConfig {
	return map[string]excel.FieldConfig{
		"Name": {
			ColumnName: "Full Name",
			DefaultValue: "Anonymous",
		},
	}
}

If you have the Excel file content already loaded in memory as a byte slice, use OpenBinary to initialize the reader.

err := conn.OpenBinary(xlsxData)
if err != nil {
    // handle error
}