From 458f216738aa59d612e1334dc856a70df720c0f4 Mon Sep 17 00:00:00 2001 From: Jochen Wezel Date: Thu, 30 Apr 2026 18:03:17 +0200 Subject: [PATCH 1/4] Document HTML export API --- AGENTS.md | 1 - .../ExcelDataOperationsBase.vb | 3 + .../HtmlSheetExportOptions.vb | 121 ++++++++++++------ .../HtmlWorkbookExportOptions.vb | 75 +++++------ tools/check-api-docs.ps1 | 27 +--- 5 files changed, 125 insertions(+), 102 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 54ddd51..b19a7a1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,6 @@ - Every new public API member must have XML documentation matching the quality of the surrounding API. - New protected members that define engine contracts or are intended for derived engine implementations must also have XML documentation. - The documentation requirements do not apply to the `EPPlus45-FixCalcsEdition.MultiTarget` project or to `TestAndDemoExcelOps`; do not make documentation-only changes there. -- The HTML export API classes are currently excluded from documentation cleanup because they are tracked for a separate follow-up ticket. - Historical documentation baselines should stay at zero. If a member is intentionally out of scope, add a narrow checker exclusion instead of raising a global allowance. - Public enums and their values must be documented. - Keep `` text short and focused, for example `Insert one or more columns.`. diff --git a/ExcelOps/ExcelOpsLowLevel/ExcelDataOperationsBase.vb b/ExcelOps/ExcelOpsLowLevel/ExcelDataOperationsBase.vb index 9833f2e..32ce71b 100644 --- a/ExcelOps/ExcelOpsLowLevel/ExcelDataOperationsBase.vb +++ b/ExcelOps/ExcelOpsLowLevel/ExcelDataOperationsBase.vb @@ -2320,6 +2320,9 @@ Namespace ExcelOps End Select End Sub + ''' + ''' Defines which parts of an HTML document are emitted for worksheet export. + ''' Public Enum HtmlDocumentExportParts As Byte ''' ''' Creates a full HTML document with header tags, style tags, etc. diff --git a/ExcelOps/ExcelOpsLowLevel/HtmlSheetExportOptions.vb b/ExcelOps/ExcelOpsLowLevel/HtmlSheetExportOptions.vb index ec01f7a..ce07aac 100644 --- a/ExcelOps/ExcelOpsLowLevel/HtmlSheetExportOptions.vb +++ b/ExcelOps/ExcelOpsLowLevel/HtmlSheetExportOptions.vb @@ -4,98 +4,136 @@ Imports System.Text Namespace ExcelOps + ''' + ''' Defines options for exporting a worksheet to HTML. + ''' Public Class HtmlSheetExportOptions + ''' + ''' Creates a new HTML worksheet export options instance. + ''' Public Sub New() End Sub + ''' + ''' Defines how a worksheet title is rendered before exported worksheet data. + ''' Public Enum SheetTitleStyles As Integer + ''' + ''' Does not render a worksheet title. + ''' None = 0 + ''' + ''' Renders the worksheet title as an H1 element. + ''' H1 = 1 + ''' + ''' Renders the worksheet title as an H2 element. + ''' H2 = 2 + ''' + ''' Renders the worksheet title as an H3 element. + ''' H3 = 3 + ''' + ''' Renders the worksheet title as an H4 element. + ''' H4 = 4 + ''' + ''' Renders the worksheet title as an H5 element. + ''' H5 = 5 + ''' + ''' Renders the worksheet title as an H6 element. + ''' H6 = 6 + ''' + ''' Renders the worksheet title as a paragraph element. + ''' P = 10 End Enum ''' - ''' Add a header before the sheet data + ''' Gets or sets how the worksheet name is rendered before worksheet data. ''' - ''' Public Property ExportSheetNameAsTitle As SheetTitleStyles ''' - ''' Cells of these row indexes will be converted to TH cells instead of TD cells + ''' Gets or sets row indexes whose cells are rendered as TH elements instead of TD elements. ''' - ''' Public Property ConsiderRowIndexesAsTableHeader As List(Of Integer) ''' - ''' The class name for the table in HTML + ''' Gets or sets the CSS class name used for generated worksheet tables. ''' - ''' Public Property TableCssClassName As String = "xlTable" #Disable Warning CA1805 ' Keine unnötige Initialisierung + ''' + ''' Gets or sets the zero-based index of the first worksheet row to export. + ''' Public Property FirstRowIndex As Integer = 0 + ''' + ''' Gets or sets the zero-based index of the first worksheet column to export. + ''' Public Property FirstColumnIndex As Integer = 0 + ''' + ''' Gets or sets the zero-based index of the last worksheet row to export. + ''' Public Property LastRowIndex As Integer? + ''' + ''' Gets or sets the zero-based index of the last worksheet column to export. + ''' Public Property LastColumnIndex As Integer? #Enable Warning CA1805 ' Keine unnötige Initialisierung + ''' + ''' Gets or sets the HTML emitted when a worksheet has no exportable content. + ''' Public Property HtmlForEmptySheet As String ''' - ''' HTML code on top of everything (including html and head tags) + ''' Gets or sets the HTML emitted before generated worksheet content, including HTML and HEAD tags. ''' - ''' Public Property HtmlDocumentHeader As String ''' - ''' HTML code on top of exported sheets (usually </head><body>) + ''' Gets or sets the HTML emitted between the document header and exported worksheets. ''' - ''' Public Property HtmlDocumentHeaderEndAndBeginOfBody As String ''' - ''' HTML code on bottom of everything (usually </body></html>) + ''' Gets or sets the HTML emitted after generated worksheet content. ''' - ''' Public Property HtmlDocumentEnd As String ''' - ''' Typically html+head tags + ''' Gets the default HTML document header. ''' - ''' Protected Friend ReadOnly Property DefaultHtmlDocumentHeader As String = "" & ControlChars.CrLf & "" & ControlChars.CrLf & "" ''' - ''' Typically /head+body tags + ''' Gets the default HTML fragment that closes HEAD and opens BODY. ''' - ''' Protected Friend ReadOnly Property DefaultHtmlDocumentHeaderEndAndBeginOfBody As String = "" ''' - ''' Typically /body+/html tags + ''' Gets the default HTML document ending. ''' - ''' Protected Friend ReadOnly Property DefaultHtmlDocumentEnd As String = "" ''' - ''' Typically some HTML indicating there was no content in Excel worksheet + ''' Gets the default HTML emitted for an empty worksheet. ''' - ''' Protected Friend ReadOnly Property DefaultHtmlForEmptySheet As String = "-/-" ''' - ''' Typically some HTML indicating there was no content in Excel worksheet + ''' Gets the effective HTML emitted for an empty worksheet. ''' - ''' + ''' Configured empty-sheet HTML, or the default empty-sheet HTML when no value is configured. Public Overridable Function EffectiveHtmlForEmptySheet() As String If HtmlForEmptySheet Is Nothing Then Return DefaultHtmlForEmptySheet @@ -105,9 +143,9 @@ Namespace ExcelOps End Function ''' - ''' Typically /head+body tags + ''' Gets the effective HTML fragment that closes HEAD and opens BODY. ''' - ''' + ''' Configured header/body transition HTML, or the default transition HTML when no value is configured. Public Overridable Function EffectiveHtmlDocumentHeaderEndAndBeginOfBody() As String If HtmlDocumentHeaderEndAndBeginOfBody Is Nothing Then Return DefaultHtmlDocumentHeaderEndAndBeginOfBody @@ -117,9 +155,9 @@ Namespace ExcelOps End Function ''' - ''' Typically html+head+styles+body tags + ''' Gets the effective HTML document header including styles and BODY start. ''' - ''' + ''' HTML emitted before worksheet content. Public Overridable Function EffectiveHtmlDocumentHeaderAndBody() As String Dim sb As New System.Text.StringBuilder(1024) sb.AppendLine(Me.EffectiveHtmlDocumentHeader) @@ -129,9 +167,9 @@ Namespace ExcelOps End Function ''' - ''' Typically html+head tags + ''' Gets the effective HTML document header. ''' - ''' + ''' Configured document header HTML, or the default document header HTML when no value is configured. Public Overridable Function EffectiveHtmlDocumentHeader() As String If HtmlDocumentHeader Is Nothing Then Return DefaultHtmlDocumentHeader @@ -141,9 +179,9 @@ Namespace ExcelOps End Function ''' - ''' Typically /body+/html tags + ''' Gets the effective HTML document ending. ''' - ''' + ''' Configured document end HTML, or the default document end HTML when no value is configured. Public Overridable Function EffectiveHtmlDocumentEnd() As String If HtmlDocumentEnd Is Nothing Then Return DefaultHtmlDocumentEnd @@ -153,9 +191,9 @@ Namespace ExcelOps End Function ''' - ''' Style HTML for the table (<style>...</style>) + ''' Gets the effective STYLE element for generated worksheet tables. ''' - ''' + ''' HTML STYLE element for generated worksheet tables. Public Overridable Function EffectiveTableCssClassStyleHtml() As String Dim sb As New System.Text.StringBuilder(1024) sb.AppendLine("