OfficeIMO.Excel.Html 3.6.0

OfficeIMO.Excel.Html

First-party HTML adapter for OfficeIMO.Excel. It exports semantic worksheet tables or visual review HTML using the shared OfficeIMO.Html profile contracts and the existing Excel SVG image exporter.

Semantic round trips

using OfficeIMO;
using OfficeIMO.Excel;
using OfficeIMO.Html;
using OfficeIMO.Excel.Html;

using ExcelDocument workbook = ExcelDocument.Load("report.xlsx", new ExcelLoadOptions {
    AccessMode = DocumentAccessMode.ReadOnly
});
string html = workbook.ToHtml(new ExcelHtmlExportOptions {
    HeaderMode = ExcelHtmlHeaderMode.FirstRow
});

HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
OfficeConversionReport report = source.SaveAsExcel("report-roundtrip.xlsx");

Semantic output carries a versioned OfficeIMO envelope and preserves worksheet names and visibility, used-range coordinates, typed text/number/boolean/date-time values, formulas, comments, merged ranges, embedded image inventory, supported chart inventory, and inert pivot-definition review metadata. HTML rowspan and colspan values become native Excel merged ranges. Pivot refresh, drill, caches, slicers, and timelines remain native workbook behavior and are not executed in HTML.

Named Excel tables export as worksheet cells without their native table definitions. Table names, table-scoped filters, table styles and totals metadata are not restored; workbook and worksheet export reports mark this omission. Ordinary HTML table IDs do not create named Excel tables.

Semantic tables show the worksheet as it reads in Excel: cell and table-style fills with their font colours, conditional fills and data bars, number formats (dates, percentages, grouping), Excel's general alignment for numbers, dates and Boolean values, and charts drawn as inline SVG with their data in a collapsible table. The raw value of every cell stays in data-officeimo-value for round trips. Set ApplyCellPresentation = false for raw cell text, and RenderCharts = false to keep charts as data tables only. The formula inventory (IncludeFormulaInventory) and visible object metadata such as chart type, anchor cell and pixel size (IncludeObjectMetadata) are opt-in; formulas still travel with their cells. The page title uses the Title option, then the workbook's title property, then the file name.

HeaderMode makes the first-row assumption explicit. FirstRow is the compatibility default and emits a real thead with column headers. Use None when every row is data.

ToExcel(options, out report) returns the workbook with its OfficeConversionReport and throws HtmlConversionException when no semantic section.officeimo-sheet envelope exists; SaveAsExcel writes it and returns the report. Set FailOnLoss to make reported loss an error. Export callers use ToHtml(options, out report) or SaveAsHtml for the same report.

Ordinary HTML tables are available explicitly through the shared generic projector:

using ExcelDocument workbook = HtmlConversionDocument.Parse(html)
    .ToExcel(new HtmlExcelExportOptions {
        Mode = HtmlImportMode.Auto
    }, out OfficeConversionReport report);

Semantic remains the default for strict round-trip compatibility. Auto selects a supported semantic envelope when present and otherwise maps ordinary tables to worksheets; Generic always uses the ordinary HTML path. HtmlExcelExportOptions.Limits bounds worksheets, tables, cells, images, chart dimensions, metadata, and geometry before native allocations. MaxTableCells remains as a forwarding compatibility property.

Generic table worksheets fit their columns to imported text within bounded widths, wrap longer values, and fit row heights. Two-column term/definition tables retain their printable layout. HTML spans remain native merged ranges; ordinary grids do not become named Excel table objects. This default presentation does not reproduce CSS table geometry.

On the ordinary HTML path, bounded positioned, floating, flex, and grid regions become editable merged-cell regions plus absolute DrawingML picture anchors. Solid backgrounds become cell fills, and foreground pictures retain supported native opacity. CSS background-image layers are omitted so they cannot cover editable cell text and produce a stable diagnostic. Excel has no editable cell-shadow equivalent, so shadows and unsupported effects are diagnosed while content and geometry remain editable. Set ImportEditableLayoutRegions = false to retain semantic flow only.

Embedded static WebP and AVIF pictures are decoded by the shared managed Core engine and stored as PNG in the workbook. Generic images, semantic inventories, and layout-region pictures use the same preparation path. Limits.MaxDecodedImagePixels bounds normalization, while MaxImageBytes and MaxTotalImageBytes bound source payloads and the retained native PNG. Independently, MaxImages and MaxTotalImageBytes cap admitted normalization attempts and their total input bytes; a failed normalization releases its output slot but retains its work charge. Animated, malformed, unsupported, or over-limit images produce omission diagnostics; PNG normalization produces an approximation diagnostic because the original compressed format is replaced. Native image placement and alternative text are retained.

SaveAsHtml and SaveAsHtmlAsync write UTF-8 without a byte-order mark to paths or caller-owned streams. For import I/O, use HtmlConversionDocument.Load(...) or LoadAsync(...), then call ToExcel or SaveAsExcel on the prepared document. Stream overloads leave caller-owned streams open.

Typed values in ordinary report tables

Set ImportTypedCellValues = true with Mode = HtmlImportMode.Generic (or Auto when no semantic envelope is present) to import explicitly declared scalar values:

<td data-officeimo-value-kind="number" data-officeimo-value="12.5"><strong>12.50</strong></td>
<td data-officeimo-value-kind="boolean" data-officeimo-value="true">Approved</td>
<td data-officeimo-value-kind="date-time" data-officeimo-value="2026-09-08T00:00:00">8 Sep 2026</td>
<td>00127</td>

The first three cells become a number, boolean, and date in Excel. The reference remains text, including its leading zeros. Supported kinds are text, number, boolean, and date-time; use invariant numeric values. Dates require yyyy-MM-dd, optionally followed by THH:mm, seconds, and up to seven fractional second digits. A timestamp may end in Z or an offset such as +02:00; explicit zones normalize to UTC, while unzoned values retain their wall-clock time. Incomplete dates, non-ISO values, and other invalid or oversized metadata fall back to bounded visible text with a diagnostic. The option defaults to false, so existing generic imports keep their text behavior.

var report = HtmlConversionDocument.Load("service-review.html");
report.SaveAsExcel("service-review.xlsx", new HtmlExcelExportOptions {
    Mode = HtmlImportMode.Generic,
    ImportTypedCellValues = true
});

See the text formatting support matrix for scalar formatting and display limits.

The multi-format report example exports one HTML source to HTML, PDF, Word, and Excel.

Visual review

Use ExcelHtmlExportOptions.CreateVisualReviewProfile() or set ExportProfile = ExcelHtmlExportProfile.VisualReview to emit review HTML through OfficeIMO's dependency-free SVG renderer. SharedProfile exposes the corresponding generic engine lane. DocumentOutput controls full-document versus fragment output, title, language, theme, default styles, and newlines. Visual-review HTML is presentation evidence; use semantic tables when the HTML must be imported back into Excel.

Targets

netstandard2.0, net8.0, and net10.0; net472 is included when building on Windows.

Dependency footprint

• External: None beyond the dependencies of its OfficeIMO format packages.
• OfficeIMO: OfficeIMO.Excel, OfficeIMO.Html, and OfficeIMO.Core own the workbook, HTML source, mapping, visual review, and reports.

See the complete OfficeIMO package map for related formats and conversion paths.

Generic table presentation

Generic HTML tables, including ARIA tables, import as editable worksheet cells with supported spans. Column widths and wrapped row heights reflect the imported content. Authored captions remain below the native grid, preserving a single whole-caption hyperlink; partially linked captions report their limitation. Linked images retain their native picture hyperlink. Semantic image inventories preserve the target as inert metadata for round-trip import. Visual-review SVG preserves web, mail, telephone, and relative targets allowed by the shared drawing-link policy; rejected interactive targets retain the image and report an omission. Raster images do not carry clickable links.

Generated capability summary

This table is generated from the package-neutral OfficeIMO operation catalog. The detailed source contracts remain authoritative for feature-level behavior and limitations.

The complete rows for OfficeIMO.Excel.Html are published in the generated operation contract.