xlsx

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 18, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package xlsx reads and writes Microsoft Excel (SpreadsheetML) workbooks via the Open Packaging Conventions. It supports opening existing .xlsx files, editing cells, styles, sheets, and images, and creating workbooks from scratch, preserving unmodified parts byte-for-byte on round-trip.

Pivot slicers and timelines are read-only: Sheet.Slicers/Workbook.Slicers and Sheet.Timelines/Workbook.Timelines expose the slicers and timelines of an opened workbook (name, caption, source pivot field and controlled pivot tables), and their definition/cache parts plus the worksheet/workbook extension references round-trip byte-for-byte. Creating them is not yet supported: a slicer or timeline is an on-sheet drawing whose creation also requires injecting relationship-bearing x14/x15 extension lists into the shared workbook and worksheet parts at save time.

The feature surface is add-and-read, not add-remove. Comments, conditional formats, data validations, tables, images, charts, pivot tables, scenarios and OLE objects can be added and read back, but only sparkline groups have a removal API (SparklineGroup.Delete); the sheet-level Remove*/Clear* methods cover the auto-filter, its column predicates, the sort state, sheet protection, freeze panes and the print area/titles. A replace-style edit of anything else therefore accretes rather than replaces, so rebuild the sheet instead of editing in place when a feature must go away.

A Workbook is not safe for concurrent use. A single Workbook, and the sheets and cells reached through it, must be confined to one goroutine, or all access must be guarded by external synchronization. In particular Save, SaveBytes, and SaveTo mutate shared state while serializing, so they must not run concurrently with each other or with any mutation of the same Workbook. Distinct Workbook values may be used from different goroutines.

Index

Examples

Constants

View Source 
const (
	CondOpEqual              = "equal"
	CondOpNotEqual           = "notEqual"
	CondOpGreaterThan        = "greaterThan"
	CondOpGreaterThanOrEqual = "greaterThanOrEqual"
	CondOpLessThan           = "lessThan"
	CondOpLessThanOrEqual    = "lessThanOrEqual"
	CondOpBetween            = "between"
	CondOpNotBetween         = "notBetween"
)

Comparison operators for a cellIs rule (NewCellIsRule). Between and NotBetween take two formula operands; the others take one.

View Source 
const (
	CondTextContains    = "containsText"
	CondTextNotContains = "notContains"
	CondTextBeginsWith  = "beginsWith"
	CondTextEndsWith    = "endsWith"
)

Operators for the containsText rule family (NewTextRule).

View Source 
const (
	FilterEqual              = "equal"
	FilterNotEqual           = "notEqual"
	FilterGreaterThan        = "greaterThan"
	FilterGreaterThanOrEqual = "greaterThanOrEqual"
	FilterLessThan           = "lessThan"
	FilterLessThanOrEqual    = "lessThanOrEqual"
)

Filter comparison operators (CT_CustomFilter operator, ST_FilterOperator). An empty operator means Equal.

View Source 
const (
	SortByValue     = "value"
	SortByCellColor = "cellColor"
	SortByFontColor = "fontColor"
	SortByIcon      = "icon"
)

Sort-by kinds (CT_SortCondition sortBy, ST_SortBy). An empty value means Value.

View Source 
const (
	OrientationDefault   = "default"
	OrientationPortrait  = "portrait"
	OrientationLandscape = "landscape"
)

Page orientation values for PageSetup.Orientation. An empty string leaves the attribute unset, which Excel treats as the default (portrait).

View Source 
const (
	ValidationErrorStop        = "stop"
	ValidationErrorWarning     = "warning"
	ValidationErrorInformation = "information"
)

Data-validation errorStyle values (ST_DataValidationErrorStyle): the alert behavior Excel applies when a cell fails validation.

View Source 
const (
	ViewNormal           = "normal"
	ViewPageLayout       = "pageLayout"
	ViewPageBreakPreview = "pageBreakPreview"
)

Sheet view modes for the sheetView view attribute, accepted by SetView and returned by View.

View Source 
const (
	SparklineLine    = "line"
	SparklineColumn  = "column"
	SparklineWinLoss = "winloss"
)

Sparkline group types accepted by AddSparklineGroup. Win/loss is Excel's "stacked" sparkline; the string constant hides that spelling from callers.

View Source 
const (
	NumberFormatGeneral  = 0
	NumberFormatInteger  = 1  // "0"
	NumberFormatDecimal  = 2  // "0.00"
	NumberFormatComma    = 3  // "#,##0"
	NumberFormatPercent  = 9  // "0%"
	NumberFormatDate     = 14 // "mm-dd-yy"
	NumberFormatTime     = 20 // "h:mm"
	NumberFormatDateTime = 22 // "m/d/yy h:mm"
	NumberFormatText     = 49 // "@"
)

Built-in number format IDs.

View Source 
const (
	BuiltinStyleNormal            uint32 = 0
	BuiltinStyleRowLevel          uint32 = 1
	BuiltinStyleColLevel          uint32 = 2
	BuiltinStyleComma             uint32 = 3
	BuiltinStyleCurrency          uint32 = 4
	BuiltinStylePercent           uint32 = 5
	BuiltinStyleCommaZero         uint32 = 6
	BuiltinStyleCurrencyZero      uint32 = 7
	BuiltinStyleHyperlink         uint32 = 8
	BuiltinStyleFollowedHyperlink uint32 = 9
	BuiltinStyleNote              uint32 = 10
	BuiltinStyleWarningText       uint32 = 11
	BuiltinStyleTitle             uint32 = 15
	BuiltinStyleHeading1          uint32 = 16
	BuiltinStyleHeading2          uint32 = 17
	BuiltinStyleHeading3          uint32 = 18
	BuiltinStyleHeading4          uint32 = 19
	BuiltinStyleInput             uint32 = 20
	BuiltinStyleOutput            uint32 = 21
	BuiltinStyleCalculation       uint32 = 22
	BuiltinStyleCheckCell         uint32 = 23
	BuiltinStyleLinkedCell        uint32 = 24
	BuiltinStyleTotal             uint32 = 25
	BuiltinStyleGood              uint32 = 26
	BuiltinStyleBad               uint32 = 27
	BuiltinStyleNeutral           uint32 = 28
	BuiltinStyleAccent1           uint32 = 29
	BuiltinStyleExplanatoryText   uint32 = 53
)

Built-in cell style IDs (CT_CellStyle builtinId, ST_BuiltinStyle). These name the styles Excel ships in the Cell Styles gallery ("Good", "Bad", "Heading 1" …); pass one as NamedStyle.BuiltinId when defining a style that mirrors a built-in.

View Source 
const (
	MaxRow = 1048576
	MaxCol = 16384
)

Worksheet grid limits (Excel 2007+): 1,048,576 rows by 16,384 columns (XFD).

Variables

View Source 
var (
	// ErrNotXLSX indicates the file is not a valid Excel file.
	ErrNotXLSX = errors.New("xlsx: not a valid Excel file")

	// ErrSheetNotFound indicates the requested sheet does not exist.
	ErrSheetNotFound = errors.New("xlsx: sheet not found")

	// ErrSheetIndex indicates an invalid sheet index.
	ErrSheetIndex = errors.New("xlsx: sheet index out of range")

	// ErrDuplicateSheetName indicates a sheet with the requested name (compared
	// case-insensitively, as Excel does) already exists in the workbook.
	// AddSheet reports it rather than quietly renaming the new sheet; derive a
	// free name with Workbook.UniqueSheetName when a suffix is what you want.
	ErrDuplicateSheetName = errors.New("xlsx: a sheet with that name already exists")

	// ErrInvalidCell indicates an invalid cell reference.
	ErrInvalidCell = errors.New("xlsx: invalid cell reference")

	// ErrInvalidRange indicates an invalid cell range.
	ErrInvalidRange = errors.New("xlsx: invalid range")

	// ErrNoSheets indicates an attempt to save a workbook with no sheets,
	// which Excel does not accept (a workbook requires at least one sheet).
	ErrNoSheets = errors.New("xlsx: workbook has no sheets")

	// ErrNoWorkbook indicates a sheet is not attached to a workbook, so an
	// operation that stores state at the workbook level (such as a print area or
	// print titles, which live in workbook-scoped defined names) cannot proceed.
	ErrNoWorkbook = errors.New("xlsx: sheet is not attached to a workbook")

	// ErrNotWorksheet indicates a worksheet operation (such as writing a cell) was
	// attempted on a non-worksheet sheet — a chartsheet, dialogsheet or
	// macrosheet. Such a sheet is preserved opaquely and has no worksheet cell
	// grid to mutate.
	ErrNotWorksheet = errors.New("xlsx: sheet is not a worksheet")
)
View Source 
var ErrNilWorkbook = errors.New("xlsx: source workbook is nil")

ErrNilWorkbook is returned when a copy operation is given a nil source workbook.

Functions

func CellRef 

func CellRef(row, col int) (string, error)

CellRef converts row and column indices (1-based) to a cell reference.

func FormatCellRef 

func FormatCellRef(row, col int) string

FormatCellRef creates a cell reference from 1-based row and column numbers. It returns "" for coordinates outside the worksheet grid rather than an invalid reference such as "5" (column 0).

func ParseCellRef 

func ParseCellRef(ref string) (row, col int, err error)

ParseCellRef parses a cell reference like "A1" into 1-based row and column numbers. It rejects references outside the worksheet grid and guards against integer overflow from pathologically long column strings.

func ValidateDefinedName added in v0.2.0 

func ValidateDefinedName(name string) error

ValidateDefinedName reports whether name is a legal Excel defined name. Excel refuses names that collide with an A1- or R1C1-style cell reference, names containing spaces or other characters outside letters, digits, ".", "_" and "\", names that do not begin with a letter, "_" or "\", and names longer than 255 characters. Such a name is accepted by the file format but rejected by Excel when the workbook is opened (C426).

func ValidateSheetName 

func ValidateSheetName(name string) error

ValidateSheetName reports whether name is a legal Excel sheet name: non-empty, at most 31 characters, containing none of \ / ? * [ ] :, and not beginning or ending with an apostrophe. It does not check uniqueness within a workbook.

Types

type ActiveXControl 

type ActiveXControl struct {
	// Name is the OPC part name of the control's ax:ocx XML part.
	Name string
	// ContentType is that part's content type (application/vnd.ms-office.activeX+xml).
	ContentType string
	// Data is the ax:ocx XML, carried verbatim.
	Data []byte
	// ClassID is the control server's COM class id (e.g.
	// "{8BD21D40-EC42-11CE-9E0D-00AA006002F3}"), best-effort from the part root.
	ClassID string
	// Persistence names how the control state is stored (e.g. "persistPropertyBag").
	Persistence string
	// BinaryName is the OPC part name of the control's persistence binary
	// (activeXN.bin), or "" when the control declares none.
	BinaryName string
	// BinaryData is the persistence binary, carried verbatim.
	BinaryData []byte
}

ActiveXControl is an ActiveX control embedded in a workbook: the ax:ocx control part (xl/activeX/activeXN.xml) plus its persistence binary (activeXN.bin). spine reads, enumerates, and preserves these parts verbatim; authoring the ActiveX persistence binary is out of scope.

type AlignmentStyle 

type AlignmentStyle struct {
	Horizontal string
	Vertical   string
	WrapText   bool
	Indent     int
	Rotation   int
	// ShrinkToFit shrinks the displayed text so it fits within the cell.
	ShrinkToFit bool
	// JustifyLastLine justifies the final line of a justified paragraph.
	JustifyLastLine bool
	// ReadingOrder controls text direction: 0 context-dependent, 1 left-to-right,
	// 2 right-to-left.
	ReadingOrder uint32
	// RelativeIndent is the relative indent used by dxf (differential) records;
	// it may be negative.
	RelativeIndent int
}

AlignmentStyle represents alignment styling.

type BorderSide 

type BorderSide struct {
	Style string
	Color string // hex color
}

BorderSide represents one side of a border.

type BorderStyle 

type BorderStyle struct {
	Left     *BorderSide
	Right    *BorderSide
	Top      *BorderSide
	Bottom   *BorderSide
	Diagonal *BorderSide
	// DiagonalUp / DiagonalDown select which diagonal(s) the Diagonal side is
	// drawn across (Excel's up/down diagonal border toggles).
	DiagonalUp   bool
	DiagonalDown bool
}

BorderStyle represents border styling.

type Cell 

type Cell struct {
	// contains filtered or unexported fields
}

Cell represents a cell in a worksheet.

func (*Cell) AddComment 

func (c *Cell) AddComment(author, text string) *Comment

AddComment adds a threaded comment authored by author to the cell, returning the new comment. Excel's back-compat behavior is matched: a threaded comment is created (so modern Excel shows the thread) together with a legacy note fallback (so older Excel still renders the text). The author is registered as a person, deduplicated by display name.

func (*Cell) Bool 

func (c *Cell) Bool() bool

Bool returns the cell value as a bool.

func (*Cell) Clear 

func (c *Cell) Clear()

Clear clears the cell value and formula.

func (*Cell) Comment 

func (c *Cell) Comment() *Comment

Comment returns the top-level comment anchored to the cell, or nil if the cell has none. A threaded comment takes precedence over a legacy note.

func (*Cell) DataValidation 

func (c *Cell) DataValidation() *DataValidation

DataValidation returns the validation rule whose range covers this cell, or nil if the cell has none. When several rules cover the cell (Excel allows this on hand-edited files) the first in document order is returned.

func (*Cell) Float 

func (c *Cell) Float() float64

Float returns the cell value as a float64.

func (*Cell) Formula 

func (c *Cell) Formula() string

Formula returns the cell formula. 

func (c *Cell) Hyperlink() *Hyperlink

Hyperlink returns the hyperlink anchored to this cell, or nil if the cell has none. When a hyperlink covers a range that includes the cell, that hyperlink is returned.

func (*Cell) Int 

func (c *Cell) Int() int

Int returns the cell value as an int.

func (*Cell) IsEmpty 

func (c *Cell) IsEmpty() bool

IsEmpty returns true if the cell has no value.

func (*Cell) Ref 

func (c *Cell) Ref() string

Ref returns the cell reference (e.g., "A1").

func (*Cell) RichText 

func (c *Cell) RichText() []TextRun

RichText returns the cell's text as formatting runs. A plain string cell (or an empty cell) returns a single unformatted run; a rich cell (inline or a shared string with runs) returns one TextRun per run. It returns nil for a truly empty cell.

func (*Cell) SetArrayFormula 

func (c *Cell) SetArrayFormula(formula, ref string)

SetArrayFormula sets the cell to a legacy (Ctrl+Shift+Enter) array formula spilling over ref, the range the formula fills — e.g. SetArrayFormula("A1:A3*B1:B3", "C1:C3"). This cell becomes the array master (`<f t="array" ref="C1:C3">`); Excel fills the other cells of ref when it recalculates. If this cell was the master of a shared-formula group its followers are first detached (see clearFormula) so they are not orphaned.

func (*Cell) SetBool 

func (c *Cell) SetBool(value bool)

SetBool sets the cell value to a bool.

func (*Cell) SetDynamicArrayFormula 

func (c *Cell) SetDynamicArrayFormula(formula, ref string)

SetDynamicArrayFormula sets the cell to a dynamic-array (spill) formula, the modern spilling form Excel writes for functions such as SORT, FILTER and UNIQUE. ref is the anchor cell (usually this cell's own reference); Excel grows the spill range from the anchor as the result changes. The formula is stored as `<f t="array" ref="…" aca="1" ca="1">`, the alwaysCalcArray / calculateCell marking Excel uses for a dynamic array.

Note: the cell-metadata linkage Excel adds for a dynamic array (a `cm` attribute pointing into xl/metadata.xml) is not synthesized here; Excel still evaluates the formula as a spilling array and rewrites the metadata itself on the next save.

func (*Cell) SetFloat 

func (c *Cell) SetFloat(value float64)

SetFloat sets the cell value to a float64. NaN and ±Inf are not representable as a numeric cell, so they are written as a #NUM! error cell rather than an invalid <v>NaN</v>.

func (*Cell) SetFormula 

func (c *Cell) SetFormula(formula string)

SetFormula sets the cell formula. If the cell was the master of a shared formula group, the group's followers are first converted to plain formulas (see clearFormula) so replacing the master does not orphan them. 

func (c *Cell) SetHyperlink(url string) *Hyperlink

SetHyperlink sets an external hyperlink on the cell pointing at url (e.g. "https://example.com"), replacing any existing hyperlink on the cell. The link is written as <hyperlink ref=... r:id=.../> with an External relationship in the sheet's .rels. It returns the new Hyperlink so a tooltip can be attached.

Works on both created and opened workbooks; a save wires the relationship and re-marshals the worksheet with the hyperlink.

func (*Cell) SetInt 

func (c *Cell) SetInt(value int)

SetInt sets the cell value to an int.

func (*Cell) SetInt64 

func (c *Cell) SetInt64(value int64)

SetInt64 sets the cell value to an int64, formatting it exactly rather than routing through float64 (which loses precision above 2^53). 

func (c *Cell) SetInternalHyperlink(location string) *Hyperlink

SetInternalHyperlink sets an internal hyperlink on the cell pointing at a location within the workbook (e.g. "Sheet2!A1"), replacing any existing hyperlink on the cell. Internal links carry a location attribute and need no relationship. It returns the new Hyperlink so a tooltip can be attached.

func (*Cell) SetNamedStyle 

func (c *Cell) SetNamedStyle(name string) error

SetNamedStyle applies a previously defined named style (see StyleManager.AddNamedStyle) to the cell by name.

An unknown name leaves the cell and the sheet untouched: the dirty flag is set by SetStyleIndex on the success path only, so a failed lookup cannot force the worksheet part to be regenerated on save (C544 shape).

func (*Cell) SetRichText 

func (c *Cell) SetRichText(runs []TextRun)

SetRichText sets the cell to a rich (multi-run) string, where each run may carry its own font formatting — e.g. a bold label followed by a normal value in the same cell: 

cell.SetRichText([]xlsx.TextRun{
    {Text: "Total: ", Font: &xlsx.FontStyle{Bold: true}},
    {Text: "1,234"},
})

The runs are stored inline in the worksheet (an inlineStr cell), so no shared-strings table is required.

func (*Cell) SetSharedFormula 

func (c *Cell) SetSharedFormula(formula, ref string) error

SetSharedFormula sets the cell to the master of a shared-formula group spanning ref, then fills every other cell of ref with a follower stub (`<f t="shared" si="N"/>`) that shares this master's index. This is the compact encoding Excel uses when one formula is copied down or across a range: only the master carries the formula text, and Excel derives each follower by translating the master's relative references by the follower's offset.

This cell must be the top-left (anchor) cell of ref, matching Excel's requirement that the master anchor the group; ref is returned unchanged as the master's ref attribute. A fresh, unused shared index is allocated for the group. If this cell was already a shared-formula master its old followers are detached first (see clearFormula).

func (*Cell) SetString 

func (c *Cell) SetString(value string)

SetString sets the cell value to a literal string, stored as an inline string (t="inlineStr"). The previous encoding t="str" is the CACHED FORMULA RESULT type and is not valid for literal strings (C129). Strings with leading or trailing whitespace are marshaled with xml:space="preserve" so the spaces survive an Excel round-trip.

func (*Cell) SetStyle 

func (c *Cell) SetStyle(style CellStyle) error

SetStyle creates a style from the given definition and applies it to the cell.

A rejected style (an out-of-range rotation or indent, a negative number-format id) leaves the cell and the sheet untouched: the dirty flag is set by SetStyleIndex on the success path only, so a failed call cannot force the worksheet part to be regenerated on save (C544 shape).

func (*Cell) SetStyleIndex 

func (c *Cell) SetStyleIndex(index uint32)

SetStyleIndex sets the cell's style index.

func (*Cell) SetTime 

func (c *Cell) SetTime(value time.Time)

SetTime sets the cell value to a time.Time, stored as an Excel serial date in the workbook's date system (see Time). The serial is computed from the wall-clock date/time in the value's own location, so the stored day does not shift by the zone offset.

Note: this sets only the numeric value, not a date number format, so the cell displays the raw serial number until a date format is applied via SetStyle.

func (*Cell) SetUint64 

func (c *Cell) SetUint64(value uint64)

SetUint64 sets the cell value to a uint64, formatting it exactly.

func (*Cell) SetValue 

func (c *Cell) SetValue(value interface{})

SetValue sets the cell value, automatically detecting the type.

func (*Cell) String 

func (c *Cell) String() string

String returns the cell value as a string.

func (*Cell) StyleIndex 

func (c *Cell) StyleIndex() *uint32

Style returns the cell's style index, or nil if not set.

func (*Cell) Time 

func (c *Cell) Time() time.Time

Time returns the cell value as a time.Time (in UTC).

Excel stores dates as serial numbers counting days from an epoch chosen by the workbook's date system: the default 1900 system (serial 1 is 1900-01-01, with Excel's fictitious 1900-02-29 leap day) or, when workbookPr/@date1904 is set — the historical Mac Excel default — the 1904 system (serial 0 is 1904-01-01, no fictitious leap day). The conversion follows the workbook the cell belongs to (C367).

A cell typed t="d" stores an ISO-8601 literal instead of a serial; it is parsed as such. A cell whose value is neither returns the zero time.

func (*Cell) Type 

func (c *Cell) Type() CellType

Type returns the cell type.

func (*Cell) Value 

func (c *Cell) Value() interface{}

Value returns the cell value as an interface{}. The dynamic type follows Type: string for CellTypeString, float64 for CellTypeNumber, time.Time for CellTypeDate, bool for CellTypeBoolean, CellError for CellTypeError, and nil for CellTypeEmpty. A formula cell yields its cached result typed the same way, or the formula text when no result is cached.

type CellError added in v0.2.0 

type CellError string

CellError is the value Cell.Value returns for an error cell (t="e"). It carries the Excel error literal — "#DIV/0!", "#N/A", "#REF!", … — and implements error, so an error cell is distinguishable from an empty one both by type switch and by errors.As (C548).

func (CellError) Error added in v0.2.0 

func (e CellError) Error() string

Error returns the Excel error literal, e.g. "#DIV/0!".

type CellStyle 

type CellStyle struct {
	Font      *FontStyle
	Fill      *FillStyle
	Border    *BorderStyle
	Alignment *AlignmentStyle
	// Format is a number format code string (e.g. "0.00" or a custom code).
	// It takes precedence over NumberFormatID when both are set.
	Format string
	// NumberFormatID applies a number format by its id, letting callers use
	// the built-in NumberFormat* constants (e.g. NumberFormatDate) directly
	// without spelling out the format code (C131). Zero means General.
	NumberFormatID int
	// Protection controls the cell's locked/hidden flags. It only takes effect
	// once the sheet itself is protected (see Sheet.Protect); on an unprotected
	// sheet every cell is editable regardless of this setting. A nil value
	// leaves the format's protection unset (Excel then treats the cell as
	// locked by default).
	Protection *ProtectionStyle
}

CellStyle represents the style of a cell.

type CellType 

type CellType int

CellType represents the type of value in a cell. 

const (
	CellTypeEmpty CellType = iota
	CellTypeString
	CellTypeNumber
	CellTypeBoolean
	CellTypeFormula
	CellTypeError
	CellTypeDate
)

type ColorScalePoint 

type ColorScalePoint struct {
	// Type is the threshold kind: "min", "max", "num", "percent", "percentile"
	// or "formula".
	Type string
	// Value is the threshold value or formula; empty for "min"/"max".
	Value string
	// Color is the stop color as a 6- or 8-digit hex RGB string (e.g. "F8696B"
	// or "FFF8696B").
	Color string
}

ColorScalePoint is one gradient stop of a color-scale rule: a threshold paired with the color reached at that threshold.

type Comment 

type Comment struct {
	// contains filtered or unexported fields
}

Comment is a cell comment: either a modern threaded comment (a resolvable discussion thread with dated, authored entries and replies) or a legacy note (a single unauthored-by-identity annotation rendered in a VML box). The read and write surface is shared across the docx, xlsx, and pptx packages; the xlsx-specific anchor is the cell reference, exposed by Ref.

A Comment returned by Sheet.Comments or Cell.Comment is a snapshot taken at the call; mutating methods (Reply, Resolve, SetResolved) write through to the workbook so a subsequent save persists them, but do not retroactively update other snapshots.

func (*Comment) Author 

func (c *Comment) Author() string

Author returns the display name of the comment's author.

func (*Comment) Date 

func (c *Comment) Date() time.Time

Date returns the comment's creation time. It is the zero time.Time for a legacy note, which carries no timestamp.

func (*Comment) ID 

func (c *Comment) ID() string

ID returns the comment's stable identifier. For a threaded comment this is its GUID; a legacy note has no identifier and returns "".

func (*Comment) Parent 

func (c *Comment) Parent() *Comment

Parent returns the comment this one replies to, or nil for a top-level comment or legacy note.

func (*Comment) Ref 

func (c *Comment) Ref() string

Ref returns the cell reference the comment is anchored to (e.g. "A1"). This is the xlsx-specific anchor, an addition to the shared comment surface.

func (*Comment) Replies 

func (c *Comment) Replies() []*Comment

Replies returns the thread's replies to this comment, in order. It is nil for a reply or a legacy note.

func (*Comment) Reply 

func (c *Comment) Reply(author, text string) *Comment

Reply adds a reply authored by author to the comment's thread, returning the new reply. It is a no-op returning nil for a legacy note, which has no thread. Replies are stored flat with the thread root as parent, matching Excel.

func (*Comment) Resolve 

func (c *Comment) Resolve()

Resolve marks the comment's thread resolved (done). Equivalent to SetResolved(true).

func (*Comment) Resolved 

func (c *Comment) Resolved() bool

Resolved reports whether the comment's thread is marked resolved (done). A legacy note is never resolved.

func (*Comment) RichText 

func (c *Comment) RichText() []TextRun

RichText returns the comment body as formatting runs. A legacy note carries per-run formatting (bold labels, colored text); a threaded comment and an unformatted note return a single run holding the plain text. It returns nil for an empty body. Text continues to return the flattened plain text.

func (*Comment) SetResolved 

func (c *Comment) SetResolved(resolved bool)

SetResolved sets the resolved (done) state of the comment's thread. It is a no-op for a legacy note.

func (*Comment) SetRichText 

func (c *Comment) SetRichText(runs []TextRun)

SetRichText replaces the comment's body with formatted runs, writing through to the workbook so a subsequent save persists it. For a legacy note the runs are stored with their formatting; for a threaded comment (whose stored body is plain text) the runs are flattened for the thread entry while the note's back-compat fallback keeps the formatting. It is a no-op on a comment not backed by any note or thread entry on its sheet.

func (*Comment) Text 

func (c *Comment) Text() string

Text returns the comment's plain-text body. Rich (per-run) formatting is flattened; use RichText to read the runs with their formatting intact.

func (*Comment) Threaded 

func (c *Comment) Threaded() bool

Threaded reports whether this is a modern threaded comment (true) or a legacy note (false). This is an xlsx-specific addition to the shared surface.

type ConditionalColorScale 

type ConditionalColorScale struct {
	Values []ConditionalValueObject
	// Colors are the gradient stops as hex RGB (e.g. "FFF8696B"); an entry is
	// empty when the stop uses a theme or indexed color instead.
	Colors []string
}

ConditionalColorScale is the read view of a colorScale rule: paired value objects and RGB colors defining the gradient.

type ConditionalDataBar 

type ConditionalDataBar struct {
	Values []ConditionalValueObject
	// Color is the bar fill as hex RGB, or empty for a theme/indexed color.
	Color string
	// ShowValue reports whether the cell value is shown alongside the bar
	// (Excel's default is true; nil means the attribute was absent).
	ShowValue *bool
}

ConditionalDataBar is the read view of a dataBar rule.

type ConditionalFormat 

type ConditionalFormat struct {
	// SqRef is the raw space-separated range list the block applies to (e.g.
	// "A1:A10 C1:C10").
	SqRef string
	// Ranges is SqRef split into individual range references.
	Ranges []string
	// Rules are the block's rules in document order.
	Rules []*ConditionalFormatRule
}

ConditionalFormat is a read-only view of one <conditionalFormatting> block: a set of cell ranges and the rules Excel evaluates against them. To create conditional formats use Sheet.AddConditionalFormat with the New*Rule constructors. A block opened from a file round-trips byte-for-byte when unmodified.

type ConditionalFormatRule 

type ConditionalFormatRule struct {
	// Type is the rule kind: "cellIs", "expression", "colorScale", "dataBar",
	// "iconSet", "top10", "aboveAverage", "duplicateValues", "uniqueValues",
	// "containsText", "timePeriod", etc.
	Type string
	// Operator is the comparison for cellIs/text rules (e.g. "between",
	// "greaterThan", "containsText"); empty when not applicable.
	Operator string
	// Priority orders overlapping rules (lower wins).
	Priority int
	// Formulas are the rule's <formula> operands, in order.
	Formulas []string
	// Text is the search text for containsText/beginsWith/endsWith rules.
	Text string
	// TimePeriod is the period for timePeriod rules (e.g. "today", "last7Days").
	TimePeriod string
	// StopIfTrue reports whether evaluation stops when this rule matches.
	StopIfTrue bool
	// DxfId indexes the differential format (dxf) applied when the rule matches,
	// or nil for rules that carry their own formatting (colorScale/dataBar/iconSet).
	DxfId *uint32
	// Rank is the N of a top10 rule (top/bottom N or N percent).
	Rank *uint32
	// Percent reports whether a top10 rule's Rank is a percentage.
	Percent bool
	// Bottom reports whether a top10 rule selects the bottom rather than the top.
	Bottom bool
	// AboveAverage, when non-nil, is an aboveAverage rule's direction: true for
	// above the average, false for below.
	AboveAverage *bool
	// ColorScale, DataBar and IconSet are populated for the corresponding rule
	// types and nil otherwise.
	ColorScale *ConditionalColorScale
	DataBar    *ConditionalDataBar
	IconSet    *ConditionalIconSet
	// contains filtered or unexported fields
}

ConditionalFormatRule is a read-only view of one <cfRule>. The set of populated fields depends on Type: cellIs uses Operator + Formulas; expression uses a single Formula; containsText and friends use Text; timePeriod rules use TimePeriod; top10 uses Rank/Percent/Bottom; colorScale, dataBar and iconSet carry their respective sub-view.

func (*ConditionalFormatRule) DifferentialFormat 

func (r *ConditionalFormatRule) DifferentialFormat() *DifferentialStyle

DifferentialFormat returns the resolved differential format (fill/font color/border) a rule applies when it matches, looked up from the workbook stylesheet via the rule's DxfId. It returns nil for rules that carry their own formatting (colorScale/dataBar/iconSet), for rules without a DxfId, or when the referenced dxf is absent or empty.

type ConditionalIconSet 

type ConditionalIconSet struct {
	// IconSet names the icon collection (e.g. "3TrafficLights1", "5Arrows").
	IconSet string
	Values  []ConditionalValueObject
	// ShowValue and Reverse mirror the iconSet attributes (nil when absent).
	ShowValue *bool
	Reverse   *bool
}

ConditionalIconSet is the read view of an iconSet rule.

type ConditionalRule 

type ConditionalRule struct {
	// contains filtered or unexported fields
}

ConditionalRule is a single conditional-formatting rule produced by one of the New*Rule constructors and passed to Sheet.AddConditionalFormat. Its priority and (where applicable) differential-format index are assigned when it is added to a sheet, so a rule value must not be reused across ranges.

func NewAboveAverageRule 

func NewAboveAverageRule(above bool, style DifferentialStyle) ConditionalRule

NewAboveAverageRule builds an aboveAverage rule that applies style to cells above (above=true) or below (above=false) the range average.

func NewCellIsRule 

func NewCellIsRule(operator string, style DifferentialStyle, formulas ...string) ConditionalRule

NewCellIsRule builds a cellIs rule that compares each cell against one or two formula operands with the given operator (a CondOp* constant) and applies style when it matches. Between/NotBetween need two formulas; the other operators need one. A formula operand is any Excel expression: a literal ("100"), a quoted string (`"done"`) or a reference ("$B$1").

func NewColorScaleRule 

func NewColorScaleRule(points ...ColorScalePoint) ConditionalRule

NewColorScaleRule builds a colorScale rule with two or three gradient stops (a 2-color or 3-color scale). It carries its own formatting, so it does not allocate a differential format.

func NewDataBarRule 

func NewDataBarRule(color string, low, high ConditionalValueObject) ConditionalRule

NewDataBarRule builds a dataBar rule with the given bar color and lower/upper bounds. A bound with an empty Type defaults to "min" (low) / "max" (high); any other Type must be a valid ST_CfvoType. It carries its own formatting.

func NewDuplicateValuesRule 

func NewDuplicateValuesRule(style DifferentialStyle) ConditionalRule

NewDuplicateValuesRule builds a rule that applies style to values appearing more than once in the range.

func NewExpressionRule 

func NewExpressionRule(formula string, style DifferentialStyle) ConditionalRule

NewExpressionRule builds an expression rule that applies style to every cell for which formula evaluates to TRUE. The formula is relative to the top-left cell of the range (e.g. "MOD(ROW(),2)=0" to shade even rows).

func NewIconSetRule 

func NewIconSetRule(iconSet string, thresholds ...ConditionalValueObject) ConditionalRule

NewIconSetRule builds an iconSet rule using the named icon collection (e.g. "3TrafficLights1", "4Arrows", "5Rating"). When no thresholds are given, one percent threshold per icon is generated (evenly spaced from 0). When thresholds are given there must be exactly one per icon in the set — Excel prompts to repair a file whose cfvo count does not match the icon count. It carries its own formatting.

func NewTextRule 

func NewTextRule(operator, text string, style DifferentialStyle) ConditionalRule

NewTextRule builds a rule from the containsText family (operator is a CondText* constant) that applies style to cells whose text contains, does not contain, begins with or ends with text. The matching formula Excel expects is synthesized automatically against the range's anchor cell.

func NewTimePeriodRule 

func NewTimePeriodRule(period string, style DifferentialStyle) ConditionalRule

NewTimePeriodRule builds a timePeriod rule that applies style to date cells falling in period (e.g. "today", "yesterday", "last7Days", "thisMonth"). The comparison formula Excel expects is synthesized against the range anchor.

func NewTop10Rule 

func NewTop10Rule(rank uint32, bottom, percent bool, style DifferentialStyle) ConditionalRule

NewTop10Rule builds a top10 rule that applies style to the top (or, when bottom is true, the bottom) rank values in the range. When percent is true rank is a percentage (1-100) rather than a count.

func NewUniqueValuesRule 

func NewUniqueValuesRule(style DifferentialStyle) ConditionalRule

NewUniqueValuesRule builds a rule that applies style to values appearing exactly once in the range.

func (ConditionalRule) StopIfTrue 

func (r ConditionalRule) StopIfTrue() ConditionalRule

StopIfTrue marks the rule so Excel stops evaluating lower-priority rules on the same cell once this one matches. It returns the rule for chaining.

type ConditionalValueObject 

type ConditionalValueObject struct {
	// Type is the threshold kind: "min", "max", "num", "percent", "percentile",
	// "formula".
	Type string
	// Value is the threshold value or formula (empty for min/max).
	Value string
}

ConditionalValueObject is a conditional-format value object (<cfvo>): a threshold that anchors a colorScale stop, dataBar bound or iconSet band.

type Connection 

type Connection struct {
	// ID is the connection's numeric id attribute.
	ID uint32
	// Name is the connection name (often the query or table name).
	Name string
	// Description is the optional connection description.
	Description string
	// Type is the raw connection type code (ST_ConnectionType): 1=OLE DB,
	// 2=data feed, 4=web query, 5=text, 6=... . 0 when unset.
	Type uint32
	// ConnectionString is the provider connection string from <dbPr connection>,
	// or "" when the connection is not database-backed.
	ConnectionString string
	// Command is the query command (SQL, table name, or query text) from
	// <dbPr command>, or "" when none.
	Command string
	// WebURL is the source URL from <webPr url> for a web query, or "".
	WebURL string
	// SourceFile is the external source file from <textPr sourceFile> or
	// <connection sourceFile>, or "".
	SourceFile string
}

Connection describes one external-data connection declared in xl/connections.xml: the metadata Excel uses to refresh a query, a pivot cache, a data-model table, or a Power Query load. Spine reads and preserves connections but does not author or refresh them (authoring a live query, with its provider round-trip and credential handling, is out of scope); see the note on Workbook.Connections.

type CustomFilter 

type CustomFilter struct {
	Operator string // one of the Filter* operator constants; empty means Equal
	Value    string
}

CustomFilter is one criterion of a custom (comparison) auto-filter, e.g. {Operator: FilterGreaterThan, Value: "100"}.

type DataModelInfo 

type DataModelInfo struct {
	// HasDataModel reports whether the workbook carries a Power Pivot data model
	// (xl/model/ parts).
	HasDataModel bool
	// HasPowerQuery reports whether the workbook carries Power Query definitions
	// (a DataMashup blob in a customXml item).
	HasPowerQuery bool
	// ModelParts are the part names of the data model (xl/model/*), sorted.
	ModelParts []string
	// CustomXMLParts are the customXml item part names carrying Power Query /
	// data-model metadata (DataMashup), sorted.
	CustomXMLParts []string
}

DataModelInfo reports the presence and locations of a workbook's Power Pivot data model and Power Query (Get & Transform) content. Spine reads and preserves these parts byte-for-byte but does not author or refresh them; full data-model and Power Query authoring (the DataMashup blob, model tables and relationships) is out of scope.

type DataValidation 

type DataValidation struct {
	Range    string // cell range (e.g., "B2:B100")
	Type     string // "list", "whole", "decimal", "date", "textLength", "custom"
	Operator string // "between", "lessThan", "equal", etc.
	Formula1 string
	Formula2 string
	// AllowBlank permits empty cells regardless of the rule.
	AllowBlank bool
	// HideDropDown suppresses the in-cell dropdown arrow for list validations.
	// By default Excel shows the dropdown; the underlying OOXML attribute
	// showDropDown counterintuitively means "suppress the dropdown", so this
	// field is named for what it actually does (C76).
	HideDropDown bool
	// ErrorTitle/ErrorMessage define the alert Excel shows on invalid input.
	// When either is set, showErrorMessage is emitted automatically — without
	// it Excel never displays the alert.
	ErrorTitle   string
	ErrorMessage string
	// PromptTitle/PromptMessage define the input hint shown when the cell is
	// selected. When either is set, showInputMessage is emitted automatically.
	PromptTitle   string
	PromptMessage string
	// ErrorStyle selects the alert icon/behavior for invalid input:
	// ValidationErrorStop (the default, rejects the entry), ValidationErrorWarning
	// (allows it after a prompt) or ValidationErrorInformation (informational
	// only). Empty leaves the attribute unset, which Excel treats as stop.
	ErrorStyle string
	// ImeMode controls the Input Method Editor state for the cell (East-Asian
	// text entry), e.g. "off", "on", "disabled", "hiragana". Empty leaves it
	// unset.
	ImeMode string
}

DataValidation represents a data validation rule.

type DefinedName 

type DefinedName struct {
	Name       string
	Value      string
	SheetIndex int // -1 for workbook scope
	// Hidden hides the name from Excel's Name Manager.
	Hidden bool
	// Comment is the name's optional comment.
	Comment string
	// Description is the name's optional description.
	Description string
}

DefinedName represents a named range or formula in the workbook.

type DifferentialStyle 

type DifferentialStyle struct {
	Font   *FontStyle
	Fill   *FillStyle
	Border *BorderStyle
}

DifferentialStyle is the formatting a rule applies when it matches. It is stored in the styles part as a differential format (dxf) and referenced from the rule by index. Any subset of the fields may be set; nil fields are left unchanged by the rule. It mirrors the existing cell-style building blocks (FontStyle/FillStyle/BorderStyle) so callers reuse one vocabulary.

Fill note: in a differential format Excel carries the visible solid-fill color in the pattern background, unlike a cell fill (which uses the foreground). NewCellIsRule and friends translate FillStyle accordingly, so a caller sets FillStyle.FgColor (or BgColor) to the highlight color they want.

type FillStyle 

type FillStyle struct {
	Pattern string
	FgColor string // hex color
	BgColor string // hex color
	// Gradient, when non-nil, renders a gradient fill instead of a pattern fill.
	Gradient *GradientFill
}

FillStyle represents fill styling. It carries either a pattern fill (the Pattern/FgColor/BgColor fields) or, when Gradient is set, a gradient fill. A non-nil Gradient takes precedence over the pattern fields.

type FilterColumn 

type FilterColumn struct {
	// ColID is the zero-based column offset within the auto-filter range.
	ColID uint32
	// Values, when non-empty, is a value-list filter: a row passes when the
	// column's displayed value matches one of these strings.
	Values []string
	// Blank, when true, also lets blank cells through the value-list filter.
	Blank bool
	// Custom, when non-empty, holds one or two custom comparison criteria.
	Custom []CustomFilter
	// CustomAnd combines two custom criteria with AND; the default (false) is OR.
	CustomAnd bool
	// HiddenButton hides the filter dropdown button on the column.
	HiddenButton bool
	// ShowButton, when explicitly set to false, hides the dropdown button.
	// A nil value leaves the attribute unset (button shown).
	ShowButton *bool
}

FilterColumn describes the filter predicate applied to one column of a sheet's auto-filter. A column carries either a value-list filter (Values, optionally with Blank) or a custom comparison filter (Custom); when both are set the value list wins.

type FontStyle 

type FontStyle struct {
	Name      string
	Size      float64
	Bold      bool
	Italic    bool
	Underline bool
	Color     string // hex color
	// Strike renders the text with a strikethrough (x:strike).
	Strike bool
	// UnderlineStyle selects a richer underline than the plain Underline bool
	// (e.g. UnderlineDouble, UnderlineSingleAccounting). When set it takes
	// precedence over Underline; the empty value leaves Underline in control.
	UnderlineStyle UnderlineStyle
	// VertAlign renders the text as superscript or subscript (x:vertAlign). The
	// empty value leaves the run on the baseline.
	VertAlign enum.VerticalAlignRun
}

FontStyle represents font styling.

type FormControl 

type FormControl struct {
	// Type is the control kind derived from the VML ObjectType.
	Type FormControlType
	// Name is the control's display name from the worksheet <control> block
	// (e.g. "Check Box 1"); best-effort and may be empty.
	Name string
	// LinkedCell is the cell the control's value is bound to (x:FmlaLink), such
	// as "$B$2"; empty when the control has no linked cell.
	LinkedCell string
	// SourceRange is the input range feeding a list box or dropdown (x:FmlaRange),
	// such as "$D$1:$D$5"; empty otherwise.
	SourceRange string
	// Checked reports the initial state of a checkbox or radio control.
	Checked bool
	// Anchor is the control's raw two-cell VML anchor (comma-separated
	// col,dx,row,dy pairs); preserved verbatim for callers that need placement.
	Anchor string
	// VMLPart is the OPC part name of the legacy VML drawing that hosts the
	// control shape (e.g. "/xl/drawings/vmlDrawing1.vml").
	VMLPart string
	// CtrlPropPart is the OPC part name of the control's properties part
	// (xl/ctrlProps/ctrlPropN.xml), resolved through the worksheet <control>
	// relationship; best-effort and may be empty.
	CtrlPropPart string
}

FormControl is a legacy Excel form control on a worksheet, reconstructed from the sheet's VML drawing (the x:ClientData shape) and, best-effort, the worksheet's <control> block. Extraction is read-only; the control parts (VML, ctrlProps) round-trip byte-for-byte on a subsequent save.

type FormControlType 

type FormControlType string

FormControlType classifies a legacy Excel form control (the kind on the Developer > Insert > Form Controls palette), stored as a VML shape whose x:ClientData carries an ObjectType. 

const (
	FormControlButton    FormControlType = "button"
	FormControlCheckBox  FormControlType = "checkbox"
	FormControlDropDown  FormControlType = "dropdown"
	FormControlListBox   FormControlType = "listbox"
	FormControlRadio     FormControlType = "radio"
	FormControlSpinner   FormControlType = "spinner"
	FormControlScrollBar FormControlType = "scrollbar"
	FormControlLabel     FormControlType = "label"
	FormControlGroupBox  FormControlType = "groupbox"
	FormControlEditBox   FormControlType = "editbox"
	FormControlDialog    FormControlType = "dialog"
	FormControlUnknown   FormControlType = "unknown"
)

type GradientFill 

type GradientFill struct {
	Type   string // "linear" (default) or "path"
	Degree float64
	Left   float64
	Right  float64
	Top    float64
	Bottom float64
	Stops  []GradientStop
}

GradientFill represents a gradient fill (CT_GradientFill). Type is "linear" (the default when empty) or "path". For a linear gradient Degree is the angle; for a path gradient Left/Right/Top/Bottom (0..1) locate the inner rectangle. Stops lists the color stops in ascending position order.

type GradientStop 

type GradientStop struct {
	Position float64 // 0..1
	Color    string  // hex color
}

GradientStop represents a single gradient color stop (CT_GradientStop).

type HeaderFooter 

type HeaderFooter struct {
	DifferentOddEven *bool
	DifferentFirst   *bool
	ScaleWithDoc     *bool
	AlignWithMargins *bool
	OddHeader        string
	OddFooter        string
	EvenHeader       string
	EvenFooter       string
	FirstHeader      string
	FirstFooter      string
}

HeaderFooter is the modeled content of the worksheet <headerFooter> element: the header and footer strings (each using Excel's &L/&C/&R section codes) and the flags controlling which of them apply. 

type Hyperlink struct {
	// contains filtered or unexported fields
}

Hyperlink is a cell hyperlink. The read and write surface is shared across the docx, xlsx, and pptx packages: URL, Anchor, and Tooltip have the same meaning in each. In xlsx a hyperlink is anchored to a cell (or cell range); the xlsx-specific anchor cell is available via Ref.

A hyperlink is either external (URL is set, Anchor is "") or internal (Anchor is a cell/range reference within the workbook such as "Sheet2!A1", URL is "").

func (*Hyperlink) Anchor 

func (h *Hyperlink) Anchor() string

Anchor returns the internal target of the hyperlink — a cell or range reference within the workbook, such as "Sheet2!A1" — or "" if the hyperlink is external.

func (*Hyperlink) Ref 

func (h *Hyperlink) Ref() string

Ref returns the cell reference the hyperlink is anchored to (e.g. "A1"). This is the xlsx-specific anchor, an addition to the shared hyperlink surface.

func (*Hyperlink) SetTooltip 

func (h *Hyperlink) SetTooltip(tooltip string)

SetTooltip sets the hyperlink's tooltip (screen-tip) text and marks the sheet dirty so a save persists it.

func (*Hyperlink) Tooltip 

func (h *Hyperlink) Tooltip() string

Tooltip returns the hyperlink's tooltip (screen-tip) text, or "" if none.

func (*Hyperlink) URL 

func (h *Hyperlink) URL() string

URL returns the external target of the hyperlink, or "" if the hyperlink is internal (points at a location within the workbook).

type Image 

type Image struct {
	// contains filtered or unexported fields
}

Image is a read-only view of an image on a worksheet. The Width/Height/WidthEMU/HeightEMU/AltText/Data/ContentType/PartName surface matches the image readers of the docx and pptx packages; the xlsx-specific anchor is the top-left cell the image is pinned to.

func (*Image) AltText 

func (i *Image) AltText() string

AltText returns the image's alternative-text description, or "" if none.

func (*Image) AnchorCell 

func (i *Image) AnchorCell() string

AnchorCell returns the top-left cell the image is anchored to (e.g. "B2"), or "" when the image is not anchored to a cell (an absolute-position anchor).

func (*Image) ContentType 

func (i *Image) ContentType() string

ContentType returns the image's OPC content type (e.g. "image/png").

func (*Image) Data 

func (i *Image) Data() []byte

Data returns the raw image bytes. For an SVG image added via AddImage the bytes are the raster (PNG) fallback embedded for viewers that cannot render SVG; use SVGData to retrieve the original SVG.

func (*Image) Height 

func (i *Image) Height() float64

Height returns the image's rendered height in points, or 0 when not readily available.

func (*Image) HeightEMU 

func (i *Image) HeightEMU() int64

HeightEMU returns the image's rendered height in EMU, or 0 when not readily available.

func (*Image) PartName 

func (i *Image) PartName() string

PartName returns the package part name of the image's binary (e.g. /xl/media/image1.png), or "" when it cannot be resolved — an image added this session has no part name until the workbook is saved. This matches the docx and pptx image readers.

func (*Image) SVGData added in v0.2.0 

func (i *Image) SVGData() []byte

SVGData returns the original SVG bytes for an image added as SVG via AddImage, or nil when the image is not an SVG (or its SVG variant is not available, e.g. an image loaded from an opened file). When non-nil, Data returns the raster fallback for the same image.

func (*Image) Width 

func (i *Image) Width() float64

Width returns the image's rendered width in points, the display unit shared with the docx and pptx image readers, or 0 when the width is not readily available (e.g. a two-cell anchor sizes to the span).

func (*Image) WidthEMU 

func (i *Image) WidthEMU() int64

WidthEMU returns the image's rendered width in English Metric Units, or 0 when the width is not readily available (e.g. a two-cell anchor sizes to the span).

type ImageOptions 

type ImageOptions struct {
	// WidthPx and HeightPx set the rendered image size in pixels. When either
	// is zero, the image's intrinsic pixel dimension is used for that axis,
	// unless PreserveAspect is set (see below).
	WidthPx  int
	HeightPx int

	// PreserveAspect, when set with exactly one of WidthPx/HeightPx, scales the
	// unset axis to keep the image's intrinsic aspect ratio (instead of using
	// its intrinsic pixel size for that axis).
	PreserveAspect bool

	// ToCell, when set, makes the image a two-cell anchor spanning from the
	// anchor cell to ToCell (e.g. "D10"): the image moves and resizes with the
	// cells. WidthPx/HeightPx are ignored for a two-cell anchor.
	ToCell string

	// AltText is the image's alternative-text description, written to the
	// picture's xdr:cNvPr descr attribute and read back by Image.AltText.
	//
	// It is xlsx's spelling of the alt-text write that docx and pptx expose as
	// InlineImage.SetAltText and Picture.SetAltText: AddImage returns only an
	// error (no handle) and xlsx.Image is a read view of the saved drawing, so
	// this is the settable path (C442). An accessibility pass that sets alt text
	// on every image is now expressible in all three formats.
	AltText string
}

ImageOptions configures how an image is placed on a sheet.

Placement is limited to whole cells. An anchor pins the image to a cell's top-left corner: the colOff/rowOff sub-cell offsets DrawingML allows are always written as 0, and absolute anchors (xdr:absoluteAnchor, a position fixed in EMU rather than relative to the grid) are not produced at all. Pixel dimensions are converted at a fixed 96 DPI (9525 EMU per pixel), so an image authored for a different DPI is scaled accordingly.

type NamedStyle 

type NamedStyle struct {
	// Name is the style's display name (e.g. "Good", "Heading 1", "My Style").
	Name string
	// Style is the formatting the named style applies.
	Style CellStyle
	// BuiltinId, when non-nil, links the style to one of Excel's built-in
	// styles (see the BuiltinStyle* constants).
	BuiltinId *uint32
	// Hidden hides the style from the gallery.
	Hidden bool
	// CustomBuiltin marks a built-in style that the user has customized.
	CustomBuiltin bool
}

NamedStyle is a named (or built-in) cell style: a reusable format that shows up in Excel's Cell Styles gallery and can be applied to cells by name.

type OLEObject 

type OLEObject struct {
	// Name is the OPC part name of the embedded object.
	Name string
	// ContentType is the part's content type (usually opc.ContentTypeOLEObject).
	ContentType string
	// Data is the raw embedded object, carried verbatim.
	Data []byte
	// ProgID is the OLE server programmatic identifier declared by the
	// referencing element (e.g. "Excel.Sheet.12"), or "" when none is declared
	// in a form spine recognizes.
	ProgID string
}

OLEObject is an embedded OLE object extracted from a workbook: an opaque binary part (typically /xl/embeddings/oleObjectN.bin) plus the metadata needed to identify it. The Data bytes are the object exactly as stored; spine does not parse the embedded OLE/CFB stream.

type OLEObjectSpec 

type OLEObjectSpec struct {
	// Data is the embedded object, carried verbatim (required, non-empty).
	Data []byte
	// ProgID is the OLE server programmatic identifier (e.g. "Word.Document.12",
	// "Package"). Defaults to "Package" when empty.
	ProgID string
	// ContentType is the embedding part's content type. Defaults to
	// opc.ContentTypeOLEObject.
	ContentType string
	// Ext is the embedding part's file extension without the dot (e.g. "bin",
	// "docx"). Defaults to "bin".
	Ext string
	// Anchor is the top-left cell the object is anchored to (e.g. "B2").
	// Defaults to "A1".
	Anchor string
	// Preview is an optional raster/metafile preview of the object shown on the
	// sheet (PNG/EMF bytes). When empty the object embeds without an on-sheet
	// image (it still opens and round-trips).
	Preview []byte
	// PreviewContentType is the preview image's content type (e.g.
	// opc.ContentTypePNG, opc.ContentTypeEMF). Required when Preview is set.
	PreviewContentType string
	// PreviewExt is the preview image's extension without the dot (e.g. "png",
	// "emf"). Required when Preview is set.
	PreviewExt string
}

OLEObjectSpec describes an OLE object to embed on a sheet with Sheet.AddOLEObject. Data is the object's raw OLE/CFB bytes (spine stores them verbatim and never parses them). The remaining fields are optional.

type PageMargins 

type PageMargins struct {
	Left   float64
	Right  float64
	Top    float64
	Bottom float64
	Header float64
	Footer float64
}

PageMargins is the set of page margins (in inches) exposed through the public API, mirroring the worksheet <pageMargins> element.

type PageSetup 

type PageSetup struct {
	// Orientation is "portrait", "landscape", "default", or "" (unset).
	Orientation     string
	PaperSize       *uint32
	Scale           *uint32
	FitToWidth      *uint32
	FitToHeight     *uint32
	FirstPageNumber *uint32
	BlackAndWhite   *bool
	Draft           *bool
}

PageSetup is the modeled subset of a worksheet's <pageSetup> element exposed through the public API. Pointer fields are unset when nil; SetPageSetup only writes the fields present here and leaves any other attributes on an existing element (printer relationship, DPI, copies, ...) untouched.

type PivotAggregation 

type PivotAggregation string

PivotAggregation is the aggregation function a value (data) field applies to its source values. 

const (
	PivotSum      PivotAggregation = "sum"
	PivotCount    PivotAggregation = "count"     // counts non-empty values (countA)
	PivotCountNum PivotAggregation = "countNums" // counts numeric values
	PivotAverage  PivotAggregation = "average"
	PivotMax      PivotAggregation = "max"
	PivotMin      PivotAggregation = "min"
	PivotProduct  PivotAggregation = "product"
)

Supported value-field aggregations. The zero value ("") is treated as PivotSum.

type PivotCalculatedField 

type PivotCalculatedField struct {
	// Name is the calculated field's name (and, prefixed with the aggregation,
	// its value-field display name). It must be unique among the source columns.
	Name string
	// Formula is the calculation, e.g. "Sales-Cost" or "Price*Quantity".
	Formula string
}

PivotCalculatedField is a formula-derived value field. The formula references source column names, e.g. Formula: "Sales-Cost".

type PivotDateGroup 

type PivotDateGroup struct {
	// Field is the date/time source column to group.
	Field string
	// By is the calendar unit: PivotByYear, PivotByQuarter, PivotByMonth or
	// PivotByDay. The zero value groups by month.
	By PivotDateGroupBy
	// OnColumn places the grouped field on the column axis instead of the row axis.
	OnColumn bool
}

PivotDateGroup groups a date/time source field into calendar buckets placed on an axis. Values are bucketed by the whole calendar unit (e.g. By PivotByMonth buckets every January together regardless of year).

type PivotDateGroupBy 

type PivotDateGroupBy string

PivotDateGroupBy is the calendar unit a date field is grouped by. 

const (
	PivotByYear    PivotDateGroupBy = "years"
	PivotByQuarter PivotDateGroupBy = "quarters"
	PivotByMonth   PivotDateGroupBy = "months"
	PivotByDay     PivotDateGroupBy = "days"
)

Supported date grouping units.

type PivotItemGroup 

type PivotItemGroup struct {
	// Field is the source column whose items are grouped.
	Field string
	// Groups are the named parent groups; each names the source item values it
	// collects. A value may appear in at most one group.
	Groups []PivotNamedGroup
	// OnColumn places the grouped field on the column axis instead of the row axis.
	OnColumn bool
}

PivotItemGroup folds selected items of a source field into named parent groups placed on an axis. Items not named in any group remain as themselves.

type PivotNamedGroup 

type PivotNamedGroup struct {
	// Name is the group's display label (e.g. "West"). It must be unique within
	// the item grouping and must not collide with an ungrouped source item.
	Name string
	// Items are the source item values collected into the group.
	Items []string
}

PivotNamedGroup is one named parent group of an item grouping: a display name and the source item values folded into it.

type PivotNumericGroup 

type PivotNumericGroup struct {
	// Field is the numeric source column to group.
	Field string
	// Start, End and Interval define the buckets. Interval must be positive and
	// End must exceed Start.
	Start    float64
	End      float64
	Interval float64
	// OnColumn places the grouped field on the column axis instead of the row axis.
	OnColumn bool
}

PivotNumericGroup groups a numeric source field into equal-width value ranges placed on an axis. Values below Start collect into a leading "<Start" bucket, values at or above End into a trailing ">End" bucket, and the remainder into [Start, Start+Interval), [Start+Interval, Start+2*Interval), ... buckets.

type PivotOptions 

type PivotOptions struct {
	// Name is the pivot table's name; it must be unique in the workbook. When
	// empty a unique name ("PivotTable1", "PivotTable2", ...) is generated.
	Name string
	// RowFields are source column names placed on the row axis, in order.
	RowFields []string
	// ColumnFields are source column names placed on the column axis, in order.
	ColumnFields []string
	// ValueFields are the aggregated value fields. At least one value field or
	// calculated field is required.
	ValueFields []PivotValueField
	// Filters are source column names placed on the page (report filter) axis.
	Filters []string
	// CalculatedFields are formula-derived value fields (e.g. Profit =
	// "Sales-Cost"). Each is added to the cache as a calculated field and placed
	// on the value axis (summed). Formulas reference source column names.
	CalculatedFields []PivotCalculatedField
	// NumericGroups group a numeric source field into value ranges (e.g. bucket
	// Age into 10-year bands). Each grouped field is placed on the row axis (or
	// the column axis when OnColumn is set) in place of the raw field.
	NumericGroups []PivotNumericGroup
	// DateGroups group a date/time source field into calendar buckets (year,
	// quarter, month or day). Each grouped field is placed on the row axis (or
	// the column axis when OnColumn is set).
	DateGroups []PivotDateGroup
	// ItemGroups fold selected items of a source field into named parent groups
	// (e.g. group states into "West"/"East"). Each grouped field is placed on the
	// row axis (or the column axis when OnColumn is set).
	ItemGroups []PivotItemGroup
}

PivotOptions configures a pivot table created via Sheet.AddPivotTable.

type PivotTable 

type PivotTable struct {
	// contains filtered or unexported fields
}

PivotTable is a pivot table: a cross-tabulation of a source range summarized on the row, column, value and page (filter) axes. A PivotTable returned by Sheet.PivotTables or Workbook.PivotTables reflects the table as stored in the workbook; its accessors are read-only.

func (*PivotTable) CacheID 

func (p *PivotTable) CacheID() uint32

CacheID returns the id of the pivot cache the table draws from.

func (*PivotTable) ColumnFields 

func (p *PivotTable) ColumnFields() []string

ColumnFields returns the source field names on the column axis, in order.

func (*PivotTable) Filters 

func (p *PivotTable) Filters() []string

Filters returns the source field names on the page (report filter) axis.

func (*PivotTable) Location 

func (p *PivotTable) Location() string

Location returns the cell range the pivot table occupies on its sheet (e.g. "A3:C12").

func (*PivotTable) Name 

func (p *PivotTable) Name() string

Name returns the pivot table's name.

func (*PivotTable) RowFields 

func (p *PivotTable) RowFields() []string

RowFields returns the source field names on the row axis, in order.

func (*PivotTable) SourceRange 

func (p *PivotTable) SourceRange() string

SourceRange returns the source data range the pivot cache was built from (e.g. "A1:D100"), or "" when the cache could not be resolved.

func (*PivotTable) SourceSheet 

func (p *PivotTable) SourceSheet() string

SourceSheet returns the name of the sheet holding the source range, or "" when the cache could not be resolved.

func (*PivotTable) ValueFields 

func (p *PivotTable) ValueFields() []PivotValue

ValueFields returns the pivot table's value (data) fields, each with its display name, source field and aggregation.

type PivotValue 

type PivotValue struct {
	// Name is the value field's display name (e.g. "Sum of Sales").
	Name string
	// Field is the source field name this value aggregates.
	Field string
	// Aggregation is the aggregation function.
	Aggregation PivotAggregation
}

PivotValue describes a value field of an existing pivot table.

type PivotValueField 

type PivotValueField struct {
	// Field is the source column header name.
	Field string
	// Aggregation is the aggregation function; the zero value is PivotSum.
	Aggregation PivotAggregation
	// Name is the value field's display name (e.g. "Sum of Sales"). When empty a
	// name is derived from the aggregation and field (e.g. "Sum of Sales").
	Name string
}

PivotValueField specifies a source field placed on the value (data) axis and how it is aggregated.

type PrintOptions 

type PrintOptions struct {
	HorizontalCentered *bool
	VerticalCentered   *bool
	Headings           *bool
	GridLines          *bool
	GridLinesSet       *bool
}

PrintOptions is the modeled content of the worksheet <printOptions> element: whether gridlines and row/column headings print and how the sheet is centered on the page.

type ProtectionStyle 

type ProtectionStyle struct {
	// Locked reports whether the cell is locked. Excel locks cells by default,
	// so set Locked=false to leave specific cells editable on a protected sheet.
	Locked bool
	// Hidden reports whether the cell's formula is hidden in the formula bar on
	// a protected sheet.
	Hidden bool
}

ProtectionStyle represents a cell format's protection flags (the <protection> child of an xf record). It is only meaningful on a protected sheet.

type Scenario 

type Scenario struct {
	// Name is the scenario's display name (required, unique within the sheet).
	Name string
	// Comment is the optional free-text comment shown in the Scenario Manager.
	Comment string
	// User is the optional author recorded for the scenario.
	User string
	// Hidden hides the scenario from the Scenario Manager list.
	Hidden bool
	// Locked marks the scenario locked (only meaningful when the sheet is
	// protected with the scenarios option).
	Locked bool
	// Inputs are the changing cells and the values this scenario substitutes.
	Inputs []ScenarioInput
}

Scenario is a what-if scenario: a named set of substitute values for a group of changing (input) cells on a sheet, managed through Excel's Scenario Manager (Data > What-If Analysis > Scenario Manager).

type ScenarioInput 

type ScenarioInput struct {
	// Cell is the changing cell reference (e.g. "B2").
	Cell string
	// Value is the substitute value, stored verbatim as the cell's value.
	Value string
}

ScenarioInput is one changing cell within a scenario and the value the scenario substitutes for it.

type Sheet 

type Sheet struct {
	// contains filtered or unexported fields
}

Sheet represents a worksheet in an Excel workbook.

func (*Sheet) AddChart 

func (s *Sheet) AddChart(c *chart.Chart, anchor string) error

AddChart anchors a chart on the sheet at the given position. anchor is either a single cell (e.g. "E2"), placing a default-sized chart with its top-left corner there, or a range (e.g. "E2:L20"), placing the chart to span exactly that block of cells.

The chart comes first, as it does in docx's Document.AddChart / Paragraph.AddChart and pptx's Slide.AddChart. The placement arguments after it legitimately differ per format (a cell anchor here, an EMU box there), but the shared *chart.Chart used to be last in xlsx and first in the other two — a gratuitous flip in an API the chart package's own godoc advertises as "symmetric methods over the same *Chart value" (C566).

Data placement: an xlsx chart references cells in the host workbook rather than an embedded workbook. AddChart writes the chart's data (categories, and each series' name and values) into a dedicated hidden worksheet — one per chart — and points the chart's c:f formula references at it, so Excel's "Edit Data" opens the real cells while the cached values keep the chart rendering standalone. The host sheet's own cells are never touched, so a chart can sit next to unrelated data.

AddChart works on both created (Create) and opened (Open/OpenReader) workbooks; the chart, drawing and data parts are added on the next save.

The chart is copied, so the caller's *chart.Chart is left untouched (its DataRef keeps whatever it had) and one chart value can be added to several sheets, workbooks, or documents. Later edits to the caller's chart do not change what this sheet saves.

func (*Sheet) AddComment 

func (s *Sheet) AddComment(ref, author, text string) *Comment

AddComment adds a threaded comment authored by author to the cell at ref (see Cell.AddComment).

func (*Sheet) AddConditionalFormat 

func (s *Sheet) AddConditionalFormat(cellRange string, rules ...ConditionalRule) error

AddConditionalFormat adds a conditional-formatting block over cellRange (a single range like "B2:B10" or a space-separated list like "A1:A10 C1:C10") with the given rules, in the order supplied. Rules that apply a differential format allocate (and deduplicate) a dxf entry in the styles part; every rule is assigned a sheet-unique priority above any already present, so later calls layer on top of earlier ones. It returns an error if the range is invalid, no rules are given, or a rule was built with invalid parameters.

func (*Sheet) AddDataValidation 

func (s *Sheet) AddDataValidation(dv DataValidation) error

AddDataValidation adds a data validation rule to the sheet.

func (*Sheet) AddImage 

func (s *Sheet) AddImage(cellRef string, data []byte, opts ImageOptions) error

AddImage anchors an image (PNG, JPEG, GIF or SVG) with its top-left corner at the given cell reference (e.g. "A1"). The image bytes are embedded in the workbook on save. SVG images are embedded with a transparent raster fallback for viewers that cannot render SVG.

AddImage works on both created (Create) and opened (Open/OpenReader) workbooks. On an opened workbook the drawing, media, and relationship parts are added alongside whatever the package already carries, with part names chosen to avoid the existing ones. When the target sheet already has a drawing from the original file, the new anchors are appended to it and its existing shapes are kept (C249); only sheets with no drawing at all get a fresh drawing part.

It returns ErrNotWorksheet on a chartsheet, dialogsheet or macrosheet: such a sheet round-trips verbatim and has no worksheet model to attach a drawing to, so the image would be dropped at save (C423).

func (*Sheet) AddNote 

func (s *Sheet) AddNote(ref, author, text string) *Comment

AddNote adds a legacy note (an unthreaded comment) authored by author to the cell at ref, returning it. Unlike AddComment it creates no threaded comment or person entry; use it when only the classic note mechanism is wanted.

func (*Sheet) AddNoteRichText 

func (s *Sheet) AddNoteRichText(ref, author string, runs []TextRun) *Comment

AddNoteRichText adds a legacy note whose body carries per-run formatting (a bold label, colored text) to the cell at ref, returning it. Each TextRun may set its own font; a nil run font leaves the run in the note's default font. Text on the returned comment reads back the flattened plain text.

func (*Sheet) AddOLEObject 

func (s *Sheet) AddOLEObject(spec OLEObjectSpec) error

AddOLEObject embeds an OLE object on the sheet: it writes the object as an embedding part, wires the worksheet <oleObjects> reference and its relationship, and generates a legacy VML shape (with the optional preview image) so Excel renders the object at the anchor cell.

It authors the classic legacy embedding form (an <oleObject> with a matching VML Pict shape), which Excel opens without a repair prompt. The object is re-extractable through Workbook.OLEObjects and round-trips on save.

Comments and OLE objects coexist: adding comments to the sheet after this call folds their note shapes into the same legacy VML drawing under one <legacyDrawing> (C283).

Limitation: the reverse order is still rejected — a sheet that already carries comments, or a pre-existing <oleObjects>/legacyDrawing element (e.g. a form control), owns the single legacy VML drawing, and merging an authored object into an existing one is out of scope. Add the OLE object first (then comments), or add it on a sheet without those.

func (*Sheet) AddPivotTable 

func (s *Sheet) AddPivotTable(sourceRange, anchor string, opts PivotOptions) (*PivotTable, error)

AddPivotTable creates a pivot table summarizing sourceRange and anchors it at anchor (the top-left cell of the pivot's output) on this sheet. The pivot table part, its cache (definition + records), the workbook <pivotCaches> entry, all relationships and the [Content_Types].xml overrides are written on the next save.

sourceRange may be sheet-qualified ("Data!A1:D100") or a bare range ("A1:D100"); a bare range is resolved on this sheet. Its first row is the header row naming the source fields. opts places those fields on the row, column, value and filter axes.

The pivot cache is written with refreshOnLoad set, so Excel rebuilds the cached values and the rendered layout when the workbook is opened.

opts.CalculatedFields adds calculated (formula) fields as value fields; opts.NumericGroups groups a numeric source field into value ranges; opts.DateGroups groups a date/time field by year, quarter, month or day; and opts.ItemGroups folds selected items of a field into named parent groups. Each grouped field is placed on the row (or, with OnColumn, the column) axis. A workbook that already contains pivot caches is extended: the new cache is allocated a fresh id and parts without disturbing existing pivots.

Limitations: multiple consolidation ranges and external-data caches are out of scope. Pivot slicers and timelines can be read (Sheet.Slicers, Workbook.Slicers, Sheet.Timelines, Workbook.Timelines) and round-trip byte-for-byte, but creating them is not yet supported (see the package documentation).

func (*Sheet) AddScenario 

func (s *Sheet) AddScenario(sc Scenario) error

AddScenario adds a what-if scenario to the sheet. The name must be non-empty and unique (case-insensitively) among the sheet's scenarios, and the scenario must reference at least one changing cell; each input cell reference is validated. Adding a scenario marks the sheet dirty so its worksheet part is regenerated on save (the sheet's other scenarios, if any, are re-emitted from the typed model rather than their preserved bytes).

func (*Sheet) AddSparklineGroup 

func (s *Sheet) AddSparklineGroup(opts SparklineOptions) (*SparklineGroup, error)

AddSparklineGroup adds a sparkline group to the sheet's worksheet extension list. Type defaults to SparklineLine; at least one (data range, location cell) mapping is required. When the sheet already carries sparkline groups, the new group is appended to the existing extension. It returns a read-only view of the group just added.

func (*Sheet) AddTable 

func (s *Sheet) AddTable(cellRange string, opts TableOptions) (*Table, error)

AddTable creates a table over cellRange (e.g. "A1:D10") and returns it. The range must be a rectangular reference of at least one column; its first row is the header row. Column names are taken from the header cells unless opts.Columns overrides them, and the resolved names are written back into the header cells so the sheet and the table agree.

AddTable works on both created (Create) and opened (Open/OpenReader) workbooks; the table part, its worksheet relationship, the worksheet <tableParts> entry and the [Content_Types].xml override are added on the next save. Existing tables in an opened workbook are left untouched.

func (*Sheet) AutoFilterRange 

func (s *Sheet) AutoFilterRange() (string, bool)

AutoFilterRange returns the sheet's auto-filter range reference (e.g. "A1:F1") and whether an auto-filter is set. It is the read counterpart of SetAutoFilter.

func (*Sheet) Cell 

func (s *Sheet) Cell(ref string) (*Cell, error)

Cell returns the cell at the specified reference (e.g., "A1"). If the cell doesn't exist in the worksheet data, it is created. The reference is canonicalized (case and leading zeros normalized), so "a1" and "A01" address the same cell as "A1" (C126).

Because it creates, Cell is a mutating accessor: probing a range with it materializes a <c>/<row> for every reference visited. Such a cell carries no value, formula, inline string or style and is dropped again when the sheet is serialized, so it neither reaches the file nor inflates <dimension>, but a read-only lookup should use FindCell (or GetCellValue) instead (C425).

A chartsheet, dialogsheet or macrosheet has no cell grid; Cell returns ErrNotWorksheet for one.

func (*Sheet) CellByRowCol 

func (s *Sheet) CellByRowCol(row, col int) (*Cell, error)

CellByRowCol returns the cell at the specified row and column (1-based).

func (*Sheet) CellValue added in v0.2.0 

func (s *Sheet) CellValue(ref string) (string, error)

CellValue returns the cell's stored value as a string: the resolved text of a shared or inline string, and otherwise the raw <v> literal. It is NOT the display value — the cell's number format is not applied, so a date reads back as its serial and 0.5 formatted as "50%" reads back as "0.5". Use Sheet.Text for the formatted rendering. An absent cell yields "" with no error; an unparseable reference yields ErrInvalidCell, and a chartsheet / dialogsheet / macrosheet ErrNotWorksheet.

It is the Get-less spelling of GetCellValue, matching the rest of the library's accessors (C565).

func (*Sheet) Charts 

func (s *Sheet) Charts() []*chart.Chart

Charts returns every chart on the sheet: those parsed from the opened file's drawing part and any added this session via AddChart. Each is returned as a parsed *chart.Chart carrying its type, title, categories, and series (names and values recovered from the chart's caches). The slice is nil when the sheet has no charts.

Chartsheets are included: a chartsheet has no cell grid, so its drawing reference is read straight from its preserved part rather than through a worksheet model, and the chart it anchors is then resolved the same way a worksheet's is (C564).

func (*Sheet) ClearFilterColumns 

func (s *Sheet) ClearFilterColumns()

ClearFilterColumns removes all per-column filter predicates while leaving the auto-filter range in place.

func (*Sheet) ClearPrintArea 

func (s *Sheet) ClearPrintArea()

ClearPrintArea removes the sheet's print area.

func (*Sheet) ClearPrintTitles 

func (s *Sheet) ClearPrintTitles()

ClearPrintTitles removes the sheet's print titles.

func (*Sheet) Cols 

func (s *Sheet) Cols() int

Cols returns the number of used columns (maximum column across all rows).

func (*Sheet) ColumnCollapsed 

func (s *Sheet) ColumnCollapsed(col int) bool

ColumnCollapsed reports whether a grouped column is collapsed.

func (*Sheet) ColumnHidden 

func (s *Sheet) ColumnHidden(col int) bool

ColumnHidden reports whether a column (1-based) is hidden.

func (*Sheet) ColumnOutlineLevel 

func (s *Sheet) ColumnOutlineLevel(col int) uint8

ColumnOutlineLevel returns a column's outline (grouping) level, 0 when the column is ungrouped.

func (*Sheet) ColumnWidth 

func (s *Sheet) ColumnWidth(col int) (width float64, ok bool)

ColumnWidth returns the configured width of a column (1-based) and whether a width is set for it. The width is in Excel column-width units (character widths of the default font), matching SetColWidth. When the column has no explicit width the sheet default applies and ok is false.

func (*Sheet) Comments 

func (s *Sheet) Comments() []*Comment

Comments returns every comment on the sheet as a unified list, merging modern threaded comments and legacy notes. Threaded comments appear as top-level entries with their Replies attached; a legacy note on a cell that also has a threaded comment is treated as the threaded comment's back-compat fallback and is not reported separately.

func (*Sheet) ConditionalFormats 

func (s *Sheet) ConditionalFormats() []*ConditionalFormat

ConditionalFormats returns the sheet's conditional-formatting blocks, in document order. The returned slice is nil when the sheet has none. To create blocks use Sheet.AddConditionalFormat.

func (*Sheet) DataValidations 

func (s *Sheet) DataValidations() []*DataValidation

DataValidations returns the data-validation rules defined on the sheet, in document order. It is the read counterpart of AddDataValidation; the returned slice is nil when the sheet has none.

func (*Sheet) FilterColumns 

func (s *Sheet) FilterColumns() []FilterColumn

FilterColumns returns the per-column filter predicates of the sheet's auto-filter, in document order. It returns nil when no auto-filter or no column filters are set.

func (*Sheet) FindCell added in v0.2.0 

func (s *Sheet) FindCell(ref string) *Cell

FindCell returns a handle to the cell at ref without creating anything. Unlike Cell it is a read-only lookup: an absent cell, an unparseable reference, an empty sheet or a non-worksheet sheet all yield nil, so scanning a range never spawns phantom <c>/<row> entries in the model (C425).

func (*Sheet) FormControls 

func (s *Sheet) FormControls() []FormControl

FormControls returns the legacy form controls on the sheet, in the order their shapes appear in the sheet's VML drawing. Buttons, checkboxes, dropdowns, list boxes, option buttons, spinners, and scroll bars are all reported with their linked cell. Extraction is read-only.

func (*Sheet) FreezePanes 

func (s *Sheet) FreezePanes(cellRef string) error

FreezePanes freezes rows and columns at the specified cell reference. For example, "B2" freezes row 1 and column A. The reference is canonicalized, so "b2" behaves like "B2". Freezing at A1 freezes nothing: it removes any existing pane instead of emitting a frozen pane with no splits, which Excel flags as invalid (C133).

func (*Sheet) FrozenPanes 

func (s *Sheet) FrozenPanes() (cols, rows int, ok bool)

FrozenPanes reports the sheet's frozen-pane split: cols is the number of frozen (always-visible) leading columns, rows the number of frozen leading rows, and ok is true when the sheet has a frozen pane. It reads the sheetView pane element written by FreezePanes; ok is false for a sheet with no pane or with a non-frozen (scrolling split) pane, in which case cols and rows are zero. This is the read counterpart of FreezePanes.

func (*Sheet) GetCellValue deprecated 

func (s *Sheet) GetCellValue(ref string) (string, error)

GetCellValue returns the cell's stored value as a string.

Deprecated: use CellValue. Go accessors do not carry a Get prefix, and this was one of a handful of methods library-wide that did (C565).

func (*Sheet) GroupColumns 

func (s *Sheet) GroupColumns(startCol, endCol int) error

GroupColumns increases the outline level of every column in [startCol, endCol] (1-based, inclusive) by one, up to Excel's maximum of 7.

func (*Sheet) GroupRows 

func (s *Sheet) GroupRows(startRow, endRow int) error

GroupRows increases the outline level of every row in [startRow, endRow] (1-based, inclusive) by one, up to Excel's maximum of 7. It is the counterpart of UngroupRows.

func (*Sheet) HeaderFooter 

func (s *Sheet) HeaderFooter() (HeaderFooter, bool)

HeaderFooter returns the sheet's header/footer settings and whether a <headerFooter> element is present. 

func (s *Sheet) Hyperlinks() []*Hyperlink

Hyperlinks returns every hyperlink on the sheet, in document order. The returned slice is nil when the sheet has none.

func (*Sheet) Images 

func (s *Sheet) Images() []*Image

Images returns every image on the sheet: those loaded from the opened file's drawing part and any added this session via AddImage. The returned slice is nil when the sheet has no images.

func (*Sheet) Index 

func (s *Sheet) Index() int

Index returns the sheet index within the workbook.

func (*Sheet) MergeCells 

func (s *Sheet) MergeCells(startRef, endRef string) error

MergeCells merges a range of cells. The references are validated and normalized to top-left:bottom-right order; invalid references return ErrInvalidRange. A merge that duplicates or overlaps an existing merged range is rejected — Excel refuses overlapping merges (C128).

func (*Sheet) MergedCells 

func (s *Sheet) MergedCells() []string

MergedCells returns the merged-range references on the sheet (e.g. []string{"A1:B2", "D4:D8"}), in document order. It is the read counterpart of MergeCells; the returned slice is nil when the sheet has no merged ranges.

func (*Sheet) Name 

func (s *Sheet) Name() string

Name returns the sheet name.

func (*Sheet) OutlineSummary 

func (s *Sheet) OutlineSummary() (below, right bool)

OutlineSummary reports the sheet's outline summary placement: below reports whether summary rows sit below their detail (the default), right whether summary columns sit to the right of their detail (the default). Both default to true when unset (the OOXML default).

func (*Sheet) PageMargins 

func (s *Sheet) PageMargins() (PageMargins, bool)

PageMargins returns the sheet's page margins and whether a <pageMargins> element is present.

func (*Sheet) PageSetup 

func (s *Sheet) PageSetup() (PageSetup, bool)

PageSetup returns the sheet's page-setup settings and whether a <pageSetup> element is present. When absent, the zero PageSetup and false are returned.

func (*Sheet) PivotTables 

func (s *Sheet) PivotTables() []*PivotTable

PivotTables returns every pivot table anchored on the sheet: those parsed from the opened file and any added this session via AddPivotTable, in that order. The slice is nil when the sheet has no pivot tables.

func (*Sheet) PrintArea 

func (s *Sheet) PrintArea() string

PrintArea returns the raw value of the sheet's _xlnm.Print_Area defined name (e.g. "Sheet1!$A$1:$D$20"), or "" when no print area is set.

func (*Sheet) PrintOptions 

func (s *Sheet) PrintOptions() (PrintOptions, bool)

PrintOptions returns the sheet's print options and whether a <printOptions> element is present.

func (*Sheet) PrintTitles 

func (s *Sheet) PrintTitles() string

PrintTitles returns the raw value of the sheet's _xlnm.Print_Titles defined name (e.g. "Sheet1!$A:$B,Sheet1!$1:$1"), or "" when no print titles are set.

func (*Sheet) Protect 

func (s *Sheet) Protect(opts SheetProtectionOptions) error

Protect turns on sheet protection with the given options, replacing any existing <sheetProtection> element. It works on both created and opened workbooks; a save regenerates the worksheet with the new protection.

It returns ErrNotWorksheet on a chartsheet, dialogsheet or macrosheet. Excel does support protecting a chartsheet, but such a sheet is round-tripped verbatim here rather than regenerated from a worksheet model, so the setting could not be persisted; reporting that is better than accepting the call and discarding it at save (C423).

Excel sheet protection is a UI guard, not encryption. Even with a password it is trivially removed; do not use it to protect confidential data.

func (*Sheet) Protection 

func (s *Sheet) Protection() *SheetProtection

Protection returns the sheet's protection state, or nil when the sheet has no <sheetProtection> element. It is the read counterpart of Protect/Unprotect.

func (*Sheet) RemoveAutoFilter 

func (s *Sheet) RemoveAutoFilter()

RemoveAutoFilter removes the auto-filter from the sheet.

func (*Sheet) RemoveSortState 

func (s *Sheet) RemoveSortState()

RemoveSortState removes the sheet's sort state, both the worksheet-level <sortState> element and the one nested in <autoFilter>. It removes exactly what SortState reads: removing only the worksheet-level element left SortState still reporting ok on the files — common Excel output — whose sort state lives inside <autoFilter> (C536). The auto-filter range itself is kept; use RemoveAutoFilter to drop that.

func (*Sheet) ReplaceText 

func (s *Sheet) ReplaceText(replacements map[string]string)

ReplaceText performs text replacement on this sheet only. See Workbook.ReplaceText for the matching rules.

func (*Sheet) RightToLeft 

func (s *Sheet) RightToLeft() bool

RightToLeft reports whether the sheet is displayed right-to-left. Defaults to false when unset.

func (*Sheet) RowCollapsed 

func (s *Sheet) RowCollapsed(row int) bool

RowCollapsed reports whether a grouped row is collapsed.

func (*Sheet) RowHeight 

func (s *Sheet) RowHeight(row int) (height float64, ok bool)

RowHeight returns the configured height of a row (1-based) and whether a height is set for it. The height is in points, matching SetRowHeight. When the row has no explicit height the sheet default applies and ok is false.

func (*Sheet) RowHidden 

func (s *Sheet) RowHidden(row int) bool

RowHidden reports whether a row (1-based) is hidden.

func (*Sheet) RowOutlineLevel 

func (s *Sheet) RowOutlineLevel(row int) uint8

RowOutlineLevel returns a row's outline (grouping) level, 0 when the row is ungrouped.

func (*Sheet) Rows 

func (s *Sheet) Rows() int

Rows returns the number of used rows. Rows holding nothing but cells a read-only Cell probe materialized are not counted — they carry no content and are dropped at serialization (C425).

func (*Sheet) Scenarios 

func (s *Sheet) Scenarios() []Scenario

Scenarios returns the what-if scenarios defined on the sheet, in document order. It is read-only; the returned slice is a copy.

func (*Sheet) SetAutoFilter 

func (s *Sheet) SetAutoFilter(rangeRef string) error

SetAutoFilter sets an auto-filter on the specified range (e.g., "A1:F1"). The range must be a single rectangular reference; an unparseable one returns ErrInvalidRange rather than reaching <autoFilter ref="...">, where it makes Excel offer to repair the workbook (C538).

Only the <autoFilter> element is written. Excel additionally maintains a hidden sheet-scoped _xlnm._FilterDatabase defined name over the same range; this package neither creates it here nor removes it in RemoveAutoFilter. Excel recreates it when the user next touches the filter, so its absence is not an error, but a workbook opened, filtered here and reopened will not show the name until then.

func (*Sheet) SetCellValue 

func (s *Sheet) SetCellValue(ref string, value interface{}) error

SetCellValue sets the value of a cell.

func (*Sheet) SetColWidth 

func (s *Sheet) SetColWidth(col int, width float64) error

SetColWidth sets the width of a column (1-based). Existing <col> entries covering a range of columns (min < max) are split so the target column is carved out with the new width while the rest of the range keeps its original properties; appending an overlapping entry would be ambiguous and is rejected by Excel (C127). It shares the carve with every other column mutator through editColumn (C383).

A chartsheet, dialogsheet or macrosheet has no column grid; SetColWidth returns ErrNotWorksheet for one.

func (*Sheet) SetColumnCollapsed 

func (s *Sheet) SetColumnCollapsed(col int, collapsed bool) error

SetColumnCollapsed sets a column's collapsed flag (whether its outline group is collapsed).

func (*Sheet) SetColumnHidden 

func (s *Sheet) SetColumnHidden(col int, hidden bool) error

SetColumnHidden hides (hidden=true) or shows (hidden=false) a column (1-based). It is the write counterpart of ColumnHidden. A column entry spanning a range is split so only the target column is affected.

func (*Sheet) SetColumnOutlineLevel 

func (s *Sheet) SetColumnOutlineLevel(col int, level uint8) error

SetColumnOutlineLevel sets a column's outline (grouping) level. Level 0 clears the grouping; levels above 7 (Excel's maximum) are rejected.

func (*Sheet) SetFilterColumn 

func (s *Sheet) SetFilterColumn(fc FilterColumn) error

SetFilterColumn sets (or replaces) the filter predicate for a single column of the sheet's auto-filter. An auto-filter range must already be set with SetAutoFilter.

The predicate is recorded but not applied: this package does not evaluate it against the sheet's data and does not hide the rows it excludes. Excel persists a filtered-out row as <row hidden="1">, and writes no such flags here, so the saved workbook opens showing every row with the filter dropdown indicating a predicate is set. Re-applying the filter in Excel (Data > Reapply) hides the rows. Set the row-hidden flags with SetRowHidden if the file must open already filtered.

func (*Sheet) SetHeaderFooter 

func (s *Sheet) SetHeaderFooter(hf HeaderFooter) error

SetHeaderFooter sets the sheet's header/footer settings, replacing any existing <headerFooter> element. An empty header/footer string is treated as absent (the child element is omitted); a non-empty string emits the element.

It returns ErrNotWorksheet on a chartsheet, dialogsheet or macrosheet: such a sheet round-trips verbatim and is never regenerated from a worksheet model, so the setting would be discarded at save (C423).

func (*Sheet) SetName 

func (s *Sheet) SetName(name string) error

SetName renames the sheet. The name must be a legal Excel sheet name (see ValidateSheetName) and must not collide (case-insensitively) with another sheet in the workbook; invalid or duplicate names are rejected with an error and the sheet is left unchanged (C71).

The name lives in workbook.xml, which is always regenerated, so renaming does not mark the worksheet part dirty: an otherwise untouched sheet still round-trips byte-for-byte and keeps the workbook's calcChain, whether or not the sheet's model happened to be materialized first (C545).

Limitation: renaming does not rewrite references to the old name held in formulas or defined names; those still refer to the previous name.

A *Sheet obtained before a DeleteSheet call that removed it is detached from its workbook; SetName on such a handle changes nothing.

func (*Sheet) SetOutlineSummary 

func (s *Sheet) SetOutlineSummary(below, right bool)

SetOutlineSummary sets the sheet's outline summary placement (see OutlineSummary). It writes the sheetPr/outlinePr element.

func (*Sheet) SetPageMargins 

func (s *Sheet) SetPageMargins(m PageMargins) error

SetPageMargins sets the sheet's page margins (in inches), creating the <pageMargins> element if absent.

It returns ErrNotWorksheet on a chartsheet, dialogsheet or macrosheet, like its three siblings: such a sheet round-trips verbatim and is never regenerated from a worksheet model, so the margins would be discarded at save (C423).

func (*Sheet) SetPageSetup 

func (s *Sheet) SetPageSetup(ps PageSetup) error

SetPageSetup applies the given page-setup settings, creating the <pageSetup> element if the sheet lacks one. Only the modeled fields are written; other attributes on a pre-existing element are preserved, so a getter/modify/setter round-trip does not drop a printer-settings relationship or DPI values.

It returns ErrNotWorksheet on a chartsheet, dialogsheet or macrosheet: such a sheet round-trips verbatim and is never regenerated from a worksheet model, so the setting would be discarded at save (C423).

func (*Sheet) SetPrintArea 

func (s *Sheet) SetPrintArea(ranges ...string) error

SetPrintArea sets the sheet's print area from one or more A1-style ranges (e.g. "A1:D20"). Each range is made absolute and qualified with the sheet name, then stored in the reserved _xlnm.Print_Area defined name scoped to this sheet. Passing no ranges clears the print area.

The stored value embeds the sheet's name literally, and renaming the sheet with SetName does not rewrite it, so the defined name is left pointing at the old name. Call SetPrintArea again after a rename.

func (*Sheet) SetPrintOptions 

func (s *Sheet) SetPrintOptions(po PrintOptions) error

SetPrintOptions sets the sheet's print options, replacing any existing <printOptions> element.

It returns ErrNotWorksheet on a chartsheet, dialogsheet or macrosheet: such a sheet round-trips verbatim and is never regenerated from a worksheet model, so the setting would be discarded at save (C423).

func (*Sheet) SetPrintTitles 

func (s *Sheet) SetPrintTitles(rows, cols string) error

SetPrintTitles sets the rows and/or columns that repeat on every printed page. rows is a row range such as "1:1" (repeat the first row) and cols is a column range such as "A:B"; either may be empty to leave that dimension unset. The value is stored in the reserved _xlnm.Print_Titles defined name scoped to this sheet. Passing both empty clears the print titles.

As with SetPrintArea, the stored value embeds the sheet's name literally and a later SetName does not rewrite it.

func (*Sheet) SetRightToLeft 

func (s *Sheet) SetRightToLeft(rtl bool)

SetRightToLeft sets whether the sheet is displayed right-to-left (columns run from right to left).

func (*Sheet) SetRowCollapsed 

func (s *Sheet) SetRowCollapsed(row int, collapsed bool) error

SetRowCollapsed sets a row's collapsed flag (whether its outline group is collapsed). Note that collapsing an outline for display also requires hiding the member rows; this sets only the flag on the summary row.

func (*Sheet) SetRowHeight 

func (s *Sheet) SetRowHeight(row int, height float64) error

SetRowHeight sets the height of a row (1-based). The row must lie inside the worksheet grid; a row past MaxRow yields ErrInvalidCell, matching editRow and SetColWidth rather than silently appending an out-of-grid <row> (C546).

func (*Sheet) SetRowHidden 

func (s *Sheet) SetRowHidden(row int, hidden bool) error

SetRowHidden hides (hidden=true) or shows (hidden=false) a row (1-based). It is the write counterpart of RowHidden.

func (*Sheet) SetRowOutlineLevel 

func (s *Sheet) SetRowOutlineLevel(row int, level uint8) error

SetRowOutlineLevel sets a row's outline (grouping) level. Level 0 clears the grouping; levels above 7 (Excel's maximum) are rejected.

func (*Sheet) SetShowFormulas 

func (s *Sheet) SetShowFormulas(show bool)

SetShowFormulas sets whether cell formulas are shown instead of their results.

func (*Sheet) SetShowGridLines 

func (s *Sheet) SetShowGridLines(show bool)

SetShowGridLines sets whether grid lines are displayed.

func (*Sheet) SetShowRowColHeaders 

func (s *Sheet) SetShowRowColHeaders(show bool)

SetShowRowColHeaders sets whether row and column headers are shown.

func (*Sheet) SetShowRuler 

func (s *Sheet) SetShowRuler(show bool)

SetShowRuler sets whether the ruler is shown in page-layout view.

func (*Sheet) SetShowZeros 

func (s *Sheet) SetShowZeros(show bool)

SetShowZeros sets whether cells holding zero display the value (true) or appear blank (false).

func (*Sheet) SetSortState 

func (s *Sheet) SetSortState(ss SortState) error

SetSortState writes the sheet's sort state. It updates the element the sheet already carries — the worksheet-level <sortState>, or the one nested in <autoFilter> when that is where the sort state lives — and creates a worksheet-level element only when the sheet has neither. The Ref must be set.

Only the modeled fields are overwritten; the target element's unmodeled children (the x14 sort-by-color conditions in its extLst) are left alone. Rebuilding the element from scratch dropped them on every call.

func (*Sheet) SetTabColor 

func (s *Sheet) SetTabColor(hexColor string)

SetTabColor sets the sheet tab color as a hex RGB string (e.g., "FF0000").

func (*Sheet) SetView 

func (s *Sheet) SetView(view string) error

SetView sets the sheet's view mode. Valid values are ViewNormal, ViewPageLayout and ViewPageBreakPreview; any other value is rejected. ViewNormal is the OOXML default and is emitted as the absence of the attribute so a normal sheet is not perturbed.

func (*Sheet) SetVisibility 

func (s *Sheet) SetVisibility(v SheetVisibility) error

SetVisibility sets the sheet's visibility. Hiding is refused when the sheet is the workbook's last visible one — Excel requires at least one visible sheet and rejects a workbook without one. The change is applied to the workbook model directly (workbook.xml is always regenerated on save), so it takes effect without dirtying the worksheet part.

func (*Sheet) SetVisible 

func (s *Sheet) SetVisible(visible bool) error

SetVisible shows (visible=true) or hides (visible=false) the sheet. It is a convenience wrapper over SetVisibility using SheetHidden for the hidden state; use SetVisibility directly for veryHidden.

func (*Sheet) SetZoom 

func (s *Sheet) SetZoom(percent uint32)

SetZoom sets the zoom percentage for the sheet view (e.g., 100 for 100%).

func (*Sheet) ShowFormulas 

func (s *Sheet) ShowFormulas() bool

ShowFormulas reports whether cell formulas are shown instead of their results. Defaults to false when unset.

func (*Sheet) ShowRowColHeaders 

func (s *Sheet) ShowRowColHeaders() bool

ShowRowColHeaders reports whether row and column headers are shown. Defaults to true when unset (the OOXML default).

func (*Sheet) ShowRuler 

func (s *Sheet) ShowRuler() bool

ShowRuler reports whether the ruler is shown in page-layout view. Defaults to true when unset.

func (*Sheet) ShowZeros 

func (s *Sheet) ShowZeros() bool

ShowZeros reports whether zero values are shown. Defaults to true when unset.

func (*Sheet) Slicers 

func (s *Sheet) Slicers() []*Slicer

Slicers returns every slicer anchored on the sheet, resolving each slicer's cache (and therefore its source field and controlled pivot tables). The slice is nil when the sheet has no slicers.

func (*Sheet) SortState 

func (s *Sheet) SortState() (SortState, bool)

SortState returns the sheet's sort state. It reads a worksheet-level sortState element when present, otherwise the sortState nested in the auto-filter. The second result reports whether a sort state exists.

func (*Sheet) Sparklines 

func (s *Sheet) Sparklines() []*SparklineGroup

Sparklines returns the sparkline groups defined on the sheet (read from the worksheet extension list), or nil when the sheet has none. The returned groups are live handles: their setters and Delete write through to the workbook.

func (*Sheet) SplitPanePosition 

func (s *Sheet) SplitPanePosition() (xSplit, ySplit float64, topLeftCell string, ok bool)

SplitPanePosition reports a scrolling split created by SplitPanes: the split offsets in twips, the top-left cell of the bottom-right pane, and ok=true when the sheet has a split pane. ok is false for no pane or a frozen pane (see FrozenPanes for the frozen case).

func (*Sheet) SplitPanes 

func (s *Sheet) SplitPanes(xSplit, ySplit float64, topLeftCell, activePane string) error

SplitPanes creates a scrolling (unfrozen) split of the sheet view, distinct from FreezePanes which freezes rows/columns. xSplit and ySplit are the split bar positions measured in twentieths of a point (twips) from the left and top of the sheet; topLeftCell is the cell shown at the top-left of the bottom-right pane. activePane selects the initially active pane ("topLeft", "topRight", "bottomLeft" or "bottomRight"); when empty it is derived from which splits are present. Both offsets zero removes any existing pane.

func (*Sheet) Tables 

func (s *Sheet) Tables() []*Table

Tables returns every table on the sheet: those parsed from the opened file and any added this session via AddTable, in that order. The slice is nil when the sheet has no tables.

func (*Sheet) Text 

func (s *Sheet) Text() string

Text returns the sheet's cell values and comments as a single plain string.

Cells are laid out row-major: within a populated row the cells are separated by a tab ("\t") and positioned at their column (missing interior cells become empty fields); rows are separated by "\n". Rows with no populated cells are skipped rather than emitted as blank lines. Cell values are resolved the same way as Cell.String — shared strings and rich text are flattened to their text, while numbers, dates, and booleans come through as their raw stored value (Excel serials for dates), not the number-format-applied display text.

Cell comments (legacy notes and threaded comments, including replies) follow the grid, one per line, ordered by their anchoring cell.

func (*Sheet) Timelines 

func (s *Sheet) Timelines() []*Timeline

Timelines returns every timeline anchored on the sheet, resolving each timeline's cache. The slice is nil when the sheet has no timelines.

func (*Sheet) UnfreezePanes 

func (s *Sheet) UnfreezePanes()

UnfreezePanes removes any frozen panes from the sheet, along with selections that referenced a pane (a pane-scoped selection is invalid once the pane is gone).

func (*Sheet) UngroupColumns 

func (s *Sheet) UngroupColumns(startCol, endCol int) error

UngroupColumns decreases the outline level of every column in [startCol, endCol] (1-based, inclusive) by one, down to zero.

func (*Sheet) UngroupRows 

func (s *Sheet) UngroupRows(startRow, endRow int) error

UngroupRows decreases the outline level of every row in [startRow, endRow] (1-based, inclusive) by one, down to zero.

func (*Sheet) UnmergeCells 

func (s *Sheet) UnmergeCells(startRef, endRef string) error

UnmergeCells unmerges a range of cells.

func (*Sheet) Unprotect 

func (s *Sheet) Unprotect()

Unprotect removes sheet protection, if any.

func (*Sheet) View 

func (s *Sheet) View() string

View returns the sheet's view mode: ViewNormal (the default), ViewPageLayout, or ViewPageBreakPreview.

func (*Sheet) Visibility 

func (s *Sheet) Visibility() SheetVisibility

Visibility returns the sheet's visibility state.

func (*Sheet) Visible 

func (s *Sheet) Visible() bool

Visible reports whether the sheet is shown (neither hidden nor very hidden).

type SheetProtection 

type SheetProtection struct {
	// contains filtered or unexported fields
}

SheetProtection is a read-only view of a sheet's <sheetProtection> element. Each operation accessor reports whether that operation is LOCKED (disallowed) while protection is enabled.

Note on defaults: in OOXML the format/insert/delete/sort/autoFilter/pivotTables operations default to locked when protection is on (their attribute is omitted when locked and written as "0" only to unlock), whereas objects and scenarios default to unlocked, and cell selection defaults to allowed. These accessors return the effective state after applying those defaults.

Excel's sheet protection is a UI convenience, not encryption: the content is not protected cryptographically and any tool can clear it. HasPassword only reports that a (weak, legacy or hashed) password guard is present; the password itself is never exposed or recovered.

func (*SheetProtection) AutoFilter 

func (p *SheetProtection) AutoFilter() bool

AutoFilter reports whether using AutoFilter is locked.

func (*SheetProtection) DeleteColumns 

func (p *SheetProtection) DeleteColumns() bool

DeleteColumns reports whether deleting columns is locked.

func (*SheetProtection) DeleteRows 

func (p *SheetProtection) DeleteRows() bool

DeleteRows reports whether deleting rows is locked.

func (*SheetProtection) Enabled 

func (p *SheetProtection) Enabled() bool

Enabled reports whether sheet protection is turned on (<sheetProtection sheet="1">).

func (*SheetProtection) FormatCells 

func (p *SheetProtection) FormatCells() bool

FormatCells reports whether formatting cells is locked.

func (*SheetProtection) FormatColumns 

func (p *SheetProtection) FormatColumns() bool

FormatColumns reports whether formatting columns is locked.

func (*SheetProtection) FormatRows 

func (p *SheetProtection) FormatRows() bool

FormatRows reports whether formatting rows is locked.

func (*SheetProtection) HasPassword 

func (p *SheetProtection) HasPassword() bool

HasPassword reports whether a password guard is present (either the legacy 16-bit hash or a modern hashValue/saltValue). The password is never exposed.

func (*SheetProtection) InsertColumns 

func (p *SheetProtection) InsertColumns() bool

InsertColumns reports whether inserting columns is locked. 

func (p *SheetProtection) InsertHyperlinks() bool

InsertHyperlinks reports whether inserting hyperlinks is locked.

func (*SheetProtection) InsertRows 

func (p *SheetProtection) InsertRows() bool

InsertRows reports whether inserting rows is locked.

func (*SheetProtection) Objects 

func (p *SheetProtection) Objects() bool

Objects reports whether editing objects is locked.

func (*SheetProtection) PivotTables 

func (p *SheetProtection) PivotTables() bool

PivotTables reports whether using PivotTables is locked.

func (*SheetProtection) Scenarios 

func (p *SheetProtection) Scenarios() bool

Scenarios reports whether editing scenarios is locked.

func (*SheetProtection) SelectLockedCells 

func (p *SheetProtection) SelectLockedCells() bool

SelectLockedCells reports whether selecting locked cells is disallowed.

func (*SheetProtection) SelectUnlockedCells 

func (p *SheetProtection) SelectUnlockedCells() bool

SelectUnlockedCells reports whether selecting unlocked cells is disallowed.

func (*SheetProtection) Sort 

func (p *SheetProtection) Sort() bool

Sort reports whether sorting is locked.

type SheetProtectionOptions 

type SheetProtectionOptions struct {
	// Password, when non-empty, is guarded with Excel's legacy 16-bit password
	// hash. This is obfuscation, not security — it is trivially removed and must
	// not be relied on to protect confidential data.
	Password string

	AllowFormatCells      bool
	AllowFormatColumns    bool
	AllowFormatRows       bool
	AllowInsertColumns    bool
	AllowInsertRows       bool
	AllowInsertHyperlinks bool
	AllowDeleteColumns    bool
	AllowDeleteRows       bool
	AllowSort             bool
	AllowAutoFilter       bool
	AllowPivotTables      bool
	AllowEditObjects      bool
	AllowEditScenarios    bool

	// DisableSelectLockedCells and DisableSelectUnlockedCells remove the
	// selection that protection allows by default.
	DisableSelectLockedCells   bool
	DisableSelectUnlockedCells bool
}

SheetProtectionOptions configures Sheet.Protect. The zero value reproduces Excel's default "Protect Sheet" behavior: protection is on, every editing operation is locked, and only cell selection is allowed. Set an Allow* field to unlock that operation, or a Disable* field to further restrict selection.

type SheetVisibility 

type SheetVisibility string

SheetVisibility is a worksheet's visibility state, stored on the workbook's <sheet state> attribute. A hidden sheet can be unhidden through Excel's UI; a very-hidden sheet can only be revealed programmatically (or via VBA). 

const (
	// SheetVisible is the default: the sheet tab is shown.
	SheetVisible SheetVisibility = ""
	// SheetHidden hides the sheet; the user can unhide it from the UI.
	SheetHidden SheetVisibility = "hidden"
	// SheetVeryHidden hides the sheet from the unhide UI entirely.
	SheetVeryHidden SheetVisibility = "veryHidden"
)

type Slicer 

type Slicer struct {
	// contains filtered or unexported fields
}

Slicer is a read view of a pivot slicer: an on-sheet control that filters one or more pivot tables by the distinct values of a single pivot field. A Slicer returned by Sheet.Slicers or Workbook.Slicers reflects the slicer as stored in the opened workbook; its accessors are read-only.

Creating slicers is not yet supported (see the package documentation); an opened workbook's slicers, slicer caches and their worksheet/workbook extension references round-trip byte-for-byte.

func (*Slicer) Cache 

func (s *Slicer) Cache() string

Cache returns the name of the slicer cache the slicer draws from.

func (*Slicer) Caption 

func (s *Slicer) Caption() string

Caption returns the slicer's display caption, or "" when it uses the field name.

func (*Slicer) ColumnCount 

func (s *Slicer) ColumnCount() int

ColumnCount returns the number of button columns the slicer lays its items out in, or 0 when unset.

func (*Slicer) Name 

func (s *Slicer) Name() string

Name returns the slicer's unique name.

func (*Slicer) PivotTables 

func (s *Slicer) PivotTables() []string

PivotTables returns the names of the pivot tables the slicer controls, or nil when the slicer cache could not be resolved.

func (*Slicer) SheetName 

func (s *Slicer) SheetName() string

SheetName returns the name of the sheet the slicer is anchored on.

func (*Slicer) SourceField 

func (s *Slicer) SourceField() string

SourceField returns the pivot field the slicer filters (e.g. "Region"), or "" when the slicer cache could not be resolved.

type SortCondition 

type SortCondition struct {
	// Ref is the range the key sorts on (e.g. "B2:B100").
	Ref string
	// Descending sorts high-to-low.
	Descending bool
	// SortBy selects what to sort on (one of the SortBy* constants; empty means
	// value).
	SortBy string
	// CustomList is a comma-separated custom sort order.
	CustomList string
}

SortCondition is a single sort key (CT_SortCondition).

type SortState 

type SortState struct {
	// Ref is the sorted range (e.g. "A2:D100").
	Ref string
	// CaseSensitive sorts case-sensitively.
	CaseSensitive bool
	// ColumnSort sorts left-to-right (by columns) instead of top-to-bottom.
	ColumnSort bool
	// SortMethod selects a stroke/pinYin method for East-Asian sorts
	// (ST_SortMethod: "stroke", "pinYin", "none").
	SortMethod string
	// Conditions lists the sort conditions in priority order.
	Conditions []SortCondition
}

SortState describes the sort applied to a range or auto-filter (CT_SortState).

type Sparkline 

type Sparkline struct {
	// DataRange is the source data reference (xm:f).
	DataRange string
	// LocationCell is the cell the sparkline is drawn in (xm:sqref).
	LocationCell string
}

Sparkline is one (data range, location cell) mapping within a group.

type SparklineData 

type SparklineData struct {
	// DataRange is the source range, e.g. "Sheet1!A1:D1" (a sheet-qualified
	// reference is recommended so the sparkline survives being moved).
	DataRange string
	// LocationCell is the single cell the sparkline is rendered in, e.g. "E1".
	LocationCell string
}

SparklineData maps one source data range to the single cell the sparkline is drawn in.

type SparklineGroup 

type SparklineGroup struct {
	// contains filtered or unexported fields
}

SparklineGroup is a live handle on one x14:sparklineGroup on a sheet, returned by Sheet.Sparklines and Sheet.AddSparklineGroup. Its setters and Delete write through to the workbook so a subsequent save persists them.

A handle stays valid across later AddSparklineGroup calls. It identifies its group by the set of cells the group draws in, re-resolving the backing model element on each use, rather than holding a pointer into the sheet's []Groups slice — an append reallocates that slice, which detached every previously returned handle so setter calls mutated dead memory and vanished at save (C428). This is the same convention Hyperlink follows (C246).

Deleting a group invalidates handles on that group only; its own Delete and setters then become no-ops. In the pathological case of two groups drawing in exactly the same cells, a handle resolves to the first.

func (*SparklineGroup) Delete 

func (g *SparklineGroup) Delete()

Delete removes this sparkline group from its sheet, writing the change through to the workbook. When it was the sheet's only group the sparkline extension is removed entirely. Handles on other groups stay valid; a second Delete on this group is a no-op.

func (*SparklineGroup) Markers 

func (g *SparklineGroup) Markers() bool

Markers reports whether point markers are enabled (a line-sparkline group with markers turned on). It is false when the flag is unset.

func (*SparklineGroup) SeriesColor 

func (g *SparklineGroup) SeriesColor() string

SeriesColor returns the group's series color as a hex RGB string (as stored, which may be 8-digit ARGB), or "" when the color is theme-based or unset.

func (*SparklineGroup) SetAxisColor 

func (g *SparklineGroup) SetAxisColor(hex string)

SetAxisColor sets the horizontal-axis color. Empty clears it.

func (*SparklineGroup) SetFirst 

func (g *SparklineGroup) SetFirst(on bool)

SetFirst toggles highlighting of the first point.

func (*SparklineGroup) SetFirstColor 

func (g *SparklineGroup) SetFirstColor(hex string)

SetFirstColor sets the color of the first point. Empty clears it.

func (*SparklineGroup) SetHigh 

func (g *SparklineGroup) SetHigh(on bool)

SetHigh toggles highlighting of the highest point.

func (*SparklineGroup) SetHighColor 

func (g *SparklineGroup) SetHighColor(hex string)

SetHighColor sets the color of the highest point. Empty clears it.

func (*SparklineGroup) SetLast 

func (g *SparklineGroup) SetLast(on bool)

SetLast toggles highlighting of the last point.

func (*SparklineGroup) SetLastColor 

func (g *SparklineGroup) SetLastColor(hex string)

SetLastColor sets the color of the last point. Empty clears it.

func (*SparklineGroup) SetLow 

func (g *SparklineGroup) SetLow(on bool)

SetLow toggles highlighting of the lowest point.

func (*SparklineGroup) SetLowColor 

func (g *SparklineGroup) SetLowColor(hex string)

SetLowColor sets the color of the lowest point. Empty clears it.

func (*SparklineGroup) SetMarkers 

func (g *SparklineGroup) SetMarkers(on bool)

SetMarkers toggles point markers on the group's sparklines (line type).

func (*SparklineGroup) SetMarkersColor 

func (g *SparklineGroup) SetMarkersColor(hex string)

SetMarkersColor sets the color of the point markers (line sparklines). Empty clears it.

func (*SparklineGroup) SetNegative 

func (g *SparklineGroup) SetNegative(on bool)

SetNegative toggles highlighting of negative points.

func (*SparklineGroup) SetNegativeColor 

func (g *SparklineGroup) SetNegativeColor(hex string)

SetNegativeColor sets the color of negative points (win/loss and column sparklines). Empty clears it.

func (*SparklineGroup) SetSeriesColor 

func (g *SparklineGroup) SetSeriesColor(hex string)

SetSeriesColor sets the group's series color (empty clears it).

func (*SparklineGroup) Sparklines 

func (g *SparklineGroup) Sparklines() []Sparkline

Sparklines returns the group's (data range, location cell) mappings.

func (*SparklineGroup) Type 

func (g *SparklineGroup) Type() string

Type returns the group's sparkline type: SparklineLine, SparklineColumn or SparklineWinLoss. It returns SparklineLine for a deleted group.

type SparklineOptions 

type SparklineOptions struct {
	// Type is SparklineLine (default), SparklineColumn or SparklineWinLoss.
	Type string
	// SeriesColor is the sparkline series color as a 6- or 8-digit hex RGB
	// string (e.g. "376092" or "FF376092"); empty leaves the color unset so
	// Excel applies its default.
	SeriesColor string
	// Data is the one or more (data range, location cell) mappings drawn by
	// the group; at least one is required.
	Data []SparklineData
}

SparklineOptions configures a new sparkline group added with AddSparklineGroup.

type StyleManager 

type StyleManager struct {
	// contains filtered or unexported fields
}

StyleManager manages the workbook stylesheet.

func (*StyleManager) AddNamedStyle 

func (sm *StyleManager) AddNamedStyle(ns NamedStyle) (uint32, error)

AddNamedStyle defines a named cell style and returns its xfId (its index into cellStyleXfs), the value ApplyNamedStyle and Cell.SetNamedStyle use to apply it. If a style with the same name already exists it is left untouched and its existing xfId is returned.

func (*StyleManager) AddNumberFormat 

func (sm *StyleManager) AddNumberFormat(code string) uint32

AddNumberFormat registers a custom number format string and returns its ID. If the format string matches a built-in format, the built-in ID is returned.

func (*StyleManager) ApplyNamedStyle 

func (sm *StyleManager) ApplyNamedStyle(name string) (uint32, error)

ApplyNamedStyle creates (or reuses) a cellXfs record linked to the named style and returns its index, ready to pass to Cell.SetStyleIndex. It fails if no style with that name exists.

func (*StyleManager) CellStyleAt added in v0.2.0 

func (sm *StyleManager) CellStyleAt(index uint32) (CellStyle, error)

CellStyleAt returns the CellStyle for the given style index. It is the Get-less spelling of GetCellStyle (C565); the name carries the "At" suffix because CellStyle is also the name of the returned type.

func (*StyleManager) GetCellStyle deprecated 

func (sm *StyleManager) GetCellStyle(index uint32) (CellStyle, error)

GetCellStyle returns the CellStyle for the given style index.

Deprecated: use CellStyleAt. Go accessors do not carry a Get prefix (C565).

func (*StyleManager) NamedStyleXfId 

func (sm *StyleManager) NamedStyleXfId(name string) (uint32, bool)

NamedStyleXfId returns the xfId of the named style with the given name.

func (*StyleManager) NamedStyles 

func (sm *StyleManager) NamedStyles() []NamedStyle

NamedStyles returns every named cell style defined in the workbook.

func (*StyleManager) NewCellStyle 

func (sm *StyleManager) NewCellStyle(style CellStyle) (uint32, error)

NewCellStyle creates a new cell format from the given style definition and returns its 0-based index into cellXfs. The cell format index can be applied to cells via Cell.SetStyleIndex.

type Table 

type Table struct {
	// contains filtered or unexported fields
}

Table is a worksheet table (a.k.a. ListObject): a named, structured range with a header row, optional totals row, per-column metadata and a built-in table style. A Table returned by Sheet.Tables reflects the table as stored in the workbook; the accessors are read-only.

func (*Table) Columns 

func (t *Table) Columns() []TableColumn

Columns returns the table's columns in order.

func (*Table) DisplayName 

func (t *Table) DisplayName() string

DisplayName returns the table's display name.

func (*Table) HeaderRow 

func (t *Table) HeaderRow() bool

HeaderRow reports whether the table shows a header row.

func (*Table) Name 

func (t *Table) Name() string

Name returns the table's name.

func (*Table) Range 

func (t *Table) Range() string

Range returns the table's cell range (e.g. "A1:D10"), covering the header row, the data rows and the totals row (when present).

func (*Table) Style 

func (t *Table) Style() (TableStyle, bool)

Style returns the table's style and banding. The second result is false when the table has no tableStyleInfo.

func (*Table) TotalsRow 

func (t *Table) TotalsRow() bool

TotalsRow reports whether the table shows a totals row.

type TableColumn 

type TableColumn struct {
	// ID is the column's stable identifier within the table.
	ID uint32
	// Name is the column header text.
	Name string
	// TotalsRowFunction is the built-in totals-row aggregation for the column
	// (e.g. "sum", "count", "average", "min", "max", "countNums", "stdDev",
	// "var", "custom"), or "" when the column has no totals function.
	TotalsRowFunction string
	// TotalsRowLabel is the literal label shown in the column's totals cell
	// (used instead of a function, e.g. "Total").
	TotalsRowLabel string
	// CalculatedColumnFormula is the calculated-column formula filled down the
	// column, or "" when the column holds plain values.
	CalculatedColumnFormula string
}

TableColumn describes one column of a table.

type TableOptions 

type TableOptions struct {
	// Name is the table's name and displayName. It must be unique within the
	// workbook (case-insensitively) and a valid Excel table name (a defined
	// name: it cannot look like a cell reference and cannot contain spaces).
	// When empty, a unique name ("Table1", "Table2", ...) is generated.
	Name string
	// Columns overrides the column header names. When nil, names are taken from
	// the header row (the first row of the range); blank or duplicate headers
	// are replaced with "ColumnN". When non-nil, its length must equal the
	// number of columns spanned by the range. The header cells are written with
	// the resolved names so the sheet and the table agree.
	Columns []string
	// Style selects the built-in table style and banding. The zero value emits
	// no tableStyleInfo; use e.g. TableStyle{Name: "TableStyleMedium2",
	// ShowRowStripes: true} for Excel's default look.
	Style TableStyle
	// TotalsRow adds a totals row. When true, the last row of the range is the
	// totals row (so the range must include it) and ColumnTotals configures the
	// per-column cells.
	TotalsRow bool
	// ColumnTotals maps a column name to its totals-row function and label.
	// Consulted only when TotalsRow is true.
	ColumnTotals map[string]TotalsColumn
}

TableOptions configures a table created via Sheet.AddTable.

type TableStyle 

type TableStyle struct {
	// Name is a built-in table style name such as "TableStyleMedium2". When
	// empty (and every banding flag is false) no style is applied.
	Name string
	// ShowRowStripes bands alternate rows.
	ShowRowStripes bool
	// ShowColumnStripes bands alternate columns.
	ShowColumnStripes bool
	// ShowFirstColumn emphasizes the first column.
	ShowFirstColumn bool
	// ShowLastColumn emphasizes the last column.
	ShowLastColumn bool
}

TableStyle selects a built-in table style and its banding options.

type TextRun 

type TextRun struct {
	Text string
	Font *FontStyle
}

TextRun is one run of formatted text within a rich-text cell. A nil Font leaves the run in the cell's default font.

type Timeline 

type Timeline struct {
	// contains filtered or unexported fields
}

Timeline is a read view of a pivot timeline: an on-sheet control that filters one or more pivot tables by a range on a date pivot field. A Timeline returned by Sheet.Timelines or Workbook.Timelines reflects the timeline as stored in the opened workbook; its accessors are read-only.

Creating timelines is not yet supported (see the package documentation); an opened workbook's timelines, timeline caches and their worksheet/workbook extension references round-trip byte-for-byte.

func (*Timeline) Cache 

func (t *Timeline) Cache() string

Cache returns the name of the timeline cache the timeline draws from.

func (*Timeline) Caption 

func (t *Timeline) Caption() string

Caption returns the timeline's display caption, or "" when unset.

func (*Timeline) Level 

func (t *Timeline) Level() int

Level returns the time grouping level: 0 years, 1 quarters, 2 months, 3 days.

func (*Timeline) Name 

func (t *Timeline) Name() string

Name returns the timeline's unique name.

func (*Timeline) PivotTables 

func (t *Timeline) PivotTables() []string

PivotTables returns the names of the pivot tables the timeline controls, or nil when the timeline cache could not be resolved.

func (*Timeline) SheetName 

func (t *Timeline) SheetName() string

SheetName returns the name of the sheet the timeline is anchored on.

func (*Timeline) SourceField 

func (t *Timeline) SourceField() string

SourceField returns the date pivot field the timeline filters (e.g. "Date"), or "" when the timeline cache could not be resolved.

type TotalsColumn 

type TotalsColumn struct {
	// Function is a built-in totals aggregation (e.g. "sum", "count",
	// "average", "min", "max"), or "" for no function.
	Function string
	// Label is a literal label for the totals cell (e.g. "Total"), typically
	// set on the first column instead of a function.
	Label string
}

TotalsColumn configures a single column's totals-row cell. Consulted only when TableOptions.TotalsRow is true.

type UnderlineStyle 

type UnderlineStyle string

UnderlineStyle names a font underline style (CT_UnderlineProperty val, ST_UnderlineValues). The string values are the SpreadsheetML tokens. 

const (
	UnderlineNone             UnderlineStyle = "none"
	UnderlineSingle           UnderlineStyle = "single"
	UnderlineDouble           UnderlineStyle = "double"
	UnderlineSingleAccounting UnderlineStyle = "singleAccounting"
	UnderlineDoubleAccounting UnderlineStyle = "doubleAccounting"
)

type Workbook 

type Workbook struct {
	// Properties contains the document properties.
	Properties opc.CoreProperties
	// contains filtered or unexported fields
}

Workbook represents an Excel workbook.

func Create 

func Create() *Workbook

Create creates a new, empty workbook.

Example

ExampleCreate mirrors the README quick start for Excel: a sheet with cell values and a SUM formula, serialized with SaveBytes and reopened from memory to read a value and the sheet count back — no files touched. 

package main

import (
	"bytes"
	"fmt"

	"github.com/mgilbir/spine/xlsx"
)

func main() {
	wb := xlsx.Create()

	sheet, err := wb.AddSheet("Sales")
	if err != nil {
		panic(err)
	}
	cells := []struct {
		ref string
		val interface{}
	}{
		{"A1", "Product"}, {"B1", "Revenue"},
		{"A2", "Widgets"}, {"B2", 1500.0},
		{"A3", "Gadgets"}, {"B3", 3200.0},
	}
	for _, c := range cells {
		if err := sheet.SetCellValue(c.ref, c.val); err != nil {
			panic(err)
		}
	}

	cell, _ := sheet.Cell("B4")
	cell.SetFormula("SUM(B2:B3)")

	data, err := wb.SaveBytes()
	if err != nil {
		panic(err)
	}

	reopened, err := xlsx.OpenReader(bytes.NewReader(data), int64(len(data)))
	if err != nil {
		panic(err)
	}
	defer func() { _ = reopened.Close() }()

	s2, _ := reopened.SheetByName("Sales")
	a1, _ := s2.Cell("A1")
	b4, _ := s2.Cell("B4")
	fmt.Printf("sheets=%d A1=%v B4.formula=%s\n", reopened.SheetCount(), a1.Value(), b4.Formula())
}

Output:
sheets=1 A1=Product B4.formula=SUM(B2:B3)

func Open 

func Open(path string, opts ...opc.ReaderOption) (*Workbook, error)

Open opens an Excel workbook from a file path. The whole package is read into memory, so the returned Workbook retains no OS file handle and Close is effectively a no-op — the same resource model as docx.Open and pptx.Open. (Before C570 this alone among the three kept the source file open until Close, an xlsx-only descriptor leak for callers trained by the other two; nothing needed the handle, because every part is read up front regardless.) Sheet contents are held as preserved bytes and parsed lazily on first access.

Options configure the underlying package reader: opc.WithPassword opens a password-encrypted workbook, and the opc.WithMax* options adjust the bounds that guard against decompression bombs.

It returns ErrNotXLSX when the package is not SpreadsheetML, opc.ErrStrictOOXML for an ISO-Strict package, and opc.ErrEncrypted when the input is password-encrypted and no opc.WithPassword was given. Each is matchable with errors.Is.

func OpenReader 

func OpenReader(r io.ReaderAt, size int64, opts ...opc.ReaderOption) (*Workbook, error)

OpenReader opens an Excel workbook from an in-memory reader. Every part is read into memory during the call (worksheet models are then parsed lazily on first access), so r need not remain valid after Open returns, and no OS file handle is retained. It takes the same options and returns the same sentinels as Open (ErrNotXLSX, opc.ErrStrictOOXML, opc.ErrEncrypted), matchable with errors.Is. Open is implemented on top of it.

func (*Workbook) ActiveSheet 

func (w *Workbook) ActiveSheet() *Sheet

ActiveSheet returns the currently active sheet.

func (*Workbook) ActiveXControls 

func (w *Workbook) ActiveXControls() []ActiveXControl

ActiveXControls returns the workbook's ActiveX controls, ordered by part name for determinism. Controls are located by their ax:ocx content type across all preserved parts; each control's persistence binary is resolved through the control part's relationships (falling back to the sibling .bin part). Extraction is read-only and leaves every part byte-for-byte unchanged.

func (*Workbook) AddDefinedName 

func (w *Workbook) AddDefinedName(name, ref string) error

AddDefinedName adds a workbook-scoped defined name. The name must be legal for Excel (see ValidateDefinedName) and must not already exist at workbook scope; otherwise an error is returned and the workbook is left unchanged (C426).

func (*Workbook) AddDefinedNameFull 

func (w *Workbook) AddDefinedNameFull(dn DefinedName) error

AddDefinedNameFull adds a defined name carrying the full set of attributes (scope plus the hidden flag, comment and description). SheetIndex -1 makes the name workbook-scoped; a valid sheet index makes it sheet-scoped. It is the richer counterpart to AddDefinedName / AddDefinedNameScoped.

The name is validated (see ValidateDefinedName) and must not duplicate an existing name in the same scope.

func (*Workbook) AddDefinedNameScoped 

func (w *Workbook) AddDefinedNameScoped(name, ref string, sheetIndex int) error

AddDefinedNameScoped adds a sheet-scoped defined name. The name must be legal for Excel (see ValidateDefinedName) and must not already exist on that sheet.

func (*Workbook) AddSheet 

func (w *Workbook) AddSheet(name string) (*Sheet, error)

AddSheet appends a new worksheet named name and returns it.

The name must be a legal Excel sheet name (see ValidateSheetName) and must not already be taken, compared case-insensitively as Excel compares them; otherwise the sheet is not added and the error says why — ErrDuplicateSheetName for a collision, a descriptive error for an illegal name.

It used to coerce instead: AddSheet("Bad[Name]…") silently returned a sheet actually called "BadName…" truncated to 31 runes, and a second AddSheet("Data") silently produced "Data (2)", after which SheetByName(<the name you passed>) failed with ErrSheetNotFound. The package already exported ValidateSheetName and Sheet.SetName already rejected exactly these names, so the library knew the name was illegal and rewrote the caller's identity anyway — in the API where names are passed most often, and in a way no docx or pptx creation API does (C440). When a suffixed fallback IS what you want, ask for it explicitly: 

sheet, err := wb.AddSheet(wb.UniqueSheetName("Data"))

func (*Workbook) AppendSheetsFrom added in v0.2.0 

func (w *Workbook) AppendSheetsFrom(other *Workbook) ([]*Sheet, error)

AppendSheetsFrom copies every sheet of other into this workbook, in order, after the existing sheets, and returns the new sheets.

It is the whole-file merge xlsx was missing: docx has Document.Append and pptx has Presentation.AppendSlidesFrom, but "merge workbook B into A" here meant looping CopySheetFrom over other.Sheets() by name and reconciling the rest by hand (C569). Each sheet is copied under a unique name — a " (2)"-style suffix is appended when the source name is already taken — so the returned slice, not the source names, is how to find the copies.

The per-sheet contract is CopySheetFrom's, and so are its limits: cell values, styles, formulas, merged ranges, column widths, row heights and images are carried; charts, cross-sheet formula references, defined names and pivot tables are not. A sheet that fails to copy aborts the whole append, leaving the sheets copied before it in place — this is not transactional.

Chartsheets, dialogsheets and macrosheets in other are skipped: they round-trip verbatim and have no worksheet model to copy from (CopySheetFrom would report ErrSheetNotFound for them).

func (*Workbook) Charts 

func (w *Workbook) Charts() []*chart.Chart

Charts returns every chart across all of the workbook's sheets — worksheets and chartsheets alike — in sheet order. The slice is nil when the workbook has no charts.

Charts held by a sheet copied in with Workbook.Merge are not included: merge does not carry a source sheet's drawing across, so no chart part comes with it.

func (*Workbook) Close 

func (w *Workbook) Close() error

Close releases the workbook's underlying resources. Since C570 no open path retains an OS file handle — Open reads the file into memory exactly as docx.Open and pptx.Open do — so this is effectively a no-op, kept because it is part of the API and because it drops the workbook's reference to the source package reader. It remains safe (and unnecessary) to call.

Calling Save (or any Save* method) after Close is valid: the preserved parts and parsed models stay in memory and a durable internal flag — not the reader — keeps the round-trip save path, so Close does not turn a saved workbook into a from-scratch regeneration.

func (*Workbook) Connections 

func (w *Workbook) Connections() []Connection

Connections returns the external-data connections declared in xl/connections.xml, ordered by id. It is read-only: the connections part is preserved byte-for-byte on save. Returns nil when the workbook declares no connections.

Deferred: authoring or refreshing a connection (writing a live query, driving its provider, handling credentials) is out of scope. Connections are surfaced for inspection and carried through unchanged.

func (*Workbook) CopySheetFrom 

func (w *Workbook) CopySheetFrom(other *Workbook, sheetName string) (*Sheet, error)

CopySheetFrom copies the sheet named sheetName from other into this workbook under a unique name (a suffix is appended if the name is already taken), returning the new sheet. Cell values, styles, formulas, merged ranges, and column widths / row heights are carried over. Shared-string cell values are resolved and written as inline strings so the two workbooks' string tables need not be merged, and cell style indices are remapped into this workbook's stylesheet (deduplicated).

Images embedded in the source sheet — both those added this session and those loaded from an opened source's drawing part — are copied into a fresh drawing on the new sheet, with their media re-embedded under non-colliding part names. Charts embedded in the source sheet are not copied (deferred), and cross-sheet references in copied formulas are not rewritten.

func (*Workbook) CustomProperties 

func (w *Workbook) CustomProperties() map[string]any

CustomProperties returns the workbook's custom (user-defined) properties as a name→value map, or nil when the workbook has none. Values are one of string, int64, float64, bool, or time.Time. The returned map is a copy; mutate the properties through SetCustomProperty and RemoveCustomProperty.

func (*Workbook) DataModel 

func (w *Workbook) DataModel() DataModelInfo

DataModel reports the presence and locations of the workbook's Power Pivot data model and Power Query content. The underlying parts round-trip unchanged; this is inspection-only.

Deferred: authoring or refreshing the data model or Power Query definitions (editing the DataMashup blob, model tables, or relationships) is out of scope.

func (*Workbook) Date1904 added in v0.2.0 

func (w *Workbook) Date1904() bool

Date1904 reports whether the workbook uses the 1904 serial-date system (workbookPr/@date1904, the historical Mac Excel default): serial 0 is 1904-01-01 and there is no fictitious 1900-02-29 leap day. The default is the 1900 system. Cell.Time and Cell.SetTime follow this setting (C367).

func (*Workbook) DefinedNames 

func (w *Workbook) DefinedNames() []DefinedName

DefinedNames returns all defined names in the workbook.

func (*Workbook) DeleteSheet deprecated 

func (w *Workbook) DeleteSheet(index int) error

DeleteSheet removes the sheet at the specified index, together with its preserved part, its content-type override, and its own .rels part (C75). Workbook state that indexes sheets by position is adjusted: the active tab is shifted/clamped, sheet-scoped defined names are re-pointed (names scoped to the deleted sheet are dropped), every relationship resolving to a removed part is dropped (C366), and references naming the deleted sheet in defined-name values and in surviving sheets' formulas are rewritten to #REF!, matching what Excel does (C424).

Not rewritten: references held in chart definition parts and in pivot-cache definitions, which round-trip as preserved bytes; and the pivot caches of the deleted sheet's pivot tables, which are shared workbook-level parts left to a dedicated pass.

Every *Sheet handle for a sheet at or after index is invalidated: the handles left in the workbook are re-indexed, but a handle the caller already holds for the removed sheet is detached and must not be used again.

Deprecated: use RemoveSheet, the name this library uses for every other removal (C565). The two are the same call; DeleteSheet is kept working.

func (*Workbook) Flavor 

func (w *Workbook) Flavor() string

Flavor returns the main part's content type: one of the SpreadsheetML flavors (opc.ContentTypeWorkbook, opc.ContentTypeWorkbookTemplateMain, or a macro-enabled variant). An opened file reports the flavor it was opened with — a macro-enabled workbook (.xlsm) stays macro-enabled across a save — and a created workbook reports opc.ContentTypeWorkbook. There is no conversion API: retyping a file to another flavor is out of scope.

func (*Workbook) ForceFullCalc 

func (w *Workbook) ForceFullCalc() bool

ForceFullCalc reports whether the workbook is marked to recalculate every formula the next time it is opened (calcPr fullCalcOnLoad).

func (*Workbook) HasMacros 

func (w *Workbook) HasMacros() bool

HasMacros reports whether the workbook carries a VBA project (vbaProject.bin), accounting for a project injected or removed in this session.

func (*Workbook) OLEObjects 

func (w *Workbook) OLEObjects() []OLEObject

OLEObjects returns the workbook's embedded OLE objects. Objects are located through the package's oleObject relationships; any remaining /xl/embeddings/*.bin parts typed as OLE objects are included as a fallback. The result is ordered by part name for determinism. Extraction is read-only and leaves every part byte-for-byte unchanged on a subsequent save.

func (*Workbook) PivotTables 

func (w *Workbook) PivotTables() []*PivotTable

PivotTables returns every pivot table across all of the workbook's sheets, in sheet order. The slice is nil when the workbook has no pivot tables.

func (*Workbook) Protect 

func (w *Workbook) Protect(opts WorkbookProtectionOptions)

Protect turns on workbook-structure protection with the given options, replacing any existing <workbookProtection> element. A save regenerates workbook.xml with the new protection.

Excel workbook protection is a UI guard, not encryption. Even with a password it is trivially removed; do not use it to protect confidential data.

func (*Workbook) Protection 

func (w *Workbook) Protection() *WorkbookProtection

Protection returns the workbook's structure-protection state, or nil when the workbook has no <workbookProtection> element. It is the read counterpart of Protect/Unprotect.

func (*Workbook) RemoveCustomProperty 

func (w *Workbook) RemoveCustomProperty(name string) bool

RemoveCustomProperty removes the named custom property, reporting whether it existed.

func (*Workbook) RemoveDefinedName 

func (w *Workbook) RemoveDefinedName(name string) bool

RemoveDefinedName removes every workbook-scoped defined name with the given name and reports whether any were removed.

func (*Workbook) RemoveDefinedNameScoped 

func (w *Workbook) RemoveDefinedNameScoped(name string, sheetIndex int) bool

RemoveDefinedNameScoped removes the sheet-scoped defined name with the given name on the given sheet and reports whether it was removed.

func (*Workbook) RemoveSheet added in v0.2.0 

func (w *Workbook) RemoveSheet(index int) error

RemoveSheet removes the sheet at the specified index. It is the primary spelling; see DeleteSheet for the full description of what removal drags along with it.

The name matches every other removal in the library — pptx's RemoveSlide, and RemoveCustomProperty / RemoveVBAProject / RemoveDefinedName in this very package — where DeleteSheet was the lone Delete* (C565).

func (*Workbook) RemoveVBAProject 

func (w *Workbook) RemoveVBAProject()

RemoveVBAProject removes the workbook's VBA project part, dropping its content-type override and workbook relationship and flipping the main part back to the regular (non-macro) flavor. It is a no-op on a workbook that carries no macros.

func (*Workbook) ReplaceText 

func (w *Workbook) ReplaceText(replacements map[string]string)

ReplaceText performs text replacement across every sheet in the workbook. Keys in the replacements map are matched exactly as provided — to replace "{{name}}" with "John", pass map[string]string{"{{name}}": "John"}.

Replacement applies to string cells (both shared-string and inline-string cells) and to the individual runs of rich (multi-run) text cells, where a run spanning a match inherits the first affected run's font. Formula cells are NOT touched: their string type is a cached formula result, not literal text. Numeric, boolean, date, and error cells are left unchanged.

This mirrors pptx.Presentation.ReplaceText and docx.Document.ReplaceText. Empty keys are ignored, and a workbook with no matching text round-trips byte-for-byte.

func (*Workbook) Save 

func (w *Workbook) Save(path string) error

Save writes the workbook to a file. Like SaveTo, it enforces the pre-save validation gate and the round-trip contract documented there.

func (*Workbook) SaveBytes 

func (w *Workbook) SaveBytes() ([]byte, error)

SaveBytes writes the workbook to an in-memory buffer through SaveTo (same validation gate and round-trip contract).

func (*Workbook) SaveEncrypted added in v0.2.0 

func (w *Workbook) SaveEncrypted(path, password string) error

SaveEncrypted saves the workbook to a file, encrypted with the supplied password using Office's agile encryption (AES-256, SHA-512). The password must not be empty. The resulting file opens in Excel with the password, and here with Open and opc.WithPassword.

func (*Workbook) SaveEncryptedTo added in v0.2.0 

func (w *Workbook) SaveEncryptedTo(dst io.Writer, password string) error

SaveEncryptedTo saves the workbook to an arbitrary writer, encrypted with the supplied password. It first serializes the workbook to plain package bytes (running the same validation as SaveTo), then wraps them in an encrypted CFB container.

func (*Workbook) SaveTo 

func (w *Workbook) SaveTo(dst io.Writer) error

SaveTo saves the workbook to an arbitrary writer.

A workbook must contain at least one sheet (Excel refuses zero-sheet files), so saving an empty workbook returns ErrNoSheets (C130). It then runs Validate and refuses to write — returning the Report as an error — when any error-severity finding is present, so a structurally corrupt package is never produced. SaveToUnvalidated bypasses the validation gate (but still enforces the non-empty-sheet invariant).

Round-trip contract: for a workbook opened with Open/OpenReader, parts the session never touched are written back byte-for-byte — including sheets that were never accessed, which are never even parsed — while touched parts are regenerated from the model. A workbook built with Create is generated entirely from the model. This holds after Close, too (see Close).

Modification time: when the session changed the workbook's content, the save records its own time in Properties.Modified (docProps/core.xml, dcterms:modified). When it did not — including a session that only read the workbook, and a repeat save of one already written — the timestamp is left exactly as it was, so an unchanged save still reproduces the package byte-for-byte. Assigning Properties.Modified yourself takes precedence over the automatic value. See modified.go.

func (*Workbook) SaveToUnvalidated 

func (w *Workbook) SaveToUnvalidated(dst io.Writer) error

SaveToUnvalidated saves the workbook without running the pre-save validation pass (it still enforces the non-empty-sheet invariant). Prefer SaveTo; use this only when a finding is known to be advisory for the caller's use case.

func (*Workbook) SetActiveSheet 

func (w *Workbook) SetActiveSheet(index int) error

SetActiveSheet sets the active sheet by index.

func (*Workbook) SetCustomProperty 

func (w *Workbook) SetCustomProperty(name string, value any) error

SetCustomProperty adds or replaces a custom document property. The value must be a string, int/int32/int64, float32/float64, bool, or time.Time (integers are stored as int64 and 32-bit floats as float64). Setting a property on a workbook that has none creates the docProps/custom.xml part on save.

func (*Workbook) SetForceFullCalc 

func (w *Workbook) SetForceFullCalc(force bool)

SetForceFullCalc controls whether Excel recalculates every formula when the workbook is next opened, by setting the workbook calcPr fullCalcOnLoad flag. Enable it after editing formulas so their cached results are refreshed on open. Disabling clears the flag; when the workbook has no other calcPr settings the (now default-only) element is still emitted, which Excel accepts.

func (*Workbook) SetVBAProject 

func (w *Workbook) SetVBAProject(data []byte)

SetVBAProject injects or replaces the workbook's VBA project with the given vbaProject.bin bytes, wiring the content-type override and the workbook relationship and flipping the main part to the macro-enabled flavor (.xlsm / .xltm) when it is not already macro-enabled. The bytes are stored as-is and written verbatim on save.

Security: the bytes are executable VBA carried opaquely. Injecting a project extracted from another document transplants that document's macros and their trust; only inject bytes from a source you trust.

func (*Workbook) Sheet 

func (w *Workbook) Sheet(index int) (*Sheet, error)

Sheet returns the sheet at the specified index (0-based).

func (*Workbook) SheetByName 

func (w *Workbook) SheetByName(name string) (*Sheet, error)

SheetByName returns the sheet with the specified name.

func (*Workbook) SheetCount 

func (w *Workbook) SheetCount() int

SheetCount returns the number of sheets.

func (*Workbook) Sheets 

func (w *Workbook) Sheets() []*Sheet

Sheets returns all sheets in the workbook. The returned slice is a copy of the workbook's backing slice, so sorting, truncating or otherwise mutating it does not desynchronize the workbook's internal sheet order (and the cached per-sheet index). The Sheet pointers themselves are shared.

func (*Workbook) Slicers 

func (w *Workbook) Slicers() []*Slicer

Slicers returns every slicer across all of the workbook's sheets, in sheet order. The slice is nil when the workbook has no slicers.

func (*Workbook) Styles 

func (w *Workbook) Styles() *StyleManager

Styles returns the StyleManager for this workbook. If no stylesheet exists yet (e.g. for a newly created workbook), a default one is materialized in memory. Merely reading styles does not mark them dirty (which would force styles.xml to be regenerated and break byte-identical round-trip); the returned manager marks styles dirty only when a mutating method is called.

func (*Workbook) Tables 

func (w *Workbook) Tables() []*Table

Tables returns every table across all of the workbook's sheets, in sheet order. The slice is nil when the workbook has no tables.

func (*Workbook) Text 

func (w *Workbook) Text() string

Text returns every cell value and cell comment in the workbook as a single plain string, with no markup, suitable for search, indexing, or LLM ingestion. Each sheet's text (see Sheet.Text) is concatenated in workbook order, separated by a blank line.

func (*Workbook) Theme 

func (w *Workbook) Theme() *dml.ThemeEditor

Theme returns a read/write handle to the workbook's theme part (xl/theme/theme1.xml), the shared DrawingML a:theme model exposed by dml.ThemeEditor. Color-scheme and font-scheme edits made through the handle are written back to the theme part on save; an untouched theme round-trips byte-for-byte from its preserved source bytes.

It returns nil when the workbook has no theme part — matching pptx's behavior for programmatically created files, whose default theme part is not modeled.

func (*Workbook) Timelines 

func (w *Workbook) Timelines() []*Timeline

Timelines returns every timeline across all of the workbook's sheets, in sheet order. The slice is nil when the workbook has no timelines.

func (*Workbook) UniqueSheetName added in v0.2.0 

func (w *Workbook) UniqueSheetName(name string) string

UniqueSheetName coerces name into a legal sheet name that is free in this workbook, mirroring how Excel repairs an invalid name: forbidden characters are stripped, the result is trimmed to 31 runes and made non-empty, and a " (2)"-style suffix is appended while the name collides (case-insensitively) with an existing sheet.

It is the explicit form of what AddSheet used to do silently (C440). Pair it with AddSheet when a derived name is genuinely what you want: 

sheet, err := wb.AddSheet(wb.UniqueSheetName(userSuppliedName))

The result is only guaranteed free until the next sheet is added.

func (*Workbook) Unprotect 

func (w *Workbook) Unprotect()

Unprotect removes workbook-structure protection, if any.

func (*Workbook) VBAProject 

func (w *Workbook) VBAProject() []byte

VBAProject returns the raw bytes of the workbook's VBA project part (vbaProject.bin), or nil if the workbook carries no macros. The bytes are the opaque MS-OVBA/CFB blob exactly as stored; spine does not parse them.

func (*Workbook) Validate 

func (w *Workbook) Validate() validate.Report

Validate walks the in-memory workbook model and reports structural problems without saving or re-parsing. Save and SaveTo run it first and refuse to write when any error-severity finding is present; use SaveToUnvalidated to bypass the gate.

The checks are sound (no false positives on Excel-accepted packages).

func (*Workbook) WriteToBuffer deprecated 

func (w *Workbook) WriteToBuffer() (*bytes.Buffer, error)

WriteToBuffer saves the workbook to an in-memory buffer.

Deprecated: use SaveBytes, which returns the same bytes without the buffer wrapper, or SaveTo for an arbitrary io.Writer. This is SaveBytes wrapped in a *bytes.Buffer and has no counterpart in docx or pptx (C567).

type WorkbookProtection 

type WorkbookProtection struct {
	// contains filtered or unexported fields
}

WorkbookProtection is a read-only view of a workbook's <workbookProtection> element. It reports whether the workbook's structure (adding, deleting, hiding or reordering sheets) and window layout are locked.

Like sheet protection, this is a UI guard, not encryption: the workbook is not protected cryptographically and any tool can clear it. HasPassword only reports that a (weak legacy or hashed) password guard is present; the password itself is never exposed or recovered.

func (*WorkbookProtection) HasPassword 

func (p *WorkbookProtection) HasPassword() bool

HasPassword reports whether a password guard is present (either the legacy 16-bit hash or a modern hashValue/saltValue). The password is never exposed.

func (*WorkbookProtection) LockStructure 

func (p *WorkbookProtection) LockStructure() bool

LockStructure reports whether the workbook structure is locked (sheets cannot be added, deleted, hidden, shown or reordered).

func (*WorkbookProtection) LockWindows 

func (p *WorkbookProtection) LockWindows() bool

LockWindows reports whether the workbook window layout is locked.

type WorkbookProtectionOptions 

type WorkbookProtectionOptions struct {
	// Password, when non-empty, is guarded with Excel's legacy 16-bit password
	// hash. This is obfuscation, not security — it is trivially removed and must
	// not be relied on to protect confidential data.
	Password string

	// LockStructure locks the workbook structure. When neither LockStructure nor
	// LockWindows is set, Protect locks the structure so the element guards
	// something rather than being an inert <workbookProtection/>.
	LockStructure bool

	// LockWindows locks the workbook window layout.
	LockWindows bool
}

WorkbookProtectionOptions configures Workbook.Protect. The zero value locks the workbook structure (the common case: preventing sheets from being added, deleted, hidden or reordered). Setting LockWindows alone locks only the window layout; set both fields to lock both.

Source Files

View all Source files

Directories

Path Synopsis
internal
oxml
Package oxml contains the SpreadsheetML schema types used to parse and serialize the XML parts of XLSX packages.
 Package oxml contains the SpreadsheetML schema types used to parse and serialize the XML parts of XLSX packages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.