活頁簿

Options 定義了讀寫電子表格檔案時的選項。

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

MaxCalcIterations 用以指定計算公式時最多迭代次數，默認值為 0。

Password 以明文形式指定開啓和儲存活頁簿時所使用的密碼，默認值為空。

RawCellValue 用以指定讀取存儲格值時是否獲取原始值，默認值為 false（應用數字格式）。

UnzipSizeLimit 用以指定開啓電子錶格檔案時的解壓縮大小限制（以位元組為單位），該值應大於或等於 UnzipXMLSizeLimit，默認大小限制為 16GB。

UnzipXMLSizeLimit 用以指定解壓每個工作表以及共享字符表時的內存限制（以位元組為單位），當大小超過此值時工作表 XML 文件將被解壓至系統臨時目錄，該值應小於或等於 UnzipSizeLimit，默認大小限制為 16MB。

ShortDatePattern 用以指定短日期數字格式代碼。在電子錶格應用程式中，可以透過為存儲格設定帶有日期格式的數字格式，將日期和時間序列號顯示為日期值。其中以星號 (*) 開頭的日期格式響應為作業系統指定的區域日期和時間設定的更改。沒有星號的格式不受作業系統設定的影響。ShortDatePattern 用於指定讀取以星號開頭的日期格式時所應用的短日期數字格式代碼。

LongDatePattern 用以指定長日期數字格式代碼。

LongTimePattern 用以指定長時間數字格式代碼。

CultureInfo 用以指定區域格式，該設定將在讀取受到作業系統特定的區域日期和時間設定影響的數字格式時使用。

新增

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) CopySheet(from, to int) error

根據給定的被複製工作表與目標工作表索引複製工作表，目標工作表索引需要開發者自行確認是否已經存在。目前支援僅包含儲存格值和公式的工作表間的複製，不支援包含表格、圖片、圖表和透視表等元素的工作表之間的複製。

// 名稱為 Sheet1 的工作表已經存在 ...
index, err := f.NewSheet("Sheet2")
if err != nil {
    fmt.Println(err)
    return
}
err := f.CopySheet(1, 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、JPEG、JPG、PNG、SVG、TIF、TIFF、WMF 和 WMZ。

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

根據給定的工作表名稱、圖片格式擴展名和圖片格式數據為指定的工作表設定平鋪效果的背景圖片。支援的圖片文件格式為：BMP、EMF、EMZ、GIF、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")

獲取工作表屬性

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 屬性用以設定單色列印 true 或 false，默認值為 false 關閉。

• 例如，將名為 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) SetDefinedName(definedName *DefinedName) error

根據給定的名稱和引用區域設定名稱，默認範圍是活頁簿。例如：

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

工作表的列印區域和列印標題設定:

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)
}

獲取名稱

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

獲取作用範圍內的活頁簿和工作表的名稱列表。

刪除名稱

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

根據給定的名稱和名稱作用範圍刪除已定義的名稱，默認名稱的作用範圍為活頁簿。例如：

err := f.DeleteDefinedName(&excelize.DefinedName{
    Name:     "Amount",
    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) 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

取保護活頁簿，指定可選密碼參數以透過密碼驗證來取消活頁簿保護。