Named Cell Templates

Named Cell Templates allow you to define reusable cell configurations that can be applied to any supported range in a workbook.

Unlike Named Styles, which encapsulate visual style properties only, Named Cell Templates can include multiple cell-related settings in a single reusable definition:

• Style

• Conditional formatting rules

• Data validation rules

• Cell states

By grouping these configurations into a template, you can ensure consistency and reduce repetitive setup across worksheets and other supported sheet types.

Core Concepts

Template Definition

A Named Cell Template is:

• Identified by a unique name

• Managed at the workbook level

• Case-insensitive by name

If a template is added using a name that already exists, the previous definition is replaced.

Templates are managed through workbook.namedCellTemplates.

Apply-Only Model

Named Cell Templates follow an apply-only model:

• A template takes effect only at the moment it is applied.

• No binding relationship is maintained between the template and the target range.

• Updating a template does not affect ranges where it has already been applied.

To reflect changes in previously formatted ranges, the template must be reapplied.

Immutable Retrieval

Calling get(name) on the template manager returns a deep copy of the stored template.

Modifying the returned object does not affect the registered template.

To update an existing template definition, call add() again using the same name. The previous definition will be overwritten.

Application Behavior

When a named cell template is applied to a target range, each configuration behaves according to the following rules:

Additional rules:

• No merging or deduplication is performed.

• Existing conditional formatting and cell state rules are preserved.

• The insertion priority of newly added rules follows the standard SpreadJS rule ordering behavior.

Because templates are apply-only, subsequent changes to the template do not propagate to previously formatted ranges.

Managing Templates

Templates are managed through the INamedCellTemplatesManager exposed on the workbook:

• Add a template

• Create a template from an existing cell

• Retrieve a template

• Remove a template

• Enumerate all templates

• Clear all templates

• Serialize and deserialize via JSON

Templates are stored at the workbook level and participate in workbook serialization.

Refer to the API Reference for full method signatures and options.

• INamedCellTemplatesManager

• INamedCellTemplate

Example: Create a Template

spread.namedCellTemplates.add("Financial Amount", {
    style: {
        formatter: "#,##0.00",
        hAlign: GC.Spread.Sheets.HorizontalAlign.right
    },
    conditionalFormats: [{
        ruleType: GC.Spread.Sheets.ConditionalFormatting.RuleType.cellValueRule,
        operator: GC.Spread.Sheets.ConditionalFormatting.ComparisonOperators.lessThan,
        value1: 0,
        style: { foreColor: "Accent 2" }
    }]
});

Sheet Type Support

Named Cell Templates can be applied to multiple sheet types. Behavior may vary slightly depending on the sheet implementation.

Worksheet

Use applyNamedCellTemplate on a worksheet or a range.

sheet.applyNamedCellTemplate("Financial Amount", "A1:A10");

// or
sheet.getRange("B1:B10")
     .applyNamedCellTemplate("Financial Amount");

Supported Address Formats

• A1-style ranges ("A1:C3")

• Entire rows or columns ("A:A", "1:3")

• Table structured references("Table1", "Table1[[#Data]]", "Table1[[#Headers]]")

See the API Reference for:

• Worksheet.applyNamedCellTemplate

• CellRange.applyNamedCellTemplate

ReportSheet

ReportSheet does not directly expose template application methods.

Instead, apply templates to its TemplateSheet, which defines layout and formatting:

const report = spread.addSheetTab(0, "Report", GC.Spread.Sheets.SheetType.reportSheet);
const templateSheet = report.getTemplate();

templateSheet.applyNamedCellTemplate("Financial Amount", "A1:A5");

TableSheet

On a TableSheet, templates are applied by specifying data source field names.

tableSheet.applyNamedCellTemplate("Financial Amount", ["price", "quantity"]);

Behavior

• A bound dataSource is required. If no data source is present, the template is not applied.

• Templates are applied column by column for the specified field names.

• Field names that do not exist in the data source are ignored.

• cellStates in templates are not supported and are ignored.

• Regular conditional formatting rules are applied per column.

• State-based rules are applied at the sheet level.

See the API Reference for:

• TableSheet.applyNamedCellTemplate

GanttSheet

GanttSheet supports Named Cell Templates using the same method as TableSheet.

Additional behavior

• Gantt chart columns are automatically skipped.

• Built-in functional columns retain their interactive editors.

When to Use Named Cell Templates

Use Named Cell Templates when:

• A reusable configuration includes more than style.

• Conditional formatting and validation rules must stay consistent.

• Interactive cell states need to be standardized.

If you only need reusable visual formatting, consider using Named Styles instead.

Integration with SpreadJS Designer

Named Cell Templates are fully supported through the SpreadJS runtime API.

SpreadJS Designer provides a visual interface for creating, editing, and applying templates, and may include additional preset templates for convenience.

Refer to the SpreadJS Designer documentation for details: Named Cell Templates.