BlazorDatasheet

BlazorDatasheet uses two primary abstractions:

• Datasheet: The Blazor UI component that renders the grid.
• Sheet: The underlying data model that holds cell data, configuration, and logic.

You instantiate a Sheet (defining its dimensions) and pass it to the Datasheet component via the Sheet parameter. You can create a sheet manually by specifying rows and columns, or use the ObjectEditorBuilder to generate a sheet from a list of objects.

By default, cells use a text editor, but you can change this by setting the Type property of specific cells or ranges.

<Datasheet Sheet="sheet" />

@code{
    private Sheet sheet;

    protected override void OnInitialized()
    {
        // Creates an empty 3x3 grid
        sheet = new Sheet(3, 3);
    }
}

To use BlazorDatasheet in your Blazor project, follow these three steps:

1. Install the NuGet package via the dotnet CLI.
2. Register the services in your Program.cs file.
3. Import the required CSS in your _Layout.cshtml or index.html file.

This ensures the component logic and styles are available to your application.

# 1. Install the package
dotnet add package BlazorDatasheet

// 2. Configure Program.cs
builder.Services.AddBlazorDatasheet();

<!-- 3. Import JS/CSS in _Layout.cshtml or index.html -->
<link href="_content/BlazorDatasheet/sheet-styles.css" rel="stylesheet"/>

Formulas can be assigned to cells using the .Formula property. The formula must start with an = sign. BlazorDatasheet automatically re-calculates the formula whenever the cells or ranges referenced by the formula are updated.

// Sets a formula in cell A1 that adds 10 to the value in A2
sheet.Cells[0, 0].Formula = "=10+A2";

You can manipulate cell values using direct indexers, range strings, or commands. Values are internally wrapped in a CellValue object and assigned a CellValueType (e.g., Number, Text, Date, Logical) based on the value provided.

To prevent automatic type conversion, you can explicitly set a cell's Type to "text". You can also intercept and modify values before they are stored by using the Sheet.Cells.BeforeCellValueConversion event.

// Using indexers
sheet.Cells[0, 0].Value = "Test";

// Using A1 notation ranges
sheet.Range("A1").Value = "Test";

// Using the Cells helper
sheet.Cells.SetValue(0, 0, "Test");

// Using commands
sheet.Commands.ExecuteCommand(new SetCellValueCommand(0, 0, "Test"));

You can add validators to specific regions (like a ColumnRegion) using sheet.Validators.Add. There are two validation modes:

1. Strict (isStrict: true): If the value fails validation, the editor will prevent the value from being set.
2. Non-strict (isStrict: false): The value can be set during editing, but a validation error will be displayed when rendered.

Note: Even with strict validation, programmatic changes to a cell can still result in a validation error being displayed.

// Add a strict number validator to the first column (index 0)
sheet.Validators.Add(new ColumnRegion(0), new NumberValidator(isStrict: true));

Formatting (like BackgroundColor, ForegroundColor, or TextAlign) can be applied to individual cells, ranges, or entire regions.

Merging Formats: When you apply a format to a region, it is merged with existing formats. If a new format has non-null properties, only those specific properties are updated, preserving the rest of the existing style.

// Set format on a range
sheet.Range("A1:A2").Format = new CellFormat() { BackgroundColor = "red" };

// Set format via command on a RowRegion
sheet.Commands.ExecuteCommand(new SetFormatCommand(new RowRegion(10, 12), new CellFormat() { ForegroundColor = "blue" }));

// Set format on a ColumnRegion
sheet.SetFormat(sheet.Range(new ColumnRegion(5)), new CellFormat() { FontWeight = "bold" });

// Set format on a single cell
sheet.Cells[0, 0].Format = new CellFormat() { TextAlign = "center" };

The Type property of a cell or range determines which renderer and editor are used. For example, setting a type to "boolean" will render a checkbox. This also assists in explicit type conversion when setting values.

// Renders checkboxes for the specified range
sheet.Range("A1:B5").Type = "boolean";

The setupGlobals() function initializes essential global helpers required for BlazorDatasheet to function correctly. This includes setting up window.writeTextToClipboard for clipboard operations and window.setFocusWithTimeout for managing element focus. It also eagerly imports the highlighter module to prevent latency during the first edit operation. This function is idempotent and can be called multiple times without side effects.

import { setupGlobals } from './BlazorDatasheet.lib.module.js';

setupGlobals();

BlazorDatasheet provides lifecycle hooks to ensure global helpers are configured at the correct stage of the Blazor application startup. Depending on your Blazor version and startup pattern, you should call one of the following exported functions:

• beforeStart(): Use this for standard Blazor startup sequences.
• beforeWebStart(): Use this for newer Blazor Web startup sequences.

Both functions internally call setupGlobals() to prepare the environment.

// For standard Blazor startup
import { beforeStart } from './BlazorDatasheet.lib.module.js';

// Call this during your app initialization
beforeStart();

You can create complex workflows by chaining ICommand instances. This allows a single command execution to trigger a sequence of other commands.

• AttachAfter(ICommand command): Schedules a command to run immediately after the current command completes.
• AttachBefore(ICommand command): Schedules a command to run immediately before the current command starts.
• ClearChainedCommands(), ClearChainedAfterCommands(), and ClearChainedBeforeCommands(): Remove existing chained commands from the current command instance.