Рабочая книга

Параметры определяют параметры чтения и записи электронных таблиц.

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 указывает, применять ли числовой формат для значения ячейки или получить необработанное значение.

UnzipSizeLimit указывает предел размера распакованного архива в байтах при открытии электронной таблицы, это значение должно быть больше или равно UnzipXMLSizeLimit, ограничение размера по умолчанию составляет 16ГБ.

UnzipXMLSizeLimit указывает предел памяти при распаковке рабочего листа в байтах, XML рабочего листа будет извлечен во временный каталог системы, когда размер файла превышает это значение, это значение должно быть меньше или равно UnzipSizeLimit, значение по умолчанию - 16МБ.

ShortDatePattern указывает код формата короткого числа даты. В приложениях для работы с электронными таблицами форматы даты отображают порядковые номера даты и времени как значения даты. Форматы даты, начинающиеся со звездочки (*), соответствуют изменениям в региональных параметрах даты и времени, указанных для операционной системы. Форматы без звездочки не зависят от настроек операционной системы. ShortDatePattern, используемый для указания применяемых форматов даты, которые начинаются со звездочки.

LongDatePattern определяет код формата длинного числа даты.

LongTimePattern определяет код формата длинного числа.

CultureInfo указывает код страны для применения встроенного кода формата номера языка, который влияет на настройки местного языка системы.

HeaderFooterImagePositionType тип положения изображения верхнего и нижнего колонтитула.

type HeaderFooterImagePositionType byte

В этом разделе определяется перечисление типов позиций изображений верхнего и нижнего колонтитула рабочего листа.

const (
    HeaderFooterImagePositionLeft HeaderFooterImagePositionType = iota
    HeaderFooterImagePositionCenter
    HeaderFooterImagePositionRight
)

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
}

Создать документ Excel

func NewFile(opts ...Options) *File

NewFile предоставляет функцию для создания нового файла по умолчанию. Вновь созданная рабочая книга по умолчанию будет содержать таблицу с именем Sheet1. Например:

Открыть

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

OpenFile берет имя файла электронной таблицы и возвращает для него заполненную структуру файла электронной таблицы. Например, откройте электронную таблицу с защитой паролем:

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 предоставляет функцию для переопределения файла xlsx с исходным путем.

Сохранить как

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

SaveAs предоставляет функцию для создания или обновления файла xlsx по предоставленному пути.

Закрыть книгу

func (f *File) Close() error

Close закрывает и очищает открытый временный файл для электронной таблицы.

Создать рабочий лист

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

NewSheet предоставляет функцию для создания нового листа по заданному имени рабочего листа и возвращает индекс листов в книге (электронной таблице) после его добавления. Обратите внимание, что при создании нового файла электронной таблицы будет создан рабочий лист по умолчанию с именем Sheet1.

Удалить рабочий лист

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

DeleteSheet предоставляет функцию для удаления рабочего листа в рабочей книге по заданному имени рабочего листа, имена листов не чувствительны к регистру. Используйте этот метод с осторожностью, так как это повлияет на изменения в ссылках, таких как формулы, диаграммы и т. д. Если есть какое-либо ссылочное значение удаленного рабочего листа, это вызовет ошибку файла при его открытии. Эта функция будет недействительна, если останется только один рабочий лист.

Переместить рабочий лист

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

MoveSheet перемещает лист в указанное положение в рабочей книге. Функция перемещает исходный лист перед целевым листом. После перемещения другие листы будут смещены влево или вправо. Если лист уже находится в целевой позиции, функция не выполнит никаких действий. Не то чтобы эта функция разгруппировала все листы после перемещения. Например, переместите Лист2 перед Лист1:

err := f.MoveSheet("Лист2", "Лист1")

Лист копирования

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

CopySheet предоставляет функцию для дублирования рабочего листа путем указания индекса источника и целевого листа. Обратите внимание, что в настоящее время не поддерживается дублирование книг, содержащих таблицы, диаграммы или изображения. Например:

// Лист1 уже существует...
index, err := f.NewSheet("Лист2")
if err != nil {
    fmt.Println(err)
    return
}
err := f.CopySheet(1, index)

Рабочие листы группы

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

GroupSheets предоставляет функцию для группировки листов по заданным именам листов. Рабочие листы групп должны содержать активный рабочий лист.

Разгруппировать листы

func (f *File) UngroupSheets() error

UngroupSheets предоставляет функцию для разгруппировки листов.

Фон рабочего листа

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

SetSheetBackground предоставляет функцию для установки фонового изображения по заданному имени рабочего листа и пути к файлу. Поддерживаемые типы изображений: BMP, EMF, EMZ, GIF, JPEG, JPG, PNG, SVG, TIF, TIFF, WMF и WMZ.

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

SetSheetBackgroundFromBytes предоставляет функцию для установки фонового изображения по заданному имени рабочего листа, имени расширения и данным изображения. Поддерживаемые типы изображений: BMP, EMF, EMZ, GIF, JPEG, JPG, PNG, SVG, TIF, TIFF, WMF и WMZ.

Установить рабочий лист по умолчанию

func (f *File) SetActiveSheet(index int)

SetActiveSheet предоставляет функцию для установки активного листа книги по умолчанию по заданному индексу. Обратите внимание, что активный индекс отличается от идентификатора, возвращаемого функцией GetSheetMap. Оно должно быть больше или равно 0 и меньше общего числа листов.

Получить активный индекс листа

func (f *File) GetActiveSheetIndex() int

GetActiveSheetIndex предоставляет функцию для получения активного листа XLSX. Если не найден, активный лист вернет целое число 0.

Сделать лист видимым

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

SetSheetVisible предоставляет функцию для установки рабочего листа, видимого по заданному имени рабочего листа. Рабочая книга должна содержать хотя бы одну видимую рабочую таблицу. Если данный лист был активирован, этот параметр будет недействительным. Третий необязательный параметр veryHidden работает только тогда, когда visible имеет значение false.

Например, скрыть Лист1:

err := f.SetSheetVisible("Лист1", false)

Получить рабочий лист видимым

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

GetSheetVisible предоставляет функцию для отображения рабочего листа по заданному имени. Например, получить видимое состояние Лист1:

visible, err := f.GetSheetVisible("Лист1")

Установить свойства листа

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

SetSheetProps предоставляет функцию для задания свойств листа. Можно задать следующие свойства:

Например, сделать строки на листе по умолчанию скрытыми:

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)

GetSheetProps предоставляет функцию для получения свойств листа. Можно задать следующие свойства:

Задать свойства представления листа

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

SetSheetView задает свойства представления листа. viewIndex может быть отрицательным, и если это так, то отсчитывается в обратном порядке (-1 - последнее представление).

Получить свойства вида листа

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

GetSheetView получает значение свойств представления листа. viewIndex может быть отрицательным, и если это так, то отсчитывается в обратном порядке (-1 - последнее представление).

Установить макет страницы листа

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

SetPageLayout предоставляет функцию для установки макета страницы листа Доступные Варианты:

Size предоставляет метод для установки размера бумаги на листе, по умолчанию размер листа составляет "Письменная бумага (8.5 дюйм × 11 дюйм)". Ниже показан формат бумаги, отсортированный по номеру индекса Excelize:

Orientation указанная ориентация листа, по умолчанию — portrait. Возможные значения для этого поля — portrait и landscape.

FirstPageNumber указывает номер первой печатной страницы. Если значение не указано, то предполагается «автоматический».

AdjustTo указывает масштабирование печати. Этот атрибут ограничен значениями в диапазоне от 10 (10%) до 400 (400%). Этот параметр переопределяется, когда используются FitToWidth и/или FitToHeight.

FitToHeight указал количество вертикальных страниц, на которые можно поместиться.

FitToWidth указывал количество горизонтальных страниц, на которые можно поместиться.

BlackAndWhite указал печать черно-белую.

PageOrder определяет порядок нескольких страниц. Принимаемые значения: overThenDown и 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)

GetPageLayout предоставляет функцию для получения макета страницы листа.

Задать поля страницы листа

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

SetPageMargins предоставляет функцию для установки полей страницы рабочего листа. Доступные Варианты:

Получить поля страницы листа

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

GetPageMargins предоставляет функцию для получения полей страницы рабочего листа.

Установить свойства книги

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

SetWorkbookProps предоставляет функцию для установки свойств книги. Доступные Варианты:

Получить свойства книги

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

GetWorkbookProps предоставляет функцию для получения свойств книги.

Установить верхний и нижний колонтитулы

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

SetHeaderFooter предоставляет функцию установки верхних и нижних колонтитулов по заданному имени рабочего листа и управляющим символам.

Верхние и нижние колонтитулы указываются с помощью следующих полей настроек:

Следующие коды форматирования могут использоваться в 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

AddHeaderFooterImage предоставляет механизм для установки графики, на которую можно ссылаться в определениях верхнего и нижнего колонтитула с помощью &G, поддерживаемые типы изображений: EMF, EMZ, GIF, JPEG, JPG, PNG, SVG, TIF, TIFF, WMF и WMZ.

Установить определенное имя

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

SetDefinedName предоставляет функцию для установки определенных имен рабочей книги или рабочего листа. Если не указано scopr, областью по умолчанию является книга. Например:

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

Если вы заполните свойство 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)
}

Получить определенное имя

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

GetDefinedName предоставляет функцию для получения определенных имен рабочей книги или рабочего листа.

Удалить определенное имя

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

DeleteDefinedName предоставляет функцию для удаления определенных имен рабочей книги или рабочего листа. Если не указана область, областью по умолчанию является рабочая книга. Например:

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

Установить свойства приложения

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

SetAppProps предоставляет функцию для установки свойств приложения документа. Можно установить следующие свойства:

Например:

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)

GetAppProps предоставляет функцию для получения свойств приложения документа.

Установить свойства документа

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

SetDocProps предоставляет функцию для установки основных свойств документа. Свойства, которые можно установить:

Например:

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)

GetDocProps предоставляет функцию для получения основных свойств документа.

Установить свойства расчета

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

SetCalcProps предоставляет функцию для установки свойств расчета.

Необязательное значение свойства CalcMode: manual, auto или autoNoTable.

Необязательное значение свойства RefMode: A1 или R1C1.

Получить свойства расчета

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

GetCalcProps предоставляет функцию для получения свойств расчета.

Защитить книгу

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

ProtectWorkbook предоставляет функцию для предотвращения случайного или преднамеренного изменения, перемещения или удаления данных в книге другими пользователями. В необязательном поле AlgorithmName указывается хеш-алгоритм, поддерживается XOR, MD4, MD5, SHA-1, SHA2-56, 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

UnprotectWorkbook предоставляет функцию для снятия защиты книги, для которой указан необязательный параметр пароля, чтобы снять защиту книги с проверкой пароля.