API reference
Hypaxel API overview: writers, streaming readers, styles, worksheets, records, tables and web helpers mapped across seven languages, plus the browser build.
v0.3.0 unreleasedLast updated View as Markdown
All Hypaxel implementations share the same model: a writer owns styles and produces worksheets one after another; a worksheet takes rows top to bottom; finishing the writer completes the file. Readers work the same way in reverse: open a workbook, open a worksheet and take its rows one at a time. This page maps those concepts to the actual names in each language and collects the method and option tables. A dash (—) means the language guide does not document a dedicated name for that concept.
Concept mapping#
.NET, Rust, Python and Node.js#
| Concept | .NET | Rust | Python | Node.js |
|---|---|---|---|---|
| Create writer | XlsxWriter.Create(path) | XlsxWriter::new(out) | hypaxel.Writer(dest) | new Writer(options) |
| Add style | writer.AddStyle(CellStyle) | writer.add_style(&Style) | wb.add_style(...) | workbook.addStyle({...}) |
| Add worksheet | AddWorksheet(name, WorksheetOptions) | add_worksheet(name), add_worksheet_with(name, &SheetOptions) | add_worksheet(name, ...) | addWorksheet(name, {...}) |
| Write row | AddRowAsync(...); Write + EndRowAsync() | add_row(...); write + end_row() | write_row, write_rows; write + end_row() | writeRow, writeRows; write + endRow() |
| Write records / objects | WriteWorksheetAsync, WriteObjectsAsync | write_sheet_records, write_records | hypaxel.write_records, write_dataframe, Worksheet.write_dicts | writeRecords(records, keys); helpers writeFile, toBuffer |
| Merge cells | — | — | merge_cells(r1, c1, r2, c2) | mergeCells(r1, c1, r2, c2) |
| Auto filter | — | — | autofilter(r1, c1, r2, c2) | autofilter(r1, c1, r2, c2) |
| Add table | AddTable(ExcelTable) | add_table(&Table) | add_table(r1, c1, r2, c2, ...) | addTable(r1, c1, r2, c2, {...}) |
| Begin row / outline | BeginRow(RowOptions) | begin_row, begin_row_with(&RowOptions), begin_row_at | begin_row(...); write_row(..., outline_level=) | beginRow({ outlineLevel, ... }) |
| Finish | CompleteAsync() | finish(), finish_async() | finish() or the with block | finish(), drain() |
| Streaming web helper | Results.Extensions.Excel(...), this.Excel(...) | hypaxel_axum::Xlsx::from_records, from_stream, from_fn, from_async_fn | XlsxResponse, stream_rows, stream_records, stream_dataframe, astream_rows, astream_records | stream(), webStream() |
Go, Java and PHP#
| Concept | Go | Java | PHP |
|---|---|---|---|
| Create writer | hypaxel.NewWriter(dst, opts...) | XlsxWriter.create(out | path, options?) | Writer::toFile, toStream, toCallback, toOutput, inMemory |
| Add style | w.AddStyle(Style) | writer.addStyle(Style) | $writer->addStyle(Style) |
| Add worksheet | AddSheet(name), AddSheetOptions(name, SheetOptions) | addWorksheet(name, SheetOptions?) | addWorksheet($name, ?SheetOptions) |
| Write row | WriteRow(values...); typed WriteX + EndRow() | addRow(values...); write + endRow() | writeRow, writeRows; write + endRow() |
| Write records / objects | WriteSheet, WriteSheetSeq, WriteSheetSeq2, WriteSheetChan, WriteStruct | writeWorksheet(name, type, items), writeObjects | Writer::writeWorksheet, Worksheet::writeRecords; helpers Xlsx::writeFile etc. |
| Merge cells | MergeCells(r1, c1, r2, c2) | mergeCells(r1, c1, r2, c2) | mergeCells($r1, $c1, $r2, $c2) |
| Auto filter | AutoFilter(r1, c1, r2, c2) | autoFilter(r1, c1, r2, c2) | autoFilter($r1, $c1, $r2, $c2) |
| Add table | AddTable(Table{...}) | addTable(ExcelTable) | addTable(Table) |
| Begin row / outline | BeginRow(RowOptions{...}) | beginRow(RowOptions), beginRowAt(row, ...) | beginRow(outlineLevel: ...), beginRowAt($row, ...) |
| Finish | Close() | close(), finish(), abort() | finish() |
| Streaming web helper | hypaxelhttp.Handler, hypaxelhttp.Serve | — (write to any OutputStream; XlsxWriter.CONTENT_TYPE) | Xlsx::download, Xlsx::output, Xlsx::stream, Xlsx::headers |
Ranges are 1-based and inclusive in every language that documents them.
Reading#
.NET, Rust, Python, Go and Java read XLSX files as a stream. Node.js and PHP do not read yet. Rows and columns are 1-based, sheet indexes 0-based.
| Concept | .NET | Rust | Python | Go | Java |
|---|---|---|---|---|---|
| Open a workbook | XlsxReader.Open(path), new XlsxReader(stream, options) | XlsxReader::open(path), new(source), with_options(source, &options) | open_workbook(source) (path, bytes or binary file object) | OpenReader(path, opts...), NewReader(src, size, opts...) | XlsxReader.open(Path | SeekableByteChannel | byte[] | InputStream, options?) |
| List sheets | SheetNames, Sheets | sheet_names(), sheets() | sheet_names, sheets | SheetNames(), Sheets() | sheetNames(), sheets() |
| Open a worksheet | OpenWorksheet(name | index) | worksheet(name), worksheet_at(index), into_worksheet(name) | wb.rows(sheet); iter_rows(source, sheet) | Rows(name), RowsAt(index) | worksheet(name | index) |
| Next row | Read(), then Row; or foreach | next_row() | iterate rows(...) / iter_rows(...) | Next(), then Row(); or All() | nextRow(), iterator, stream() |
| Row number | row.Number | row.number() | — (enumerate(rows, 1)) | row.Index() | row.number() |
| Cell by column | row.TryGetString(col, out ...), TryGetDouble, TryGetDateTime, GetValue | row.get(col) | row[col - 1] | row.Get(col) | row.getString(col), getNumber, getValue |
| Value kinds | ExcelValue.Kind (ExcelValueKind) | Value enum | str, int, float, bool, datetime, time, timedelta, error strings, None | Value.Kind() | row.type(col) (CellType) |
| Dates | ExcelDateTime, TryGetDateTime | Value::DateTime(ExcelDateTime) | datetime, time, timedelta | Time(), Duration(), DateKind() | getDateTime(col) (ExcelDateTime), getLocalDateTime(col) |
| Options and limits | XlsxReaderOptions (MaxSharedStringsBytes, BackgroundDecompression) | ReadOptions::new().max_shared_strings_bytes(n) | max_shared_strings_bytes= | WithMaxSharedStringsBytes(n), WithConcurrentInflate(on) | ReadOptions.builder().maxSharedStringsBytes(n) |
| Errors | XlsxReadException (Kind, Part) | Error::InvalidFile, Error::Malformed, Error::SheetNotFound, Error::LimitExceeded | XlsxError, FileNotFoundError | *ReadError (Part); ErrInvalidFile, ErrMalformed, … | XlsxException (kind(), part()) |
Formulas yield their cached result. Formula text, styles beyond date detection, merged ranges, comments and hyperlinks are not read.
.NET#
| Area | Names |
|---|---|
| Writer | XlsxWriter.Create(...), AddStyle, AddWorksheet, WriteWorksheetAsync, CompleteAsync |
| Worksheet | AddRowAsync, Write, EndRowAsync, SkipCells, SkipRows, BeginRow(n), BeginRow(RowOptions), WriteObjectsAsync, AddTable, RowNumber |
| Values | CellValue.From(value, style), CellValue.Formula(formula, style), CellValue.Empty |
| Styles | CellStyle with Font, Fill, NumberFormat; ExcelColor, NumberFormats |
| Worksheet options | WorksheetOptions: FrozenRows, SetColumnWidths, AutoFitColumns(), AutoFit (AutoFitOptions { SampleRows, MaxWidth }), RowOutlineLevels, OutlineSummaryAbove |
| Rows | RowOptions: OutlineLevel, Hidden, Collapsed, Height, Style |
| Tables | ExcelTable(firstRow, firstColumn, lastRow, lastColumn) with Name, Columns, Style (TableStyle.Light, Medium, Dark, None) |
| Mapping | [ExcelColumn(header, Order, Width, NumberFormat)], [ExcelIgnore], ObjectWriteOptions { WriteHeader } |
| ASP.NET Core | Results.Extensions.Excel(...), this.Excel(...), ExcelResult |
XlsxWriterOptions
| Option | Default | Meaning |
|---|---|---|
CompressionLevel | CompressionLevel.Fastest | Optimal for smaller files |
StringStorage | StringStorage.Inline | SharedStrings for repetitive text |
FlushThreshold | 64 * 1024 | Bytes buffered before an async write |
WriteCellReferences | false | true writes r="A1" on every cell |
Use1904DateSystem | false | Use the 1904 date system |
OwnsStream | false | Whether the writer owns the destination stream |
Reading (guide)
| Area | Names |
|---|---|
| Reader | XlsxReader.Open(path, options?), new XlsxReader(stream, options?), SheetNames, Sheets (SheetInfo: Name, Visibility, Kind), OpenWorksheet(name), OpenWorksheet(index) |
| Worksheet | WorksheetReader: Read(), Row; also IEnumerable<XlsxRow> |
| Row | XlsxRow: Number, Count, LastColumn, Cells (XlsxCell: Column, Value), GetValue(col), GetKind(col), TryGetString, TryGetText (as ReadOnlySpan<char>), TryGetDouble, TryGetBoolean, TryGetDateTime, GetValues(), GetValues(Span<ExcelValue>) |
| Values | ExcelValue with Kind (Empty, String, Number, Boolean, DateTime, Error), TryGetString, TryGetDouble, TryGetBoolean, TryGetDateTime, TryGetExcelDateTime, TryGetError |
| Dates | ExcelDateTime: Serial, Kind (Date, DateTime, Time, Duration), Is1904, TryGetDateTime, TryGetDateOnly, TryGetTimeOnly, TryGetTimeSpan |
| Errors | XlsxReadException with Kind (InvalidFile, Malformed, LimitExceeded, Unsupported) and Part |
XlsxReaderOptions
| Option | Default | Meaning |
|---|---|---|
MaxSharedStringsBytes | 1 GiB | Caps the shared string table; lower it for untrusted uploads |
BackgroundDecompression | false | Inflate on a second thread; faster for single large files when cores are idle |
OwnsStream | false | Whether the reader disposes the stream |
Rust#
| Area | Names |
|---|---|
| Writer | XlsxWriter::new(out), XlsxWriter::with_options(out, options), add_style, add_worksheet, add_worksheet_with, write_sheet_records, finish |
| Sheet | add_row, write, write_styled, skip_cells, skip_rows, end_row, begin_row, begin_row_with, begin_row_at, write_records, add_table, row() |
Async (tokio feature) | add_row_async, end_row_async, write_records_async, write_records_stream, write_sheet_stream, finish_async |
| Values | Styled(value, style), Formula("..."), Blank |
| Styles | Style::new().bold().font_color(..).fill(..).num_format(..), Color, formats |
| Sheet options | SheetOptions::new().freeze_rows(n).column_widths(&[..]).autofit_columns().autofit(AutoFit).row_outline_levels(n).outline_summary_above() |
| Rows | RowOptions::new().outline_level(n).hidden() |
| Tables | Table::new(r1, c1, r2, c2).name(..).columns([..]).style(TableStyle::Medium(9)) |
| Records | RecordOptions::new().header(bool).column_style(name, style), hypaxel::records::excel_date |
| axum | Xlsx::from_records, from_stream, from_fn, from_async_fn, .filename(..) |
Options
| Option | Default | Meaning |
|---|---|---|
compression_level | 1 | 0–9; 6 gives about 40% smaller files at about 4x the CPU |
string_storage | StringStorage::Inline | Shared for repetitive text |
flush_threshold | 64 * 1024 | Bytes buffered before a write |
cell_references | false | true writes r="A1" on every cell |
date_1904 | false | Use the 1904 date system |
Reading (guide)
| Area | Names |
|---|---|
| Reader | XlsxReader::open(path), open_with(path, &options), new(source), with_options(source, &options), sheet_names(), sheets() (SheetInfo: name(), visibility(), kind()), is_1904(), with_source(source) |
| Worksheet | worksheet(name), worksheet_at(index), into_worksheet(name), into_worksheet_at(index) return Rows; Rows::next_row() |
| Row | number(), len(), last_column(), cells() (Cell: column(), value()), get(column), values() |
| Values | Value::String, Number, Bool, Error, DateTime, Empty; as_str(), as_f64(), as_bool(), as_datetime() |
| Dates | ExcelDateTime: serial(), kind(), is_1904(), to_naive_datetime(), to_naive_date(), to_naive_time(), to_duration() |
| Options | ReadOptions::new().max_shared_strings_bytes(n) (default 1 GiB) |
| Errors | Error::InvalidFile, Error::Malformed { part, message }, Error::SheetNotFound, Error::LimitExceeded |
Python#
| Call | Notes |
|---|---|
Writer(dest=None, *, compression_level=1, shared_strings=False, flush_threshold=65536, date_1904=False) | dest: path, binary file object, or None (in memory) |
Writer.add_style(bold=, italic=, underline=, strikethrough=, font_name=, font_size=, font_color=, fill=, border=, border_color=, border_bottom=, align=, valign=, wrap=, indent=, rotation=, num_format=) | returns a Style. Identical styles are shared |
Writer.add_worksheet(name, *, freeze_rows=, freeze_columns=, column_widths=, hidden=, show_grid_lines=, tab_color=, autofit=, autofit_sample_rows=, autofit_max_width=, row_outline_levels=, outline_summary_above=) | returns a Worksheet. The previous sheet is completed |
Writer.drain() / Writer.finish() | in-memory chunks / complete the workbook |
Worksheet.write_row(values, style=None, *, height=, outline_level=, hidden=, collapsed=), write_rows(rows), write_columns(columns), write_dicts(records, keys) | bulk writers, with the loops running in Rust |
Worksheet.write(value), skip_cells(n), end_row(), begin_row(height=, style=, *, outline_level=, hidden=, collapsed=), skip_rows(n) | cell-by-cell control. A begun row is filled by the next write |
Worksheet.merge_cells(r1, c1, r2, c2), autofilter(r1, c1, r2, c2) | ranges (1-based, inclusive) |
Worksheet.add_table(r1, c1, r2, c2, *, columns=, name=, style="TableStyleMedium2", header_row=, autofilter=, row_stripes=, column_stripes=, first_column=, last_column=) | Excel table; columns must equal the header texts |
Formula("SUM(A1:A9)"), Styled(value, style) | special cell values |
to_xlsx(df, "out.xlsx", column_formats={...}), to_xlsx(orders) | one-liner for DataFrames and records; without a path it returns bytes |
write_records(wb, name, records, column_formats=), write_dataframe(wb, name, df, index=) | whole worksheets from records or a DataFrame |
stream_rows, stream_records, stream_dataframe, astream_rows, astream_records | generators of file chunks for streaming responses |
hypaxel.starlette.XlsxResponse(generator, filename=), hypaxel.CONTENT_TYPE | web integration |
Reading (guide)
| Call | Notes |
|---|---|
open_workbook(source, *, max_shared_strings_bytes=1 GiB) → Reader | source: path, bytes or binary file object; a context manager |
Reader.sheet_names, Reader.sheets, Reader.date_1904, Reader.rows(sheet=0, *, skip_empty=False), Reader.close() | rows iterates lists; several iterators can be open at once |
iter_rows / read_rows | rows as lists, one at a time or as a list |
iter_records / read_records | dicts keyed by the header row (header_row=1) |
read_dataframe(source, sheet=0, *, header=True, library="pandas") | pandas or polars DataFrame |
Errors: FileNotFoundError for missing files, XlsxError for everything else.
Node.js#
Worksheet methods
| Method | Purpose |
|---|---|
writeRow(values, style?) | One row. style applies to cells without their own |
writeRows(rows, style?) | Many rows; returns the count |
writeRecords(records, keys, styles?) | One row per object, taking keys in order |
write(value, style?), endRow() | Cell-by-cell writing |
beginRow({ height, style, outlineLevel, hidden, collapsed }) | Start a row with row properties; the next writeRow fills it |
skipCells(n), skipRows(n) | Leave cells or rows empty |
mergeCells(r1, c1, r2, c2), autofilter(r1, c1, r2, c2) | Ranges, 1-based and inclusive |
addTable(r1, c1, r2, c2, { columns, name, style, ... }) | Excel table; columns must equal the header texts |
Module exports: Writer (addStyle, addWorksheet, drain, finish), Styled, Formula, CONTENT_TYPE, and the export helpers stream, webStream, toBuffer, toBufferSync, writeFile.
Options
| Option | Default | Meaning |
|---|---|---|
compressionLevel | 1 | Deflate level 0-9 |
sharedStrings | false | Shared string table: smaller files for repeated text, more memory |
flushThreshold | 65536 | Compressed bytes buffered before a chunk is produced |
date1904 | false | Use the 1904 date system |
dates | 'local' | A Date is written as wall-clock time in the process time zone ('local') or in UTC ('utc') |
cellReferences | false | Write a reference such as B7 on every cell |
Export helpers also take sheetName, columns, header, autofilter and batchRows. Worksheet options include freezeRows, columnWidths, autofit (or { sampleRows, maxWidth }), rowOutlineLevels and outlineSummaryAbove.
Browsers (guide)
The same package runs in browsers on a WebAssembly build. Bundlers pick it through the browser export condition; import ... from 'hypaxel/wasm' selects it explicitly.
| Export | Purpose |
|---|---|
init(source?) | Loads the WebAssembly module, by default from hypaxel_bg.wasm next to the JavaScript file, or from a URL, bytes or compiled module. Required before new Writer() and toBufferSync. In Node.js it resolves immediately |
initSync(bytes | module) | Loads the module synchronously, for workers and server runtimes |
toBlob(rows, options?) | The whole file as a Blob with the XLSX content type, held in memory. Browsers only |
webStream(rows, options?) | A pull-based ReadableStream: rows are produced as the consumer reads |
In browsers, drain(), finish(), toBuffer and toBufferSync return a Uint8Array instead of a Buffer. stream (a Node Readable) and writeFile exist only in Node.js. The module file is exported as hypaxel/hypaxel_bg.wasm.
Go#
Writer
| Function | Purpose |
|---|---|
NewWriter(dst, opts...) | Start a workbook on any io.Writer |
AddStyle(style) | Register a cell format; identical styles share a StyleID |
AddSheet(name), AddSheetOptions(name, opts) | Add a worksheet |
StructColumns(v) | Column widths and visibility from a struct type’s tags |
Flush() | Send everything written so far to the destination now |
Close() | Complete the workbook. Does not close the destination |
Err() | The error that stopped the writer, if any |
Sheet
| Method | Purpose |
|---|---|
WriteString, WriteInt, WriteUint, WriteFloat, WriteBool | Typed cells, each with an optional style |
WriteTime, WriteDate, WriteDuration | Date and time, date only, and elapsed time |
WriteFormula, WriteBlank | A formula, and an empty cell that carries a style |
Write(v, style?) | Any supported value |
EndRow() | End the row and return any pending error |
WriteRow(values...), WriteRowStyled(style, values...) | One row from values |
WriteStrings(values, style?) | One row of text, such as a header |
WriteStruct(v), WriteStructHeader(v, style?) | One row from a struct, and its header row |
BeginRow(RowOptions{Index, Height, Style, OutlineLevel, Hidden, Collapsed}) | Start a row with a height, a row style, a grouping level or a row number further down |
SkipCells(n), SkipRows(n) | Leave cells or rows empty |
MergeCells(r1, c1, r2, c2), AutoFilter(r1, c1, r2, c2) | Ranges, 1-based and inclusive |
AddTable(Table{...}) | Turn a range into an Excel table |
Row(), Column() | Current position |
Package functions
| Function | Purpose |
|---|---|
WriteSheet, WriteSheetSeq, WriteSheetSeq2, WriteSheetChan | A whole worksheet from a slice, sequence or channel |
Styled(v, style), Formula("...") | A value with its own style, and a formula, for Write and WriteRow |
RGB(r, g, b), ParseColor("#RRGGBB") | Colors |
BorderAll(style, color), Widths(w...) | Shorthands for borders and column widths |
ColumnName(n), CellRef(row, column) | 27 to "AA", (7, 2) to "B7" |
Style and option types
| Type | Fields |
|---|---|
Style | NumberFormat, Font, Fill, Border, Alignment |
Font | Name, Size, Bold, Italic, Underline, Strike, Color |
Border | Left, Right, Top, Bottom, each a BorderLine{Style, Color} with 13 line styles |
Alignment | Horizontal, Vertical, WrapText, ShrinkToFit, Indent, Rotation |
SheetOptions | Columns (Width, Style, Hidden), FrozenRows, FrozenColumns, HideGridLines, Hidden, TabColor, RowOutlineLevels, OutlineSummaryAbove, AutoFit |
Writer options
| Option | Default | Meaning |
|---|---|---|
WithCompressionLevel(n) | 1 | Deflate level 0-9. 0 stores without compressing |
WithSharedStrings(true) | off | Shared string table: can be smaller for repeated text, uses more memory |
WithFlushThreshold(n) | 65536 | Compressed bytes buffered before they are written to the destination |
WithDate1904(true) | off | Use the 1904 date system |
WithCellReferences(true) | off | Write a reference such as B7 on every cell |
HTTP: hypaxelhttp.Handler(filename, func(r, w) error), hypaxelhttp.Serve(rw, r, filename, func(w) error), hypaxelhttp.ErrPartial.
Reading (guide)
| Function | Purpose |
|---|---|
OpenReader(path, opts...), NewReader(src io.ReaderAt, size, opts...) | Open a workbook; Close closes a file opened by path |
Sheets(), SheetNames() | Sheets in workbook order with Name, Visibility and Kind |
Rows(name), RowsAt(index) | Stream a sheet by name (exact, then case-insensitive) or 0-based index |
Date1904() | Whether the workbook uses the 1904 date system |
Rows.Next(), Row(), Err(), Close(), All() | Row loop; All() is an iter.Seq2[*Row, error] |
Row.Index(), Len(), LastColumn(), Cell(i), Cells(), Get(column), AppendValues(dst) | Row number, cells with values, a cell by 1-based column, dense values |
Value.Kind(), Text(), Float(), Bool(), Time(), Duration(), DateKind(), String() | Typed access; the zero Value is empty |
Reader options
| Option | Default | Meaning |
|---|---|---|
WithMaxSharedStringsBytes(n) | 1 GiB | Cap the shared string table |
WithConcurrentInflate(on) | on (off when GOMAXPROCS is 1) | Decompress on a separate goroutine while parsing |
Read errors: *ReadError with a Part field; test with errors.Is for ErrInvalidFile, ErrSheetNotFound, ErrMalformed, ErrLimitExceeded or ErrUnsupported.
Java#
XlsxWriter
| Method | Purpose |
|---|---|
create(OutputStream | Path, XlsxOptions?) | Creates a writer |
addStyle(Style) | Registers a cell format; identical styles share a StyleId |
addWorksheet(name, SheetOptions?) | Starts the next worksheet |
writeWorksheet(name, type, items) | Worksheet from objects with header, frozen row, filter and widths |
flush() | Sends buffered output to the destination now |
finish() | Completes the workbook and leaves the destination open |
abort() | Stops without completing the workbook |
close() | Completes the workbook (unless finished or aborted) and closes the destination |
Worksheet
| Method | Purpose |
|---|---|
write(value), write(value, style) | Next cell. Overloads: String, char, int, long, double, float, boolean, BigDecimal, LocalDate, LocalDateTime, LocalTime, Instant, ZonedDateTime, OffsetDateTime, java.util.Date, Duration |
writeFormula(formula, style?) | Formula cell; a leading = is optional |
writeBlank(style) | Empty cell that carries a format |
writeValue(object, style?) | Next cell by runtime type |
endRow() | Ends the row and hands buffered output to the destination |
beginRow(height?, style?), beginRow(RowOptions), beginRowAt(row, ...) | Starts a row with a height, row style, outline level or hidden state, or at a given row number. A following addRow fills it |
skipCells(n), skipRows(n) | Leave cells or rows empty |
addRow(values...), addRow(iterable), addStyledRow(style, values...) | One complete row |
addRows(iterable | stream) | One row per Object[] or Iterable element |
writeRows(items, (row, item) -> ...) | One row per item, written with the typed overloads |
writeObjects(type, items, ObjectOptions?) | One row per object |
mergeCells(r1, c1, r2, c2), autoFilter(r1, c1, r2, c2) | Ranges, 1-based and inclusive |
addTable(ExcelTable) | Excel table over a range |
rowNumber(), columnNumber() | Current position, 1-based |
In rows passed as objects, Cell.styled(value, style), Cell.formula("SUM(A1:A9)") and Cell.blank(style) give a single cell its own style or make it a formula. CellReference.of(row, column) and CellReference.range(...) build A1 references for formulas.
XlsxOptions.builder()
| Option | Default | Meaning |
|---|---|---|
compressionLevel | 1 | Deflate level 0-9. Level 6 gives smaller files for more CPU time |
stringStorage | INLINE | SHARED uses a shared string table |
flushThreshold | 65536 | Compressed bytes buffered before a write to the destination |
xmlBufferSize | 65536 | Uncompressed XML bytes buffered before compression |
cellReferences | false | Write a reference such as B7 on every cell |
date1904 | false | Use the 1904 date system |
zone | system default | Time zone for Instant and java.util.Date values |
closeOutput | true | Whether closing the writer closes the destination stream |
Other builders: Style.builder() (fontName, fontSize, bold, italic, underline, strikethrough, fontColor, fill, border, align, verticalAlign, wrapText, indent, rotation, numberFormat), SheetOptions.builder() (freezeRows, freezeColumns, columnWidths, column(index, Column), hideGridLines, hidden, tabColor, autoFitColumns, autoFit, rowOutlineLevels, outlineSummaryAbove), RowOptions.builder(), ExcelTable.builder(r1, c1, r2, c2), AutoFit.builder(), ObjectOptions.builder().
Reading (guide)
| Method | Purpose |
|---|---|
XlsxReader.open(Path | SeekableByteChannel | byte[] | InputStream, ReadOptions?) | Reads the package structure, sheet list and cell formats |
sheets(), sheetNames() | Sheets in workbook order with SheetVisibility and SheetKind |
worksheet(name), worksheet(index) | A SheetReader, by name (exact, then ignoring case) or 0-based position |
isDate1904(), sharedStringCount() | Date system, entries in the shared string table |
SheetReader.nextRow(), iterator, stream() | nextRow() and the iterator reuse one Row; stream() yields copies |
Row.number(), cellCount(), lastColumn(), column(i) | Row number, cells with a value and their columns |
Row.type(column) | CellType: EMPTY, STRING, NUMBER, BOOLEAN, DATE_TIME, ERROR |
getString, getNumber, getBoolean, getError, getDateTime, getLocalDateTime | Typed values by 1-based column |
getValue, getObject, getText, sharedStringIndex | As Value, a plain Java object, text, or shared string index |
cells(), values(), toList(), copy() | Cells with values, dense values, dense objects, a detached copy |
ExcelDateTime has serial(), kind() (DateKind: DATE, DATE_TIME, TIME, DURATION), toLocalDateTime(), toLocalDate(), toLocalTime(), toDuration() and toObject(). ReadOptions.builder().maxSharedStringsBytes(n) (default 1 GiB) caps the shared string table. Errors are XlsxException with kind() INVALID_FILE, MALFORMED, UNSUPPORTED, LIMIT_EXCEEDED or SHEET_NOT_FOUND, and part().
PHP#
Writer
| Method | Purpose |
|---|---|
addStyle(Style $style): StyleId | Registers a format. Identical styles share a handle |
addWorksheet($name, ?SheetOptions $options): Worksheet | Starts the next worksheet |
writeWorksheet($name, $data, columns:, header:, autoFilter:): int | A worksheet from rows or records, with header row |
finish(): string | Completes the workbook; returns the remaining bytes of an in-memory writer |
drain(): string, flush() | Take the bytes of an in-memory writer / push buffered bytes to the destination |
currentWorksheet(), worksheetCount(), bytesWritten(), isFinished() | State |
Worksheet
| Method | Purpose |
|---|---|
writeRow(iterable $values, ?StyleId $style) | One row. $style applies to cells without their own |
writeRows(iterable $rows, ?StyleId $style): int | Many rows from any iterable; returns the count |
writeRecords(iterable $records, array $columns): int | One row per array or object, taking $columns in order |
write($value, ?StyleId $style), endRow() | Cell-by-cell writing (chainable) |
beginRow(height:, style:, outlineLevel:, hidden:, collapsed:), beginRowAt($row, ...) | Start a row with a height, row format or outline level, or further down |
skipCells($n), skipRows($n) | Leave cells or rows empty |
mergeCells($r1, $c1, $r2, $c2), autoFilter($r1, $c1, $r2, $c2) | Ranges, 1-based and inclusive |
addTable(Table $table) | An Excel table over a range |
row(), column() | Current position |
Xlsx helpers
| Helper | Destination |
|---|---|
Xlsx::writeFile($path, $data, ...) | a file |
Xlsx::writeStream($resource, $data, ...) | any writable stream resource |
Xlsx::toString($data, ...) | a string (memory grows with the file) |
Xlsx::stream($data, ...) | a generator of chunks |
Xlsx::output($data, ...) | the response body, without headers |
Xlsx::download($filename, $data, ...) | the response body, with headers |
Xlsx::headers($filename), Xlsx::contentDisposition($filename), Xlsx::CONTENT_TYPE | header values for frameworks |
All helpers take sheetName, columns, header, autoFilter and options as named arguments.
Options
| Option | Default | Meaning |
|---|---|---|
compressionLevel | 1 | Deflate level 0-9 |
sharedStrings | false | Shared string table: smaller files for repeated text, memory grows with the number of distinct strings |
flushThreshold | 65536 | Compressed bytes buffered before a chunk goes to the destination (at least 1024) |
cellReferences | false | Write a reference such as B7 on every cell |
date1904 | false | Use the 1904 date system |
SheetOptions takes freezeRows, freezeColumns, columnWidths, columns, showGridLines, hidden, tabColor, rowOutlineLevels, outlineSummaryAbove and autoFit as named arguments. See the PHP guide for styles, tables and cell values.