OdfKit 是純受控 C# / .NET 的 ODF (OpenDocument Format) 文件處理 SDK。它讓應用程式在不啟動 LibreOffice、OpenOffice、UNO、Microsoft Office 或 Java 的情況下，建立、載入、保存、驗證並保留 ODF 文件內容。
目前預設新建文件為 ODF 1.4。核心程式庫與可封裝擴充套件採
net10.0 與 netstandard2.0 雙目標框架；CLI 與測試專案目前覆蓋
net10.0 與 net8.0。
AI 產製聲明 本專案目前公開之原始碼、文件、範例、測試與相關內容，均為使用 AI 工具撰寫、整理或產製。
| 面向 | 說明 |
|---|---|
| 核心能力 | 支援 24 種主要 ODF extension 的格式偵測、最小建立、載入、保存、驗證與來回讀寫 |
| 高階 API | ODT、ODS、ODP、ODG 提供常用建立與編輯 API；ODC、ODF、ODI、ODB 提供可用的高階入口 |
| 資料庫互通 | 透過 ObjectDataReader<T> 將任意物件序列或 Entity Framework Core 查詢投影以 DbDataReader 邊界串流匯出／匯入，不綁定特定 ORM 或資料庫 provider |
| 相容性 | Package 與 DOM 來回讀寫會保留未知封裝專案、foreign XML、processing instructions、comments 與 prefix |
| 驗證 | 內建 package / flat XML 檢查、ODF 1.4 schema metadata、profile rules、positive / negative corpus 測試 |
| 在地化 | 透過 OdfLocalizer 提供多語系訊息與文化回退機制 |
| 工具鏈 | CLI 提供 validate、validate-corpus、info、metadata、sanitize、typed-dom-coverage、convert-flat、convert-csv 與 pack |
完整支援範圍請見 ODF 格式支援矩陣、 ODF Profile 來源、 LibreOffice 互通矩陣 與 i18n 與在地化。
| 類別 | 內容 | 典型用途 |
|---|---|---|
| 核心 SDK | OdfKit |
ODF 文件建立、載入、保存、驗證、來回讀寫 |
| 匯出與轉換擴充 | OdfKit.Extensions.Html、OdfKit.Extensions.Pdf、OdfKit.Extensions.Ooxml |
HTML / Markdown / RTF、PDF、DOCX / XLSX 互通 |
| 渲染與資料擴充 | OdfKit.Extensions.Imaging、OdfKit.Extensions.Rendering、OdfKit.Extensions.Rdf、OdfKit.Extensions.Collaboration |
影像渲染、LibreOffice 後端渲染、RDF、協作操作匯出 |
| 工具 | OdfKit.Cli、samples、測試與 corpus 工具 |
自動化驗證、批次轉檔、範例與工程驗證 |
套件挑選與相依說明請見 套件目錄與選型指南； 工具與範例導覽請見 tools/README.md 與 samples/README.md。
原始碼整合（主要方式）：
dotnet build
dotnet testProjectReference 整合：
dotnet add YourApp.csproj reference path\to\OdfKit\OdfKit\OdfKit.csproj版本原則與交付方式請見 版本與交付資訊。
using OdfKit.Text;
using TextDocument document = TextDocument.Create();
document.Body.Headings.Add("報告", 1);
document.Body.Paragraphs.Add("這是一份 ODF 文字文件。");
document.Save("report.odt");using OdfKit.Formula;
using FormulaDocument formula = FormulaDocument.Builder()
.WithIdentifierEquation("F", "ma")
.Build();
formula.Save("equation.odf");SpreadsheetDocument、PresentationDocument、DrawingDocument、ChartDocument、
ImageDocument 與 DatabaseDocument 也提供短名 facade。完整範例請見
samples/README.md 與 docs/cookbook.md。
dotnet run --project tools/OdfKit.Cli --framework net10.0 -- validate report.odt完整入門流程、CLI 範例與後續文件請見 docs/getting-started.md、docs/core-quickstart.md 與 samples/README.md。
OdfKit 的文件已依常用技術文件結構重整為「評估 → 導入 → 營運」導覽：
| 階段 | 建議先讀 | 內容 |
|---|---|---|
| 評估 | 文件中心 | 文件入口、閱讀路徑與角色導覽 |
| 選型 | 套件目錄與選型指南 | 核心套件、擴充套件、工具與情境對照 |
| 導入 | 快速開始 | 安裝模式、第一個文件、CLI、下一步 |
| SDK 路徑 | 核心 SDK 快速開始、API 表面分層 | 核心純受控路徑、API 分層與新增 API 放置準則 |
| 相容性 | NuGet 相容矩陣 | 套件清單、目標框架、安裝策略 |
| 功能邊界 | ODF 格式支援矩陣 | 支援狀態、測試證據、已知缺口 |
| 規則與語系 | ODF Profile 來源、i18n 與在地化 | 內建 Profile、語系字典與訊息回退 |
| 版本與交付 | 版本與交付資訊 | 交付管道、版本原則與安裝參考 |
| 效能 | 效能基準線 | 基準測試回歸關卡、穩定量測設定檔與報告產生方式 |
更細部的規格、互通、測試與 corpus 文件，請由 docs/index.md 進入。
- 目前主要交付管道為 GitHub 原始碼 與 GitHub Release 資產， 未發佈至 nuget.org。
- OdfKit 目前仍屬
0.x階段；相容性承諾與破壞性變更將記錄於 CHANGELOG。 - 版本、交付與安裝參考已整理於 docs/version-delivery.md。
| 適合 | 較不適合 |
|---|---|
| 需以 ODF 為主格式 建立、編輯、驗證或批次匯出（含 ODS 串流） | 客戶只要 XLSX／DOCX、無 ODF 政策要求 → 優先 ClosedXML、MiniExcel、Open XML SDK 等 |
| 伺服器／容器需 純受控、不安裝 LibreOffice 即可處理 ODF 封裝 | 需要 高保真物理分頁、列印金標 PDF → 使用 LibreOffice 後端或商用渲染庫 |
| 需要 package 級 round-trip、foreign 內容保留、profile／corpus 驗證閘門 | 需要 完整試算表重算／樞紐引擎 或企業級 侵權賠償契約 → 見 non-goals 與商用套件 |
| 開源可審計（CC0 + 第三方 NOTICE） | 需要 nuget.org 上長期 1.x 穩定承諾與 SLA → 目前仍為 0.x，請鎖定 commit／Release |
功能邊界與非目標見 ODF 格式支援矩陣、 UDX 非功能性目標。效能數字見 效能對比報告（跨格式參考，非服務等級承諾）。
- 高階 API 覆蓋度依格式不同而不同；請以
ODF 格式支援矩陣 與測試證據為準。
矩陣中的
complete代表文件定義的最低完成標準，不代表每一種格式的完整深度語意模型。 - Template、master 與 Flat XML 變體已具專屬 typed 文件類別與常用變體功能； 但其高階語意 API 仍以對應主格式為主，完整變體專屬物件模型不屬於目前承諾範圍。
OdfKit.Extensions.Rendering需本機 LibreOffice 或相容程序後端， 不屬於核心 OdfKit 的純受控路徑。- 目前主要交付為 GitHub 原始碼與 Release 資產，尚未發佈至 nuget.org。
OdfKit 專案原創程式碼採用 CC0-1.0 Universal。 第三方相依套件維持各自授權；再散布時請保留必要聲明，詳見 THIRD-PARTY-NOTICES.md。
複合授權、AI 產製聲明、clean-room 原則、貢獻者 DCO 與採用者盡職調查清單見 智慧財產與合規說明 與 provenance。本專案不是 OASIS 或 LibreOffice 官方產品。