Register a style in a workbook

The wb_add_style() function serves as a general-purpose entry point for registering XML-based style definitions into a wbWorkbook. While specific wrappers like wb_add_font() target individual cell properties, wb_add_style() is used to add pre-constructed styles—such as custom table styles or differential formatting (DXF) styles—to the workbook's internal style manager.

Usage

wb_add_style(wb, style = NULL, style_name = NULL)

Arguments

wb: A wbWorkbook object.
style: A character string containing the XML definition of the style. This is usually the output of functions like create_cell_style() or create_dxfs_style().
style_name: Optional; a unique name for the style. If NULL, the function attempts to derive a name from the object name or the internal XML attributes (e.g., for table styles).

Value

The wbWorkbook object, invisibly.

Details

Styles in the OpenXML specification are stored in a centralized catalog (styles.xml). This function takes an XML character string, typically generated by a create_*() function, and registers it under a specific style_name.

Once registered, these styles can be applied to cells, ranges, or tables by referencing their name. This is particularly useful for maintaining consistency across a large workbook or when creating complex "Table Styles" that define headers, footers, and banding in a single object.

Notes

If the style provided is a tableStyle node, the function automatically extracts the name from the XML attribute if style_name is not provided.
Registering a style does not automatically apply it to a cell; it only makes the style available within the workbook's style catalog.

Examples

yellow_f <- wb_color(hex = "FF9C6500")
yellow_b <- wb_color(hex = "FFFFEB9C")

yellow <- create_dxfs_style(font_color = yellow_f, bg_fill = yellow_b)
wb <- wb_workbook()
wb <- wb_add_style(wb, yellow)