工作簿

Options 定义了打开电子表格的选项。

type Options struct {
    Password string
}

创建

func NewFile() *File

使用 NewFile 新建 Excel 工作薄，新创建的工作簿中会默认包含一个名为 Sheet1 的工作表。

打开

func OpenFile(filename string, opt ...Options) (*File, error)

使用 OpenFile 打开已有 Excel 文档。例如，打开带有密码保护的电子表格文档:

f, err := excelize.OpenFile("Book1.xlsx", excelize.Options{Password: "password"})
if err != nil {
    return
}

请注意，目前 Excelize 支持解密带有密码保护的电子表格文档，但不支持加密，通过 Save() 和 SaveAs() 保存后的电子表格文档将不受密码保护。

打开数据流

func OpenReader(r io.Reader, opt ...Options) (*File, error)

OpenReader 从 io.Reader 读取数据流。

下面的例子中，我们创建一个简单的 HTTP 服务器接收上传的电子表格文档，向接收到的电子表格文档添加新工作表，并返回下载响应:

package main
import (
    "fmt"
    "net/http"
    "github.com/360EntSecGroup-Skylar/excelize/v2"
)
func process(w http.ResponseWriter, req *http.Request) {
    file, _, err := req.FormFile("file")
    if err != nil {
        fmt.Fprintf(w, err.Error())
        return
    }
    defer file.Close()
    f, err := excelize.OpenReader(file)
    if err != nil {
        fmt.Fprintf(w, err.Error())
        return
    }
    f.NewSheet("NewSheet")
    w.Header().Set("Content-Disposition", "attachment; filename=Book1.xlsx")
    w.Header().Set("Content-Type", req.Header.Get("Content-Type"))
    if _, err := f.WriteTo(w); err != nil {
        fmt.Fprintf(w, err.Error())
    }
    return
}
func main() {
    http.HandleFunc("/process", process)
    http.ListenAndServe(":8090", nil)
}

使用 cURL 进行测试:

curl --location --request GET 'http://127.0.0.1:8090/process' \
--form '[email protected]/tmp/template.xlsx' -O -J
curl: Saved to filename 'Book1.xlsx'

保存

func (f *File) Save() error

使用 Save 保存对 Excel 文档的编辑。

另存为

func (f *File) SaveAs(name string) error

使用 SaveAs 保存 Excel 文档为指定文件。

新建工作表

func (f *File) NewSheet(name string) int

根据给定的工作表名称来创建新工作表，并返回工作表在工作簿中的索引。请注意，在创建新的工作簿时，将包含名为 Sheet1 的默认工作表。

删除工作表

func (f *File) DeleteSheet(name string)

根据给定的工作表名称删除指定工作表，谨慎使用此方法，这将会影响到与被删除工作表相关联的公式、引用、图表等元素。如果有其他组件引用了被删除工作表上的值，将会引发错误提示，甚至将会导致打开工作簿失败。当工作簿中仅包含一个工作表时，调用此方法无效。

复制工作表

func (f *File) CopySheet(from, to int) error

根据给定的被复制工作表与目标工作表索引复制工作表，目标工作表索引需要开发者自行确认是否已经存在。目前支持仅包含单元格值和公式的工作表间的复制，不支持包含表格、图片、图表和透视表等元素的工作表之间的复制。

// 名称为 Sheet1 的工作表已经存在 ...
index := f.NewSheet("Sheet2")
err := f.CopySheet(1, index)
return err

设置工作表背景图片

func (f *File) SetSheetBackground(sheet, picture string) error

根据给定的工作表名称和图片地址为指定的工作表设置平铺效果的背景图片。

设置默认工作表

func (f *File) SetActiveSheet(index int)

根据给定的索引值设置默认工作表，索引的值应该大于等于 0 且小于工作簿所包含的累积工作表总数。

获取默认工作表索引

func (f *File) GetActiveSheetIndex() int

获取默认工作表的索引，如果没有找到默认工作表将返回 0。

设置工作表可见性

func (f *File) SetSheetVisible(name string, visible bool) error

根据给定的工作表名称和可见性参数设置工作表的可见性。一个工作簿中至少包含一个可见工作表。如果给定的工作表为默认工作表，则对其可见性设置无效。工作表可见性状态可参考工作表状态枚举:

例如，隐藏名为 Sheet1 的工作表:

err := f.SetSheetVisible("Sheet1", false)

获取工作表可见性

func (f *File) GetSheetVisible(name string) bool

根据给定的工作表名称获取工作表可见性设置。例如，获取名为 Sheet1 的工作表可见性设置:

f.GetSheetVisible("Sheet1")

设置工作表格式属性

func (f *File) SetSheetFormatPr(sheet string, opts ...SheetFormatPrOptions) error

根据给定的工作表名称设置格式属性。

例如，设置名为 Sheet1 的工作表中行默认为隐藏：

f := excelize.NewFile()
const sheet = "Sheet1"
if err := f.SetSheetFormatPr("Sheet1", excelize.ZeroHeight(true)); err != nil {
    fmt.Println(err)
}
if err := f.SetRowVisible("Sheet1", 10, true); err != nil {
    fmt.Println(err)
}
f.SaveAs("Book1.xlsx")

获取工作表格式属性

func (f *File) GetSheetFormatPr(sheet string, opts ...SheetFormatPrOptionsPtr) error

根据给定的工作表名称获取格式属性。

例子:

f := excelize.NewFile()
const sheet = "Sheet1"
var (
    baseColWidth     excelize.BaseColWidth
    defaultColWidth  excelize.DefaultColWidth
    defaultRowHeight excelize.DefaultRowHeight
    customHeight     excelize.CustomHeight
    zeroHeight       excelize.ZeroHeight
    thickTop         excelize.ThickTop
    thickBottom      excelize.ThickBottom
)
if err := f.GetSheetFormatPr(sheet,
    &baseColWidth,
    &defaultColWidth,
    &defaultRowHeight,
    &customHeight,
    &zeroHeight,
    &thickTop,
    &thickBottom,
); err != nil {
    fmt.Println(err)
}
fmt.Println("Defaults:")
fmt.Println("- baseColWidth:", baseColWidth)
fmt.Println("- defaultColWidth:", defaultColWidth)
fmt.Println("- defaultRowHeight:", defaultRowHeight)
fmt.Println("- customHeight:", customHeight)
fmt.Println("- zeroHeight:", zeroHeight)
fmt.Println("- thickTop:", thickTop)
fmt.Println("- thickBottom:", thickBottom)

得到输出：

Defaults:
- baseColWidth: 0
- defaultColWidth: 0
- defaultRowHeight: 15
- customHeight: false
- zeroHeight: false
- thickTop: false
- thickBottom: false

设置工作表视图属性

func (f *File) SetSheetViewOptions(name string, viewIndex int, opts ...SheetViewOption) error

根据给定的工作表名称、视图索引和视图参数设置工作表视图属性，viewIndex 可以是负数，如果是这样，则向后计数（-1 代表最后一个视图）。

• 例1:

err = f.SetSheetViewOptions("Sheet1", -1, ShowGridLines(false))

• 例2:

f := excelize.NewFile()
const sheet = "Sheet1"
if err := f.SetSheetViewOptions(sheet, 0,
    excelize.DefaultGridColor(false),
    excelize.RightToLeft(false),
    excelize.ShowFormulas(true),
    excelize.ShowGridLines(true),
    excelize.ShowRowColHeaders(true),
    excelize.ZoomScale(80),
    excelize.TopLeftCell("C3"),
); err != nil {
    fmt.Println(err)
}
var zoomScale excelize.ZoomScale
fmt.Println("Default:")
fmt.Println("- zoomScale: 80")
if err := f.SetSheetViewOptions(sheet, 0, excelize.ZoomScale(500)); err != nil {
    fmt.Println(err)
}
if err := f.GetSheetViewOptions(sheet, 0, &zoomScale); err != nil {
    fmt.Println(err)
}
fmt.Println("Used out of range value:")
fmt.Println("- zoomScale:", zoomScale)
if err := f.SetSheetViewOptions(sheet, 0, excelize.ZoomScale(123)); err != nil {
    fmt.Println(err)
}
if err := f.GetSheetViewOptions(sheet, 0, &zoomScale); err != nil {
    fmt.Println(err)
}
fmt.Println("Used correct value:")
fmt.Println("- zoomScale:", zoomScale)

得到输出：

Default:
- zoomScale: 80
Used out of range value:
- zoomScale: 80
Used correct value:
- zoomScale: 123

获取工作表视图属性

func (f *File) GetSheetViewOptions(name string, viewIndex int, opts ...SheetViewOptionPtr) error

根据给定的工作表名称、视图索引和视图参数获取工作表视图属性，viewIndex 可以是负数，如果是这样，则向后计数（-1 代表最后一个视图）。

• 例1，获取名为 Sheet1 的工作表上最后一个视图的网格线属性设置：

var showGridLines excelize.ShowGridLines
err = f.GetSheetViewOptions("Sheet1", -1, &showGridLines)

• 例2：

f := excelize.NewFile()
const sheet = "Sheet1"
var (
    defaultGridColor  excelize.DefaultGridColor
    rightToLeft       excelize.RightToLeft
    showFormulas      excelize.ShowFormulas
    showGridLines     excelize.ShowGridLines
    showZeros         excelize.ShowZeros
    showRowColHeaders excelize.ShowRowColHeaders
    zoomScale         excelize.ZoomScale
    topLeftCell       excelize.TopLeftCell
)
if err := f.GetSheetViewOptions(sheet, 0,
    &defaultGridColor,
    &rightToLeft,
    &showFormulas,
    &showGridLines,
    &showZeros,
    &showRowColHeaders,
    &zoomScale,
    &topLeftCell,
); err != nil {
    fmt.Println(err)
}
fmt.Println("Default:")
fmt.Println("- defaultGridColor:", defaultGridColor)
fmt.Println("- rightToLeft:", rightToLeft)
fmt.Println("- showFormulas:", showFormulas)
fmt.Println("- showGridLines:", showGridLines)
fmt.Println("- showZeros:", showZeros)
fmt.Println("- showRowColHeaders:", showRowColHeaders)
fmt.Println("- zoomScale:", zoomScale)
fmt.Println("- topLeftCell:", `"`+topLeftCell+`"`)
if err := f.SetSheetViewOptions(sheet, 0, excelize.TopLeftCell("B2")); err != nil {
    fmt.Println(err)
}
if err := f.GetSheetViewOptions(sheet, 0, &topLeftCell); err != nil {
    fmt.Println(err)
}
if err := f.SetSheetViewOptions(sheet, 0, excelize.ShowGridLines(false)); err != nil {
    fmt.Println(err)
}
if err := f.GetSheetViewOptions(sheet, 0, &showGridLines); err != nil {
    fmt.Println(err)
}
if err := f.SetSheetViewOptions(sheet, 0, excelize.ShowZeros(false)); err != nil {
    fmt.Println(err)
}
if err := f.GetSheetViewOptions(sheet, 0, &showZeros); err != nil {
    fmt.Println(err)
}
fmt.Println("After change:")
fmt.Println("- showGridLines:", showGridLines)
fmt.Println("- showZeros:", showZeros)
fmt.Println("- topLeftCell:", topLeftCell)

得到输出：

Default:
- defaultGridColor: true
- rightToLeft: false
- showFormulas: false
- showGridLines: true
- showZeros: true
- showRowColHeaders: true
- zoomScale: 0
- topLeftCell: ""
After change:
- showGridLines: false
- showZeros: false
- topLeftCell: B2

设置工作表页面布局

func (f *File) SetPageLayout(sheet string, opts ...PageLayoutOption) error

根据给定的工作表名称和页面布局参数设置工作表的页面布局属性。目前支持设置的页面布局属性：

• 通过 BlackAndWhite 方法设置单色打印 true 或 false，默认值为 false 关闭。

• 通过 FirstPageNumber 方法设置页面起始页码，默认为自动。

• 通过 PageLayoutOrientation 方法设置页面布局方向，默认页面布局方向为“纵向”。下面的表格是 Excelize 中页面布局方向 PageLayoutOrientation 参数的列表：

• 通过 PageLayoutPaperSize 方法设置页面纸张大小，默认页面布局大小为“信纸 8½ × 11 英寸”。下面的表格是 Excelize 中页面布局大小和索引 PageLayoutPaperSize 参数的关系对照：

• 通过 FitToHeight 方法设置页面缩放调整页宽，默认值为 1。

• 通过 FitToWidth 方法设置页面缩放调整页高，默认值为 1。

• 通过 PageLayoutScale 方法设置页面缩放比例，取值范围 10 至 400，即缩放 10% 至 400%，默认值为 100 正常尺寸。

• 例如，将名为 Sheet1 的工作表页面布局设置为单色打印、起始页码为 2、横向、使用 A4(小) 210 × 297 毫米纸张、调整为 2 页宽、2 页高并缩放 50%：

f := excelize.NewFile()
if err := f.SetPageLayout(
    "Sheet1",
    excelize.BlackAndWhite(true),
    excelize.FirstPageNumber(2),
    excelize.PageLayoutOrientation(excelize.OrientationLandscape),
    excelize.PageLayoutPaperSize(10),
    excelize.FitToHeight(2),
    excelize.FitToWidth(2),
    excelize.PageLayoutScale(50),
); err != nil {
    fmt.Println(err)
}

获取工作表页面布局

func (f *File) GetPageLayout(sheet string, opts ...PageLayoutOptionPtr) error

根据给定的工作表名称和页面布局参数获取工作表的页面布局属性。

• 通过 PageLayoutOrientation 方法获取页面布局方向
• 通过 PageLayoutPaperSize 方法获取页面纸张大小

例如，获取名为 Sheet1 的工作表页面布局设置：

f := excelize.NewFile()
const sheet = "Sheet1"
var (
    orientation excelize.PageLayoutOrientation
    paperSize   excelize.PageLayoutPaperSize
)
if err := f.GetPageLayout("Sheet1", &orientation); err != nil {
    fmt.Println(err)
}
if err := f.GetPageLayout("Sheet1", &paperSize); err != nil {
    fmt.Println(err)
}
fmt.Println("Defaults:")
fmt.Printf("- orientation: %q\n", orientation)
fmt.Printf("- paper size: %d\n", paperSize)

得到输出：

Defaults:
- orientation: "portrait"
- paper size: 1

设置工作表页边距

func (f *File) SetPageMargins(sheet string, opts ...PageMarginsOptions) error

根据给定的工作表名称和页边距参数设置工作表的页边距。页边距可选参数：

• 例如，设置名为 Sheet1 的工作表页边距:

f := excelize.NewFile()
const sheet = "Sheet1"
if err := f.SetPageMargins(sheet,
    excelize.PageMarginBottom(1.0),
    excelize.PageMarginFooter(1.0),
    excelize.PageMarginHeader(1.0),
    excelize.PageMarginLeft(1.0),
    excelize.PageMarginRight(1.0),
    excelize.PageMarginTop(1.0),
); err != nil {
    fmt.Println(err)
}

获取工作表页边距

根据给定的工作表名称和页边距参数获取工作表的页边距。页边距可选参数：

• 例如，获取名为 Sheet1 的工作表页边距:

f := excelize.NewFile()
const sheet = "Sheet1"
var (
    marginBottom excelize.PageMarginBottom
    marginFooter excelize.PageMarginFooter
    marginHeader excelize.PageMarginHeader
    marginLeft   excelize.PageMarginLeft
    marginRight  excelize.PageMarginRight
    marginTop    excelize.PageMarginTop
)
if err := f.GetPageMargins(sheet,
    &marginBottom,
    &marginFooter,
    &marginHeader,
    &marginLeft,
    &marginRight,
    &marginTop,
); err != nil {
    fmt.Println(err)
}
fmt.Println("Defaults:")
fmt.Println("- marginBottom:", marginBottom)
fmt.Println("- marginFooter:", marginFooter)
fmt.Println("- marginHeader:", marginHeader)
fmt.Println("- marginLeft:", marginLeft)
fmt.Println("- marginRight:", marginRight)
fmt.Println("- marginTop:", marginTop)

得到输出：

Defaults:
- marginBottom: 0.75
- marginFooter: 0.3
- marginHeader: 0.3
- marginLeft: 0.7
- marginRight: 0.7
- marginTop: 0.75

设置页眉和页脚

func (f *File) SetHeaderFooter(sheet string, settings *FormatHeaderFooter) error

根据给定的工作表名称和控制字符设置工作表的页眉和页脚。

页眉和页脚包含如下字段：

下表中的格式代码可用于 6 个字符串类型字段: OddHeader, OddFooter, EvenHeader, EvenFooter, FirstFooter, FirstHeader

例如：

err := f.SetHeaderFooter("Sheet1", &excelize.FormatHeaderFooter{
    DifferentFirst:   true,
    DifferentOddEven: true,
    OddHeader:        "&R&P",
    OddFooter:        "&C&F",
    EvenHeader:       "&L&P",
    EvenFooter:       "&L&D&R&T",
    FirstHeader:      `&CCenter &"-,Bold"Bold&"-,Regular"HeaderU+000A&D`,
})

上面的例子蕴含如下格式：

• 第一页有自己的页眉和页脚
• 奇数和偶数页具有不同的页眉和页脚
• 奇数页标题右侧部分为当前页码
• 奇数页页脚中心部分为当前工作簿的文件名
• 偶数页标题左侧部分为当前页码
• 左侧部分为当前日期，偶数页页脚右侧部分为当前时间
• 第一页中心部分的第一行上的文本为“Center Bold Header”, 第二行为日期
• 第一页上没有页脚

设置名称

func (f *File) SetDefinedName(definedName *DefinedName) error

根据给定的名称和作范围设置名称，默认范围是工作簿。例如：

f.SetDefinedName(&excelize.DefinedName{
    Name:     "Amount",
    RefersTo: "Sheet1!$A$2:$D$5",
    Comment:  "defined name comment",
    Scope:    "Sheet2",
})

工作表的打印区域和打印标题设置:

f.SetDefinedName(&excelize.DefinedName{
    Name:     "_xlnm.Print_Area",
    RefersTo: "Sheet1!$A$1:$Z$100",
    Scope:    "Sheet1",
})
f.SetDefinedName(&excelize.DefinedName{
    Name:     "_xlnm.Print_Titles",
    RefersTo: "Sheet1!$A:$A,Sheet1!$1:$1",
    Scope:    "Sheet1",
})

获取名称

func (f *File) GetDefinedName() []DefinedName

获取作用范围内的工作簿和工作表的名称列表。

删除名称

func (f *File) DeleteDefinedName(definedName *DefinedName) error

根据给定的名称和名称作用范围删除已定义的名称，默认名称的作用范围为工作簿。例如：

f.DeleteDefinedName(&excelize.DefinedName{
    Name:     "Amount",
    Scope:    "Sheet2",
})

设置工作簿属性

func (f *File) SetDocProps(docProperties *DocProperties) error

设置工作簿的核心属性。 可以设置的属性包括:

例如：

err := f.SetDocProps(&excelize.DocProperties{
    Category:       "category",
    ContentStatus:  "Draft",
    Created:        "2019-06-04T22:00:10Z",
    Creator:        "Go Excelize",
    Description:    "This file created by Go Excelize",
    Identifier:     "xlsx",
    Keywords:       "Spreadsheet",
    LastModifiedBy: "Go Author",
    Modified:       "2019-06-04T22:00:10Z",
    Revision:       "0",
    Subject:        "Test Subject",
    Title:          "Test Title",
    Language:       "en-US",
    Version:        "1.0.0",
})

获取工作簿属性

func (f *File) GetDocProps() (*DocProperties, error)

获取工作簿的核心属性。