Package io.github.dornol.excelkit.excel

Class ExcelSheetWriter<T>

java.lang.Object
io.github.dornol.excelkit.excel.ExcelSheetWriter<T>
Type Parameters:
T - the row data type for this sheet
public class ExcelSheetWriter<T> extends Object
Writes data of a specific type to one or more sheets within an ExcelWorkbook.

Supports optional auto-rollover via maxRows(int) — when set, the writer automatically creates additional sheets when the row limit is reached.

Column configuration uses ColumnConfig (via Consumer<ColumnConfig<T>>) rather than ExcelColumn.ExcelColumnBuilder. Unlike ExcelWriter's builder, there is no style(CellStyle) method — styles are derived from the declarative config properties (type, bold, color, borders, etc.).

  • Method Details

    • column

      public ExcelSheetWriter<T> column(String name, Function<T,@Nullable Object> function)
      Adds a column using a simple function.
      Parameters:
      name - the column header
      function - function to extract the cell value
      Returns:
      this writer for chaining

    • column

      public ExcelSheetWriter<T> column(String name, Function<T,@Nullable Object> function, Consumer<ColumnConfig<T>> cfg)
      Adds a column with additional configuration.
      Parameters:
      name - the column header
      function - function to extract the cell value
      cfg - consumer to configure column styling
      Returns:
      this writer for chaining

    • column

      public ExcelSheetWriter<T> column(String name, RowFunction<T,@Nullable Object> function)
      Adds a column using a row function with cursor support.
      Parameters:
      name - the column header
      function - function to extract the cell value
      Returns:
      this writer for chaining

    • column

      public ExcelSheetWriter<T> column(String name, RowFunction<T,@Nullable Object> function, Consumer<ColumnConfig<T>> cfg)
      Adds a column using a row function with cursor support and additional configuration.
      Parameters:
      name - the column header
      function - function to extract the cell value
      cfg - consumer to configure column styling
      Returns:
      this writer for chaining

    • constColumn

      public ExcelSheetWriter<T> constColumn(String name, @Nullable Object value)
      Adds a column with a constant value for all rows.
      Parameters:
      name - the column header
      value - the constant value
      Returns:
      this writer for chaining

    • rowHeight

      public ExcelSheetWriter<T> rowHeight(float rowHeightInPoints)
      Sets the row height for data rows in points.
      Parameters:
      rowHeightInPoints - Row height in points
      Returns:
      this writer for chaining

    • autoFilter

      public ExcelSheetWriter<T> autoFilter()
      Enables auto-filter on the header row.
      Returns:
      this writer for chaining

    • autoFilter

      public ExcelSheetWriter<T> autoFilter(boolean autoFilter)
      Enables or disables auto-filter on the header row.
      Parameters:
      autoFilter - Whether to apply auto-filter
      Returns:
      this writer for chaining

    • columnIf

      public ExcelSheetWriter<T> columnIf(String name, boolean condition, Function<T,@Nullable Object> function)
      Conditionally adds a column using a simple function.
      Parameters:
      name - Column header name
      condition - Whether to include this column
      function - Function to extract cell value from row
      Returns:
      this writer for chaining

    • columnIf

      public ExcelSheetWriter<T> columnIf(String name, boolean condition, Function<T,@Nullable Object> function, Consumer<ColumnConfig<T>> cfg)
      Conditionally adds a column with additional configuration.
      Parameters:
      name - Column header name
      condition - Whether to include this column
      function - Function to extract cell value from row
      cfg - Consumer to configure column options
      Returns:
      this writer for chaining

    • freezeRows

      public ExcelSheetWriter<T> freezeRows(int rows)
      Freezes the specified number of top rows. For both-axes freezing use freezePane(int, int); for columns-only use freezeCols(int).
      Parameters:
      rows - number of rows to freeze
      Returns:
      this writer for chaining
      Since:
      0.16.6

    • freezeCols

      public ExcelSheetWriter<T> freezeCols(int cols)
      Freezes the specified number of left columns. For both-axes freezing use freezePane(int, int); for rows-only use freezeRows(int).
      Parameters:
      cols - number of columns to freeze
      Returns:
      this writer for chaining
      Since:
      0.16.6

    • freezePane

      public ExcelSheetWriter<T> freezePane(int cols, int rows)
      Freezes the specified number of columns and rows.
      Parameters:
      cols - number of columns to freeze from the left
      rows - number of rows to freeze
      Returns:
      this writer for chaining

    • beforeHeader

      public ExcelSheetWriter<T> beforeHeader(BeforeHeaderWriter writer)
      Registers a callback that writes content before the header row.
      Parameters:
      writer - the before-header writer callback
      Returns:
      this writer for chaining

    • afterData

      public ExcelSheetWriter<T> afterData(AfterDataWriter writer)
      Registers a callback that writes content after all data rows.
      Parameters:
      writer - the after-data writer callback
      Returns:
      this writer for chaining

    • rowColor

      public ExcelSheetWriter<T> rowColor(Function<T,@Nullable ExcelColor> fn)
      Sets a function that determines the background color for each row.
      Parameters:
      fn - function returning a color per row, or null
      Returns:
      this writer for chaining

    • onProgress

      public ExcelSheetWriter<T> onProgress(int interval, ProgressCallback callback)
      Registers a progress callback that fires every interval rows.
      Parameters:
      interval - the number of rows between each callback invocation
      callback - the callback to invoke
      Returns:
      this writer for chaining

    • maxRows

      public ExcelSheetWriter<T> maxRows(int maxRows)
      Sets the maximum number of rows per sheet before auto-rollover.

      When set, the writer automatically creates additional sheets within the workbook when the row limit is reached. Use sheetName(Function) to control rollover sheet naming.

      Parameters:
      maxRows - maximum rows per sheet (must be positive)
      Returns:
      this writer for chaining

    • sheetName

      public ExcelSheetWriter<T> sheetName(Function<Integer,String> sheetNameFunction)
      Sets a function that generates sheet names for rollover sheets. The function receives the 0-based rollover index (0 = first rollover sheet, i.e., the second sheet).

      If not set, rollover sheets are named "{baseName} (2)", "{baseName} (3)", etc.

      Parameters:
      sheetNameFunction - function to generate sheet names
      Returns:
      this writer for chaining

    • autoWidthSampleRows

      public ExcelSheetWriter<T> autoWidthSampleRows(int rows)
      Sets the number of rows sampled for auto column width calculation. Defaults to 100. Set to 0 to disable.
      Parameters:
      rows - number of rows to sample
      Returns:
      this writer for chaining

    • protectSheet

      public ExcelSheetWriter<T> protectSheet(String password)
      Protects the sheet(s) with the given password.
      Parameters:
      password - the protection password
      Returns:
      this writer for chaining

    • conditionalFormatting

      public ExcelSheetWriter<T> conditionalFormatting(Consumer<ExcelConditionalRule> configurer)
      Adds a conditional formatting rule to the sheet(s).
      Parameters:
      configurer - consumer to configure the rule
      Returns:
      this writer for chaining

    • chart

      public ExcelSheetWriter<T> chart(Consumer<ExcelChartConfig> configurer)
      Configures a chart to be added after data is written.
      Parameters:
      configurer - consumer to configure the chart
      Returns:
      this writer for chaining

    • printSetup

      public ExcelSheetWriter<T> printSetup(Consumer<ExcelPrintSetup> configurer)
      Configures print setup (page layout) for the sheet(s).

      Controls orientation, paper size, margins, headers/footers, repeat rows, and fit-to-page.

      Parameters:
      configurer - consumer to configure the print setup
      Returns:
      this writer for chaining

    • tabColor

      public ExcelSheetWriter<T> tabColor(int r, int g, int b)
      Sets the sheet tab color using RGB values.
      Parameters:
      r - Red component (0–255)
      g - Green component (0–255)
      b - Blue component (0–255)
      Returns:
      this writer for chaining
      Since:
      0.7.0

    • tabColor

      public ExcelSheetWriter<T> tabColor(ExcelColor color)
      Sets the sheet tab color using a preset color.
      Parameters:
      color - Preset color
      Returns:
      this writer for chaining
      Since:
      0.7.0

    • defaultStyle

      public ExcelSheetWriter<T> defaultStyle(Consumer<ColumnStyleConfig.DefaultStyleConfig<T>> configurer)
      Sets default column styles that apply to all columns unless overridden per-column.
      Parameters:
      configurer - consumer to configure default style properties
      Returns:
      this writer for chaining

    • summary

      public ExcelSheetWriter<T> summary(Consumer<ExcelSummary> configurer)
      Configures summary (footer) rows with formulas such as SUM, AVERAGE, COUNT, MIN, MAX.
      Parameters:
      configurer - consumer to configure the summary
      Returns:
      this writer for chaining

    • write

      public void write(Stream<T> stream)
      Writes the data stream to this sheet (with optional auto-rollover).
      Parameters:
      stream - the data stream to write