活頁簿

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

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

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