儲存格

《Excelize 權威指南》圖書出版，網路購買方式：人民郵電出版社 | 異步社區 | 天貓 | 京東 | 當當 | 亞馬遜 | 微店 | 抖音

RichTextRun 定義了富文本的屬性。

type RichTextRun struct {
    Font *Font
    Text string
}

HyperlinkOpts 用來指定可選的超鏈接屬性，例如要顯示的文字與螢幕提示文字。

type HyperlinkOpts struct {
    Display *string
    Tooltip *string
}

FormulaOpts 用於在 SetCellFormula 函式中指定設定特殊公式類型。

type FormulaOpts struct {
    Type *string // 公式類型
    Ref  *string // 共享公式引用
}

設定儲存格的值

func (f *File) SetCellValue(sheet, cell string, value interface{}) error

根據給定的工作表名和儲存格坐標設定儲存格的值。此功能是併發安全的。指定的坐標不應在表格的第一列範圍，使用字符文本設定複數。

請注意，此函式默認為 time.Time 類型的儲存格的值設定 m/d/yy h:mm 數字格式，您可透過 SetCellStyle 更改該設定。若您需設定無法透過 Go 語言 time.Time 類型表示的 Excel 特殊日期，例如 1900 年 1 月 0 日或 1900 年 2 月 29 日，請先設定儲存格的值為 0 或 60，再為其設定具有日期數字格式的樣式。

設定布林型值

func (f *File) SetCellBool(sheet, cell string, value bool) error

根據給定的工作表名和儲存格坐標設定布林型儲存格的值。

設定默認字符型值

func (f *File) SetCellDefault(sheet, cell, value string) error

根據給定的工作表名和儲存格坐標設定字符型儲存格的值，字符將不會進行特殊字符過濾。

設定整數

func (f *File) SetCellInt(sheet, cell string, value int64) error

根據給定的工作表名和儲存格坐標設定整數儲存格的值。

設定無符號整型值

func (f *File) SetCellUint(sheet, cell string, value uint64) error

根據給定的工作表名和儲存格坐標設定無符號整型儲存格的值。

設定浮點數

func (f *File) SetCellFloat(sheet, cell string, value float64, precision, bitSize int) error

根據給定的工作表名、儲存格坐標、浮點數、浮點數尾數部分精度和浮點數類型設定浮點型儲存格的值。

設定字符型值

func (f *File) SetCellStr(sheet, cell, value string) error

根據給定的工作表名和儲存格坐標設定字符型儲存格的值，字符將會進行特殊字符過濾，並且字符串的累計長度應不超過 32767，多餘的字符將會被略過。

設定儲存格樣式

func (f *File) SetCellStyle(sheet, topLeftCell, bottomRightCell string, styleID int) error

根據給定的工作表名、儲存格坐標區域和樣式索引設定儲存格的值。此功能是併發安全的。樣式索引可以透過 NewStyle 函式獲取。注意，在同一個坐標區域內的 diagonalDown 和 diagonalUp 需要保持色彩一致。SetCellStyle 將覆蓋儲存格的已有樣式，而不會將樣式與已有樣式疊加或合併。

• 例1，為名為 Sheet1 的工作表 D7 儲存格設定外框樣式：

style, err := f.NewStyle(&excelize.Style{
    Border: []excelize.Border{
        {Type: "left", Color: "0000FF", Style: 3},
        {Type: "top", Color: "00FF00", Style: 4},
        {Type: "bottom", Color: "FFFF00", Style: 5},
        {Type: "right", Color: "FF0000", Style: 6},
        {Type: "diagonalDown", Color: "A020F0", Style: 8},
        {Type: "diagonalUp", Color: "A020F0", Style: 8},
    },
})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "D7", "D7", style)

儲存格 D7 的四個外框被設定了不同的樣式和色彩，這與調用 NewStyle 函式時的參數有關，需要設定不同的樣式可參考該章節的文檔。

• 例2，為名為 Sheet1 的工作表 D7 儲存格設定漸層樣式：

style, err := f.NewStyle(&excelize.Style{
    Fill: excelize.Fill{Type: "gradient", Color: []string{"FFFFFF", "E0EBF5"}, Shading: 1},
})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "D7", "D7", style)

儲存格 D7 被設定了漸層效果的色彩填滿，漸層填滿效果與調用 NewStyle 函式時的參數有關，需要設定不同的樣式可參考該章節的文檔。

• 例3，為名為 Sheet1 的工作表 D7 儲存格設定純色填滿：

style, err := f.NewStyle(&excelize.Style{
    Fill: excelize.Fill{Type: "pattern", Color: []string{"E0EBF5"}, Pattern: 1},
})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "D7", "D7", style)

儲存格 D7 被設定了純色填滿。

• 例4，為名為 Sheet1 的工作表 D7 儲存格設定字符間距與旋轉角度：

f.SetCellValue("Sheet1", "D7", "樣式")
style, err := f.NewStyle(&excelize.Style{
    Alignment: &excelize.Alignment{
        Horizontal:      "center",
        Indent:          1,
        JustifyLastLine: true,
        ReadingOrder:    0,
        RelativeIndent:  1,
        ShrinkToFit:     true,
        TextRotation:    45,
        Vertical:        "",
        WrapText:        true,
    },
})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "D7", "D7", style)

• 例5，Excel 中的日期和時間用實數表示，例如 2017/7/4 12:00:00 PM 可以用數字 42920.5 來表示。為名為 Sheet1 的工作表 D7 儲存格設定時間格式：

f.SetCellValue("Sheet1", "D7", 42920.5)
f.SetColWidth("Sheet1", "D", "D", 13)
style, err := f.NewStyle(&excelize.Style{NumFmt: 22})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "D7", "D7", style)

儲存格 D7 被設定了時間格式。注意，當應用了時間格式的儲存格寬度過窄無法完整展示時會顯示為 ####，可以拖拽調整欄寬或者透過調用 SetColWidth 函式設定欄寬到合適的大小使其正常顯示。

• 例6，為名為 Sheet1 的工作表 D7 儲存格設定字型、字號、色彩和傾斜樣式：

f.SetCellValue("Sheet1", "D7", "Excel")
style, err := f.NewStyle(&excelize.Style{
    Font: &excelize.Font{
        Bold:   true,
        Italic: true,
        Family: "Times New Roman",
        Size:   36,
        Color:  "777777",
    },
})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "D7", "D7", style)

• 例7，鎖定並隱藏名為 Sheet1 的工作表 D7 儲存格：

style, err := f.NewStyle(&excelize.Style{
    Protection: &excelize.Protection{
        Hidden: true,
        Locked: true,
    },
})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "D7", "D7", style)

要鎖定儲存格或隱藏公式，請保護工作表。在「審閱」選項卡上，單擊「保護工作表」。

設定超鏈接

func (f *File) SetCellHyperLink(sheet, cell, link, linkType string, opts ...HyperlinkOpts) error

根據給定的工作表、儲存格坐標、鏈接資源和資源類別設定儲存格的超鏈接。資源類別分為外部鏈接地址 External 和活頁簿內部位置鏈接 Location 兩種。每個工作表中的包含最大超鏈接限制為 65530 個。該方法僅設定儲存格的超鏈接而不影響儲存格的值，若需設定儲存格的值，請透過 SetCellStyle 或 SetSheetRow 等函式另行設定。

• 例1，為名為 Sheet1 的工作表 A3 儲存格添加外部鏈接：

display, tooltip := "https://github.com/xuri/excelize", "Excelize on GitHub"
if err := f.SetCellHyperLink("Sheet1", "A3",
    "https://github.com/xuri/excelize", "External", excelize.HyperlinkOpts{
        Display: &display,
        Tooltip: &tooltip,
    }); err != nil {
    fmt.Println(err)
}
// 為儲存格設定字型和底線樣式
style, err := f.NewStyle(&excelize.Style{
    Font: &excelize.Font{Color: "1265BE", Underline: "single"},
})
if err != nil {
    fmt.Println(err)
}
err = f.SetCellStyle("Sheet1", "A3", "A3", style)

• 例2，為名為 Sheet1 的工作表 A3 儲存格添加內部位置鏈接：

err := f.SetCellHyperLink("Sheet1", "A3", "Sheet1!A40", "Location")

設定富文本格式

func (f *File) SetCellRichText(sheet, cell string, runs []RichTextRun) error

根據給定的工作表、儲存格坐標和富文本格式為指定儲存格設定富文本。

例如，在名為 Sheet1 的工作表 A1 儲存格設定富文本格式：

package main

import (
    "fmt"

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

func main() {
    f := excelize.NewFile()
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    if err := f.SetRowHeight("Sheet1", 1, 35); err != nil {
        fmt.Println(err)
        return
    }
    if err := f.SetColWidth("Sheet1", "A", "A", 44); err != nil {
        fmt.Println(err)
        return
    }
    if err := f.SetCellRichText("Sheet1", "A1", []excelize.RichTextRun{
        {
            Text: "bold",
            Font: &excelize.Font{
                Bold:   true,
                Color:  "2354E8",
                Family: "Times New Roman",
            },
        },
        {
            Text: " and ",
            Font: &excelize.Font{
                Family: "Times New Roman",
            },
        },
        {
            Text: "italic ",
            Font: &excelize.Font{
                Bold:   true,
                Color:  "E83723",
                Italic: true,
                Family: "Times New Roman",
            },
        },
        {
            Text: "text with color and font-family,",
            Font: &excelize.Font{
                Bold:   true,
                Color:  "2354E8",
                Family: "Times New Roman",
            },
        },
        {
            Text: "\r\nlarge text with ",
            Font: &excelize.Font{
                Size:  14,
                Color: "AD23E8",
            },
        },
        {
            Text: "strike",
            Font: &excelize.Font{
                Color:  "E89923",
                Strike: true,
            },
        },
        {
            Text: " superscript",
            Font: &excelize.Font{
                Color:     "DBC21F",
                VertAlign: "superscript",
            },
        },
        {
            Text: " and ",
            Font: &excelize.Font{
                Size:      14,
                Color:     "AD23E8",
                VertAlign: "baseline",
            },
        },
        {
            Text: "underline",
            Font: &excelize.Font{
                Color:     "23E833",
                Underline: "single",
            },
        },
        {
            Text: " subscript.",
            Font: &excelize.Font{
                Color:     "017505",
                VertAlign: "subscript",
            },
        },
    }); err != nil {
        fmt.Println(err)
        return
    }
    style, err := f.NewStyle(&excelize.Style{
        Alignment: &excelize.Alignment{
            WrapText: true,
        },
    })
    if err != nil {
        fmt.Println(err)
        return
    }
    if err := f.SetCellStyle("Sheet1", "A1", "A1", style); err != nil {
        fmt.Println(err)
        return
    }
    if err := f.SaveAs("Book1.xlsx"); err != nil {
        fmt.Println(err)
    }
}

獲取富文本格式

func (f *File) GetCellRichText(sheet, cell string) ([]RichTextRun, error)

根據給定的工作表、儲存格坐標獲取指定儲存格的富文本格式。

獲取儲存格的值

func (f *File) GetCellValue(sheet, cell string, opts ...Options) (string, error)

根據給定的工作表和儲存格坐標獲取儲存格的值，傳回值將轉換為 string 類別。此功能是併發安全的。如果可以將儲存格格式應用於儲存格的值，將傳回應用後的值，否則將傳回原始值。合併區域內所有儲存格的值都相同。

獲取儲存格數據類型

func (f *File) GetCellType(sheet, cell string) (CellType, error)

根據給定的工作表、儲存格坐標獲取指定儲存格的數據類型。

按欄獲取全部儲存格的值

func (f *File) GetCols(sheet string, opts ...Options) ([][]string, error)

根據給定的工作表名按欄獲取該工作表上全部儲存格的值，以二維數組形式傳回，其中儲存格的值將轉換為 string 類別。如果可以將儲存格格式應用於儲存格的值，將使用應用後的值，否則將使用原始值。

例如，按欄獲取並遍歷輸出名為 Sheet1 的工作表上的所有儲存格的值：

cols, err := f.GetCols("Sheet1")
if err != nil {
    fmt.Println(err)
    return
}
for _, col := range cols {
    for _, rowCell := range col {
        fmt.Print(rowCell, "\t")
    }
    fmt.Println()
}

按列獲取全部儲存格的值

func (f *File) GetRows(sheet string, opts ...Options) ([][]string, error)

根據給定的工作表名按列獲取該工作表上全部儲存格的值，以二維數組形式傳回，其中儲存格的值將轉換為 string 類別。如果可以將儲存格格式應用於儲存格的值，將使用應用後的值，否則將使用原始值。GetRows 獲取帶有值或公式儲存格的列，列尾連續為空的儲存格將被跳過，每列中的儲存格數目可能不同。

例如，按列獲取並遍歷輸出名為 Sheet1 的工作表上的所有儲存格的值：

rows, err := f.GetRows("Sheet1")
if err != nil {
    fmt.Println(err)
    return
}
for _, row := range rows {
    for _, colCell := range row {
        fmt.Print(colCell, "\t")
    }
    fmt.Println()
}

獲取超鏈接存儲格

func (f *File) GetHyperLinkCells(sheet, linkType string) ([]string, error)

根據給定的工作表名和資源類型獲取超鏈接存儲格坐標。可選參數 linkType 用於指定超鏈接的類型，可選值為用於表示外部鏈接地址的 External、活頁簿內部位置鏈接的 Location，和表示無超鏈接的 None。如果 linkType 的值為空，該函式將傳回工作表中全部超鏈接存儲格的坐標。

獲取超鏈接

func (f *File) GetCellHyperLink(sheet, cell string) (bool, string, error)

根據給定的工作表名和儲存格坐標獲取儲存格超鏈接，如果該儲存格存在超鏈接，將傳回 true 和鏈接地址，否則將傳回 false 和空的鏈接地址。

例如，獲取名為 Sheet1 的工作表上坐標為 H6 儲存格的超鏈接：

link, target, err := f.GetCellHyperLink("Sheet1", "H6")

獲取樣式索引

func (f *File) GetCellStyle(sheet, cell string) (int, error)

根據給定的工作表名和儲存格坐標獲取儲存格樣式索引，獲取到的索引可以在設定儲存格樣式時，作為調用 SetCellStyle 函式的參數使用。

合併儲存格

func (f *File) MergeCell(sheet, topLeftCell, bottomRightCell string) error

根據給定的工作表名和儲存格坐標區域合併儲存格。合併區域內僅保留左上角儲存格的值，其他儲存格的值將被略過。例如，合併名為 Sheet1 的工作表上 D3:E9 區域內的儲存格：

err := f.MergeCell("Sheet1", "D3", "E9")

如果給定的儲存格坐標區域與已有的其他合併儲存格相重疊，已有的合併儲存格將會被刪除。

取消合併儲存格

func (f *File) UnmergeCell(sheet, topLeftCell, bottomRightCell string) error

根據給定的工作表名和儲存格坐標區域取消合併儲存格。例如，取消合併名為 Sheet1 的工作表上 D3:E9 區域內的儲存格：

err := f.UnmergeCell("Sheet1", "D3", "E9")

如果給定的儲存格坐標區域包含多個合併儲存格，則全部合併儲存格都將被取消合併。

獲取合併儲存格

func (f *File) GetMergeCells(sheet string, withoutValues ...bool) ([]MergeCell, error)

根據給定的工作表名獲取全部合併儲存格的坐標區域和值。如果將可選參數 withoutValues 的值設定為 true，將僅解析合併儲存格的區域，而不會獲取合併儲存格的值。例如，獲取名為 Sheet1 的工作表中的全部合併儲存格：

mergeCells, err := f.GetMergeCells("Sheet1")

如果你希望獲取合併儲存格時，不包含合併儲存格的值，可使用以下代碼：

mergeCells, err := f.GetMergeCells("Sheet1", true)

獲取合併儲存格的值

func (m *MergeCell) GetCellValue() string

GetCellValue 傳回合併儲存格的值。

獲取合併儲存格區域左上角儲存格坐標

func (m *MergeCell) GetStartAxis() string

GetStartAxis 傳回合併儲存格區域左上角儲存格的坐標，例如：C2。

獲取合併儲存格區域右下角儲存格坐標

func (m *MergeCell) GetEndAxis() string

GetEndAxis 傳回合併儲存格區域右下角儲存格的坐標，例如：D4。

獲取圖片儲存格

func (f *File) GetPictureCells(sheet string) ([]string, error)

根據給定的工作表名稱獲取該工作表中，包含圖片的全部儲存格坐標。

添加註解

func (f *File) AddComment(sheet string, comment Comment) error

根據給定的工作表名稱、儲存格坐標和樣式參數（作者與文本信息）添加註解。作者信息最大長度為 255 個字符，最大文本內容長度為 32512 個字符，超出該範圍的字符將會被略過，並且每個存儲格僅能有一個註解，如果向已存在註解的存儲格添加註解，則會傳回錯誤。例如，為 Sheet1!A3 儲存格添加註解：

err := f.AddComment("Sheet1", excelize.Comment{
    Cell:   "A3",
    Author: "Excelize",
    Paragraph: []excelize.RichTextRun{
        {Text: "Excelize: ", Font: &excelize.Font{Bold: true}},
        {Text: "This is a comment."},
    },
})

獲取註解

func (f *File) GetComments(sheet string) ([]Comment, error)

根據給定的工作表名稱獲取工作表中的所有儲存格註解。

刪除註解

func (f *File) DeleteComment(sheet, cell string) error

根據給定的工作表名稱、儲存格坐標刪除註解。例如，刪除 Sheet1!A30 儲存格註解：

err := f.DeleteComment("Sheet1", "A30")

添加略過錯誤

func (f *File) AddIgnoredErrors(sheet, rangeRef string, ignoredErrorsType IgnoredErrorsType) error

根據給定的工作表名稱、儲存格坐標範圍和錯誤類型略過指定範圍內儲存格中的錯誤。例如，略過 Sheet1 工作表中 D15 C18:D19 範圍內儲存格中「數值儲存成文字」錯誤：

err := f.AddIgnoredErrors("Sheet1", "D15 C18:D19", excelize.IgnoredErrorsNumberStoredAsText)

設定公式

func (f *File) SetCellFormula(sheet, cell, formula string, opts ...FormulaOpts) error

根據給定的工作表名和儲存格坐標設定該儲存格上的公式。公式的結果會在工作表被 Office Excel 應用程式開啓時計算，或透過 CalcCellValue 函式計算儲存格的值。若 Excel 應用程式開啓活頁簿後未對設定的儲存格公式進行計算，請在設定公式後調用 UpdateLinkedValue 清除儲存格緩存。

• 例1，為名為 Sheet1 的工作表 A3 儲存格設定普通公式 =SUM(A1,B1)：

err := f.SetCellFormula("Sheet1", "A3", "SUM(A1,B1)")

• 例2，為名為 Sheet1 的工作表 A3 儲存格設定一維縱向常量數組（欄數組）公式 1;2;3:

err := f.SetCellFormula("Sheet1", "A3", "{1;2;3}")

• 例3，為名為 Sheet1 的工作表 A3 儲存格設定一維橫向常量數組（列數組）公式 "a","b","c":

err := f.SetCellFormula("Sheet1", "A3", "{\"a\",\"b\",\"c\"}")

• 例4，為名為 Sheet1 的工作表 A3 儲存格設定平面常量數組公式 {1,2;"a","b"}:

formulaType, ref := excelize.STCellFormulaTypeArray, "A3:A3"
err := f.SetCellFormula("Sheet1", "A3", "{1,2;\"a\",\"b\"}",
    excelize.FormulaOpts{Ref: &ref, Type: &formulaType})

• 例5，為名為 Sheet1 的工作表 A3 儲存格設定區域數組公式 A1:A2:

formulaType, ref := excelize.STCellFormulaTypeArray, "A3:A3"
err := f.SetCellFormula("Sheet1", "A3", "A1:A2",
    excelize.FormulaOpts{Ref: &ref, Type: &formulaType})

• 例6，為名為 Sheet1 的工作表 C1:C5 區域的儲存格設定共享公式 =A1+B1，其中 C1 為主儲存格:

formulaType, ref := excelize.STCellFormulaTypeShared, "C1:C5"
err := f.SetCellFormula("Sheet1", "C1", "A1+B1",
    excelize.FormulaOpts{Ref: &ref, Type: &formulaType})

• 例7，為名為 Sheet1 的工作表 C2 儲存格設定表格公式 =SUM(Table1[[A]:[B]]):

package main

import (
    "fmt"

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

func main() {
    f := excelize.NewFile()
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    for idx, row := range [][]interface{}{{"A", "B", "C"}, {1, 2}} {
        if err := f.SetSheetRow("Sheet1", fmt.Sprintf("A%d", idx+1), &row); err != nil {
            fmt.Println(err)
            return
        }
    }
    if err := f.AddTable("Sheet1",
        &excelize.Table{
            Range:     "A1:C2",
            Name:      "Table1",
            StyleName: "TableStyleMedium2",
        }); err != nil {
        fmt.Println(err)
        return
    }
    formulaType := excelize.STCellFormulaTypeDataTable
    if err := f.SetCellFormula("Sheet1", "C2", "SUM(Table1[[A]:[B]])",
        excelize.FormulaOpts{Type: &formulaType}); err != nil {
        fmt.Println(err)
        return
    }
    if err := f.SaveAs("Book1.xlsx"); err != nil {
        fmt.Println(err)
    }
}

獲取公式

func (f *File) GetCellFormula(sheet, cell string) (string, error)

根據給定的工作表名和儲存格坐標獲取該儲存格上的公式。

計算儲存格的值

func (f *File) CalcCellValue(sheet, cell string, opts ...Options) (string, error)

根據給定的工作表名和儲存格坐標計算包含公式儲存格的值。該方法目前正在開發中，尚未支援反覆運算、隱式交集、顯式交集、數組函式、數組函式、表格函式和其他部分函式。

支援的公式函式列表如下：