{"id":19626583,"url":"https://github.com/softcircuits/softcircuits.spreadsheetbuilder","last_synced_at":"2025-04-28T05:33:46.370Z","repository":{"id":38379237,"uuid":"397009774","full_name":"SoftCircuits/SoftCircuits.SpreadsheetBuilder","owner":"SoftCircuits","description":"Lightweight class to build Excel spreadsheet files (XLSX) without Excel.","archived":false,"fork":false,"pushed_at":"2022-06-05T21:28:23.000Z","size":145,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-03T01:06:53.684Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SoftCircuits.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-16T23:19:29.000Z","updated_at":"2023-04-10T13:51:02.000Z","dependencies_parsed_at":"2022-07-12T02:17:11.348Z","dependency_job_id":null,"html_url":"https://github.com/SoftCircuits/SoftCircuits.SpreadsheetBuilder","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftCircuits%2FSoftCircuits.SpreadsheetBuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftCircuits%2FSoftCircuits.SpreadsheetBuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftCircuits%2FSoftCircuits.SpreadsheetBuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftCircuits%2FSoftCircuits.SpreadsheetBuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftCircuits","download_url":"https://codeload.github.com/SoftCircuits/SoftCircuits.SpreadsheetBuilder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224098960,"owners_count":17255545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T11:47:03.404Z","updated_at":"2024-11-11T11:47:05.798Z","avatar_url":"https://github.com/SoftCircuits.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spreadsheet Builder\n\n[![NuGet version (SoftCircuits.SpreadsheetBuilder)](https://img.shields.io/nuget/v/SoftCircuits.SpreadsheetBuilder.svg?style=flat-square)](https://www.nuget.org/packages/SoftCircuits.SpreadsheetBuilder/)\n\n```\nInstall-Package SoftCircuits.SpreadsheetBuilder\n```\n\n## Overview\n\nSpreadsheetBuilder is a lightweight class that makes it easy to create Microsoft Excel spreadsheet (XLSX) files without Excel.\n\nThe library forgoes some features in order to keep things simple. But should be sufficient for most requirements for building an Excel spreadsheet.\n\nThe following example creates a new Excel spreadsheet file, sets a value at cell *A1*, and then saves the file.\n\n```cs\nusing SpreadsheetBuilder builder = SpreadsheetBuilder.Create(Filename);\nbuilder.SetCell(\"A1\", \"Hello, World!\");\nbuilder.Save();\n```\n## Getting Started\n\nTo get started, create an instance of the `SpreadsheetBuilder` class. You can do that using any of the following static methods of the `SpreadsheetBuilder` class.\n\n```cs\npublic static SpreadsheetBuilder Create(string path, SpreadsheetDocumentType type = SpreadsheetDocumentType.Workbook);\n\npublic static SpreadsheetBuilder CreateFromTemplate(string path);\n\npublic static SpreadsheetBuilder Open(string path, bool isEditable);\n```\n\nThe `SpreadsheetBuilder` class implements `IDisposable`, so you should use a `using` statement to ensure the class cleans up in a timely manner.\n\n```cs\nusing SpreadsheetBuilder builder = SpreadsheetBuilder.Create(Filename);\n```\n\nOnce you've constructed the document, you can save it to disk by calling the `Save()` or `SaveAs()` method.\n\n## Setting Cell Values\n\nTo set the value of a cell, use the `SetCell()` method.\n\n```cs\nbuilder.SetCell(\"A1\", \"Hello, World!\");\n```\n\nThis method has dozens of overloads. You can pass a string, as shown in the example above, or you can pass other data types such as integers, doubles and decimals.\n\n```cs\nbuilder.SetCell(\"B5\", 123.45);\n```\n\nThe first argument specifies the cell address. You can pass the address as a string, as shown above, or you can pass an instance of the `CellReference` class. When you pass a string, the syntax is more compact but the library must convert the address to a `CellReference`. So some performance gains might be possible by passing a `CellReference` directly.\n\n```cs\nbuilder.SetCell(new CellReference(2, 5), 123.45);\n```\n\nTo create a calculated cell, you can pass an instance of the `CellFormula` class.\n\n```cs\nbuilder.SetCell(\"C17\", new CellFormula(\"SUM(A1:C16)\");\n```\n\n## Formatting Cells\n\nOne of the more onerous tasks of building spreadsheets is creating and tracking cell formats.\n\nSpreadsheet builder simplifies things somewhat by defining a number of predefined cell formats via the `CellStyles` property. Overloads of `SetCell()` accept a style ID parameter.\n\n```cs\nbuilder.SetCell(\"A7\", 123.45, builder.CellStyles[StandardCellStyle.Currency]);\n```\n\n*Note: If you pass a `decimal` type to `SetCell()`, the library automatically uses the currency style when no style ID is specified.*\n\nIf you need something other than one of the default cell formats, you can create your own as shown in the following example.\n\n```cs\nuint bold = builder.CellStyles.Register(new CellFormat()\n{\n    FontId = builder.FontStyles[StandardFontStyle.Bold],\n    ApplyFont = BooleanValue.FromBoolean(true),\n});\n\nuint header = builder.CellStyles.Register(new CellFormat()\n{\n    FontId = builder.FontStyles[StandardFontStyle.Header],\n    ApplyFont = BooleanValue.FromBoolean(true)\n});\n\nuint subheader = builder.CellStyles.Register(new CellFormat()\n{\n    FontId = builder.FontStyles[StandardFontStyle.Subheader],\n    ApplyFont = BooleanValue.FromBoolean(true)\n});\n\nuint headerRight = builder.CellStyles.Register(new CellFormat()\n{\n    FontId = builder.FontStyles[StandardFontStyle.Header],\n    ApplyFont = BooleanValue.FromBoolean(true),\n    Alignment = new() { Horizontal = HorizontalAlignmentValues.Right },\n    ApplyAlignment = BooleanValue.FromBoolean(true)\n});\n\nuint subheaderRight = builder.CellStyles.Register(new CellFormat()\n{\n    FontId = builder.FontStyles[StandardFontStyle.Subheader],\n    ApplyFont = BooleanValue.FromBoolean(true),\n    Alignment = new() { Horizontal = HorizontalAlignmentValues.Right },\n    ApplyAlignment = BooleanValue.FromBoolean(true)\n});\n\nbuilder.SetCell(\"D22\", \"Header\", header);\n```\n\nIn addition to the `CellStyles` property, the `SpreadsheetBuilder` class also has `NumberFormats`, `FontStyles`, `FillStyles` and `BorderStyles` properties that provide standard styles and the ability to add new ones similar to the `CellStyles` property.\n\n*Note: When you register a style, it is stored within the current instance of `SpreadsheetBuilder`. Care should be taken to ensure you don't create the same style more than once for the same instance of `SpreadsheetBuilder`.*\n\n## Tables\n\nYou can create tabular data by setting the value of the appropriate cells, or you can use the `TableBuilder` class.\n\nThe `TableBuilder` class simplifies the process of creating tabular data, offers some performance gains, and can also be used to create and format a named Excel table.\n\nThe `TableBuilder` constructor takes an instance of the `SpreadsheetBuilder` class, a cell reference to the cell at the top, left corner of the table, and either of:\n\n- The number of columns\n- An `IEnumerable\u003cstring\u003e` of the column headers\n\nIf you specify the number of columns, it is assumed the table has no headers.\n\nTo write data to the table, call the `AddRow()` method. This method accepts any number of arguments, each of which is assigned to the corresponding cell on the current table row. The type of the arguments can be `string`, `int`, `double`, etc. They can also be an instance of `CellValue\u003cT\u003e`, which can specify a style ID in addition to a value. In addition, they can also be an instance of `CellFormula`.\n\n```cs\nstring[] headers = new string[]\n{\n  \"Column1\",\n  \"Column2\",\n  \"Column3\"\n};\n\nTableBuilder table = new(builder, \"A4\", headers);\ntable.AddRow(\"Abc\", 123, 123.45m);\ntable.AddRow(\"Def\", 456, 4000m);\n```\n\nThe `TableBuilder` class has many properties for returning things like the range of the table built so far.\n\nOnce you've finished building the tabular data, you can create an Excel table and style it.\n\n```cs\ntable.BuildTable(\"MyTableName\", ExcelTableStyle.MediumBlue6);\n```\n\n## Column Widths\n\nUse the following method to set the width of a column.\n\n```cs\npublic void SetColumnWidth(uint index, double width);\n```\n\n`index` is the 1-based index of the column to set. `width` is the new column width measured as the number of characters of the maximum digit width of the numbers 0, 1, 2, ..., 9 as rendered in the normal style's font. There are 4 pixels of margin padding (two on each side), plus 1 pixel padding for the gridlines.\n\nUse the following method to set the width of a range of columns.\n\n```cs\npublic void SetColumnWidth(uint startIndex, uint endIndex, double width)\n```\n\n## Worksheets\n\nWhen creating a new spreadsheet document, the library automatically creates a worksheet called *Sheet1*.\n\nThe `Worksheet` property is set to the active worksheet, if any. Set this property to change the active worksheet.\n\nIn addition, the following methods are provided.\n\n```cs\npublic Worksheet? GetFirstWorksheet()\n```\n\nThis method returns the first worksheet, or null if there are no worksheets.\n\n```cs\npublic Worksheet? GetWorksheet(string name)\n```\n\nThis method returns the worksheet with the specified name.\n\n```cs\npublic Worksheet CreateWorksheet(string name)\n```\n\nCreates a new worksheet and gives it the specified name.\n\n```cs\npublic void RenameWorksheet(Worksheet worksheet, string name)\n```\n\nRenames the given worksheet with the specified name.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftcircuits%2Fsoftcircuits.spreadsheetbuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftcircuits%2Fsoftcircuits.spreadsheetbuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftcircuits%2Fsoftcircuits.spreadsheetbuilder/lists"}