工作簿

《Excelize 权威指南》图书出版，网上购买方式：人民邮电出版社 | 异步社区 | 天猫 | 京东 | 当当 | 亚马逊 | 微店 | 抖音

Options 定义了读写电子表格时的选项。

type Options struct {
    MaxCalcIterations uint
    Password          string
    RawCellValue      bool
    UnzipSizeLimit    int64
    UnzipXMLSizeLimit int64
    TmpDir            string
    ShortDatePattern  string
    LongDatePattern   string
    LongTimePattern   string
    CultureInfo       CultureName
}

MaxCalcIterations 用以指定计算公式时最多迭代次数，默认值为 0。

Password 以明文形式指定打开和保存工作簿时所使用的密码，默认值为空。

RawCellValue 用以指定读取单元格值时是否获取原始值，默认值为 false（应用数字格式）。

UnzipSizeLimit 用以指定打开电子表格文档时的解压缩大小限制（以字节为单位），该值应大于或等于 UnzipXMLSizeLimit，默认大小限制为 16GB。

UnzipXMLSizeLimit 用以指定解压每个工作表以及共享字符表时的内存限制（以字节为单位），当大小超过此值时工作表 XML 文件将被解压至系统临时目录，该值应小于或等于 UnzipSizeLimit，默认大小限制为 16MB。

TmpDir 用以指定创建临时文件的临时目录，如果值为空，则使用系统默认的临时目录。

ShortDatePattern 用以指定短日期数字格式代码。在电子表格应用程序中，可以通过为单元格设置带有日期格式的数字格式，将日期和时间序列号显示为日期值。其中以星号 (*) 开头的日期格式响应为操作系统指定的区域日期和时间设置的更改。没有星号的格式不受操作系统设置的影响。ShortDatePattern 用于指定读取以星号开头的日期格式时所应用的短日期数字格式代码。

LongDatePattern 用以指定长日期数字格式代码。

LongTimePattern 用以指定长时间数字格式代码。

CultureInfo 用以指定区域格式，该设置将在读取受到操作系统特定的区域日期和时间设置影响的数字格式时使用。

HeaderFooterImagePositionType 定义了页眉页脚图片位置类型。

type HeaderFooterImagePositionType byte

下面是工作表页眉页脚位置枚举值。

const (
    HeaderFooterImagePositionLeft HeaderFooterImagePositionType = iota
    HeaderFooterImagePositionCenter
    HeaderFooterImagePositionRight
)

CustomProperty 定义了设置工作簿自定义属性时的选项。自定义属性的值支持以下数据类型：int32、float64、string、bool、time.Time 和 nil。

type CustomProperty struct {
    Name  string
    Value interface{}
}

CalcPropsOptions 定义了设置工作簿计算属性时的选项。

type CalcPropsOptions struct {
    CalcID                *uint
    CalcMode              *string
    FullCalcOnLoad        *bool
    RefMode               *string
    Iterate               *bool
    IterateCount          *uint
    IterateDelta          *float64
    FullPrecision         *bool
    CalcCompleted         *bool
    CalcOnSave            *bool
    ConcurrentCalc        *bool
    ConcurrentManualCount *uint
    ForceFullCalc         *bool
}

创建

func NewFile(opts ...Options) *File

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

打开

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

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

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

使用 Close() 关闭已打开的工作簿。

打开数据流

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

OpenReader 从 io.Reader 读取数据流。

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

package main

import (
    "fmt"
    "net/http"

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

func process(w http.ResponseWriter, req *http.Request) {
    file, _, err := req.FormFile("file")
    if err != nil {
        fmt.Fprint(w, err.Error())
        return
    }
    defer file.Close()
    f, err := excelize.OpenReader(file)
    if err != nil {
        fmt.Fprint(w, err.Error())
        return
    }
    f.Path = "Book1.xlsx"
    f.NewSheet("NewSheet")
    w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%s", f.Path))
    w.Header().Set("Content-Type", req.Header.Get("Content-Type"))
    if err := f.Write(w); err != nil {
        fmt.Fprint(w, err.Error())
    }
}

func main() {
    http.HandleFunc("/process", process)
    http.ListenAndServe(":8090", nil)
}

使用 cURL 进行测试:

curl --location --request GET 'http://127.0.0.1:8090/process' \
--form 'file=@/tmp/template.xltx' -O -J

保存

func (f *File) Save(opts ...Options) error

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

另存为

func (f *File) SaveAs(name string, opts ...Options) error

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

关闭工作簿

func (f *File) Close() error

关闭工作簿并清理打开文档时可能产生的系统磁盘缓存。

新建工作表

func (f *File) NewSheet(sheet string) (int, error)

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

删除工作表

func (f *File) DeleteSheet(sheet string) error

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

移动工作表

func (f *File) MoveSheet(source, target string) error

将工作表移动到工作簿中的指定位置。根据给定的被移动工作表名称和目标工作表名称，将工作表移动至目标工作表之前。移动后，其他工作表的位置将向左或向右移动，如果工作表已经在目标位置，则该函数不会执行任何操作。请注意，该函数在移动工作表后将取消所有工作表分组。例如，将名为 Sheet2 的工作表移动至工作表 Sheet1 之前：

err := f.MoveSheet("Sheet2", "Sheet1")

复制工作表

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

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

// 名称为 Sheet1 的工作表已经存在 ...
index, err := f.NewSheet("Sheet2")
if err != nil {
    fmt.Println(err)
    return
}
err = f.CopySheet(0, index)

工作表分组

func (f *File) GroupSheets(sheets []string) error

根据给定的工作表名称对工作表进行分组，给定的工作表中需包含默认工作表。

取消工作表分组

func (f *File) UngroupSheets() error

取消工作表分组。

设置工作表背景图片

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

根据给定的工作表名称和图片文件路径为指定的工作表设置平铺效果的背景图片。支持的图片文件格式为：BMP、EMF、EMZ、GIF、ICO、JPEG、JPG、PNG、SVG、TIF、TIFF、WMF 和 WMZ。

func (f *File) SetSheetBackgroundFromBytes(sheet, extension string, picture []byte) error

根据给定的工作表名称、图片格式扩展名和图片格式数据为指定的工作表设置平铺效果的背景图片。支持的图片文件格式为：BMP、EMF、EMZ、GIF、ICO、JPEG、JPG、PNG、SVG、TIF、TIFF、WMF 和 WMZ。

设置默认工作表

func (f *File) SetActiveSheet(index int)

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

获取默认工作表索引

func (f *File) GetActiveSheetIndex() int

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

设置工作表可见性

func (f *File) SetSheetVisible(sheet string, visible bool, veryHidden ...bool) error

根据给定的工作表名称和可见性参数设置工作表的可见性。一个工作簿中至少包含一个可见工作表。如果给定的工作表为默认工作表，则对其可见性设置无效。第三个可选参数 veryHidden 仅在 visible 参数值为 false 时有效。

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

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

获取工作表可见性

func (f *File) GetSheetVisible(sheet string) (bool, error)

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

visible, err := f.GetSheetVisible("Sheet1")

设置工作表属性

func (f *File) SetSheetProps(sheet string, opts *SheetPropsOptions) error

根据给定的工作表名称和属性参数设置工作表属性。支持设置的工作表属性选项：

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

f, enable := excelize.NewFile(), true
if err := f.SetSheetProps("Sheet1", &excelize.SheetPropsOptions{
    ZeroHeight: &enable,
}); err != nil {
    fmt.Println(err)
}
if err := f.SetRowVisible("Sheet1", 10, true); err != nil {
    fmt.Println(err)
}
f.SaveAs("Book1.xlsx")

在电子表格应用中，有四种"自定义缩放"预设选项。如果您需要使用这些缩放选项，请使用 SetSheetProps 和 SetPageLayout 函数来设置这四种缩放选项:

1. 不缩放（打印实际大小的工作表）:

    disable := false
    if err := f.SetSheetProps("Sheet1", &excelize.SheetPropsOptions{
        FitToPage: &disable,
    }); err != nil {
        fmt.Println(err)
    }
   

2. 将工作表调整为一页（缩减打印输出以显示在一个页面上）:

    enable := true
    if err := f.SetSheetProps("Sheet1", &excelize.SheetPropsOptions{
        FitToPage: &enable,
    }); err != nil {
        fmt.Println(err)
    }
   

3. 将所有列调整为一页（缩减打印输出使其只有一个页面宽）:

    enable, zero := true, 0
    if err := f.SetSheetProps("Sheet1", &excelize.SheetPropsOptions{
        FitToPage: &enable,
    }); err != nil {
        fmt.Println(err)
    }
    if err := f.SetPageLayout("Sheet1", &excelize.PageLayoutOptions{
        FitToHeight: &zero,
    }); err != nil {
        fmt.Println(err)
    }
   

4. 将所有行调整为一页（缩减打印输出使其只有一个页面高）:

    enable, zero := true, 0
    if err := f.SetSheetProps("Sheet1", &excelize.SheetPropsOptions{
        FitToPage: &enable,
    }); err != nil {
        fmt.Println(err)
    }
    if err := f.SetPageLayout("Sheet1", &excelize.PageLayoutOptions{
        FitToWidth: &zero,
    }); err != nil {
        fmt.Println(err)
    }
   

获取工作表属性

func (f *File) GetSheetProps(sheet string) (SheetPropsOptions, error)

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

设置工作表视图属性

func (f *File) SetSheetView(sheet string, viewIndex int, opts *ViewOptions) error

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

获取工作表视图属性

func (f *File) GetSheetView(sheet string, viewIndex int) (ViewOptions, error)

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

设置工作表页面布局

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

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

Size 属性用以指定页面纸张大小，默认页面布局大小为“信纸 (8½ 英寸 × 11 英寸)”。下面的表格是 Excelize 中页面布局大小和索引 Size 参数的关系对照：

Orientation 属性用以指定页面布局方向，默认页面布局方向为“纵向”，可选值为 portrait 和 landscape。

FirstPageNumber 属性用以指定页面起始页码，默认为自动。

AdjustTo 属性用以指定页面缩放比例，取值范围 10 至 400，即缩放 10% 至 400%，默认值为 100 正常尺寸。FitToHeight 或 FitToWidth 的设置会覆盖此属性。

FitToHeight 属性用以指定页面缩放调整页宽，默认值为 1。

FitToWidth 属性用以指定页面缩放调整页高，默认值为 1。

BlackAndWhite 属性用以指定单色打印，默认为关闭。

PageOrder 属性用以指定页面顺序，可选值为：overThenDown（先行后列）和 downThenOver（先列后行），默认值为 downThenOver。

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

f := excelize.NewFile()
var (
    size                 = 10
    orientation          = "landscape"
    firstPageNumber uint = 2
    adjustTo        uint = 100
    fitToHeight          = 2
    fitToWidth           = 2
    blackAndWhite        = true
)
if err := f.SetPageLayout("Sheet1", &excelize.PageLayoutOptions{
    Size:            &size,
    Orientation:     &orientation,
    FirstPageNumber: &firstPageNumber,
    AdjustTo:        &adjustTo,
    FitToHeight:     &fitToHeight,
    FitToWidth:      &fitToWidth,
    BlackAndWhite:   &blackAndWhite,
}); err != nil {
    fmt.Println(err)
}

获取工作表页面布局

func (f *File) GetPageLayout(sheet string) (PageLayoutOptions, error)

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

设置工作表页边距

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

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

获取工作表页边距

func (f *File) GetPageMargins(sheet string) (PageLayoutMarginsOptions, error)

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

设置工作簿属性

func (f *File) SetWorkbookProps(opts *WorkbookPropsOptions) error

SetWorkbookProps 用于设置工作簿属性。支持设置的工作簿属性：

获取工作簿属性

func (f *File) GetWorkbookProps() (WorkbookPropsOptions, error)

GetWorkbookProps 用于获取工作簿属性。

设置页眉和页脚

func (f *File) SetHeaderFooter(sheet string, opts *HeaderFooterOptions) error

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

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

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

例如：

err := f.SetHeaderFooter("Sheet1", &excelize.HeaderFooterOptions{
    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) AddHeaderFooterImage(sheet string, opts *HeaderFooterImageOptions) error

添加可通过 &G 控制字符在页眉和页脚定义中引用的图片，支持的图片文件格式为：EMF、EMZ、GIF、ICO、JPEG、JPG、PNG、SVG、TIF、TIFF、WMF 和 WMZ。

设置名称

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

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

err := f.SetDefinedName(&excelize.DefinedName{
    Name:     "数量",
    RefersTo: "Sheet1!$A$2:$D$5",
    Comment:  "自定义名称的批注",
})

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

if err := f.SetDefinedName(&excelize.DefinedName{
    Name:     "_xlnm.Print_Area",
    RefersTo: "Sheet1!$A$1:$Z$100",
    Scope:    "Sheet1",
}); err != nil {
    fmt.Println(err)
}
if err := f.SetDefinedName(&excelize.DefinedName{
    Name:     "_xlnm.Print_Titles",
    RefersTo: "Sheet1!$A:$A,Sheet1!$1:$1",
    Scope:    "Sheet1",
}); err != nil {
    fmt.Println(err)
}

在设置打印标题时，若将 RefersTo 选项的值设置为不包含逗号分隔符的列范围引用，将仅对“从左侧重复的列数”生效。例如：

if err := f.SetDefinedName(&excelize.DefinedName{
    Name:     "_xlnm.Print_Titles",
    RefersTo: "Sheet1!$A:$A",
    Scope:    "Sheet1",
}); err != nil {
    fmt.Println(err)
}

在设置打印标题时，若将 RefersTo 选项的值设置为不包含逗号分隔符的行范围引用，将仅对“顶端标题行”生效。例如：

if err := f.SetDefinedName(&excelize.DefinedName{
    Name:     "_xlnm.Print_Titles",
    RefersTo: "Sheet1!$1:$1",
    Scope:    "Sheet1",
}); err != nil {
    fmt.Println(err)
}

在 RefersTo 选项中可以使用公式。例如：

err := f.SetDefinedName(&excelize.DefinedName{
    Name:     "自定义单元格范围",
    RefersTo: "Sheet1!$A$2+Sheet1!$D$5",
    Scope:    "Sheet1",
})

获取名称

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

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

删除名称

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

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

err := f.DeleteDefinedName(&excelize.DefinedName{
    Name:     "数量",
    Scope:    "Sheet2",
})

设置工作簿应用程序属性

func (f *File) SetAppProps(appProperties *AppProperties) error

设置工作簿的应用程序属性。可以设置的属性包括:

例如：

err := f.SetAppProps(&excelize.AppProperties{
    Application:       "Microsoft Excel",
    ScaleCrop:         true,
    DocSecurity:       3,
    Company:           "Company Name",
    LinksUpToDate:     true,
    HyperlinksChanged: true,
    AppVersion:        "16.0000",
})

获取工作簿应用程序属性

func (f *File) GetAppProps() (*AppProperties, error)

获取工作簿的应用程序属性。

设置文档属性

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)

获取工作簿的核心属性。

设置自定义属性

func (f *File) SetCustomProps(prop CustomProperty) error

根据给定的属性名称和值设置工作簿的自定义属性。如果给定的属性名称已经存在，将会更新已存在属性的值，否则将添加新的属性。属性值支持的数据类型为 int32、float64、bool、string、time.Time 或 nil。当设置属性的值为 nil 时，将删除指定的属性。当给定的属性值是不受支持的数据类型时，函数将会返回错误。

获取自定义属性

func (f *File) GetCustomProps() ([]CustomProperty, error)

获取全部自定义属性。

设置计算属性

func (f *File) SetCalcProps(opts *CalcPropsOptions) error

设置工作簿的计算属性。

可选属性 CalcMode 的有效值为：manual、auto 或 autoNoTable。

可选属性 RefMode 的有效值为：A1 或 R1C1。

获取计算属性

func (f *File) GetCalcProps() (CalcPropsOptions, error)

获取工作簿的计算属性。

保护工作簿

func (f *File) ProtectWorkbook(opts *WorkbookProtectionOptions) error

使用密码保护工作簿的结构，以防止其他用户查看隐藏的工作表，添加、移动或隐藏工作表以及重命名工作表，选字段 AlgorithmName 支持指定哈希算法 XOR、MD4、MD5、SHA-1、SHA-256、SHA-384 或 SHA-512，如果未指定哈希算法，默认使用 XOR 算法。例如，使用密码保护工作簿结构：

err := f.ProtectWorkbook(&excelize.WorkbookProtectionOptions{
    Password:      "password",
    LockStructure: true,
})

WorkbookProtectionOptions 定义了保护工作簿的设置选项。

type WorkbookProtectionOptions struct {
    AlgorithmName string
    Password      string
    LockStructure bool
    LockWindows   bool
}

取消保护保护工作簿

func (f *File) UnprotectWorkbook(password ...string) error

取保护工作簿，指定可选密码参数以通过密码验证来取消工作簿保护。