HotXLS ドキュメント
ホーム 目次 XLSX Facade 概要

TXLSXWorkbook クラス

Excel 2007+ (.xlsx) ワークブックのトップレベルコンテナです。lxHandleX で宣言されています。TXLSXSheets コレクションを保持し、OOXML ワークブック、CSV/TSV インポート、OpenDocument Spreadsheet (.ods) の読み書きワークフローのための SaveAs / Open エントリポイントを提供します

宣言

type
  TXLSXFileFormat = (xlsxOpenXMLWorkbook, xlsxOpenDocumentSpreadsheet);

  TODSExportOptions = class
    constructor Create;
    property Generator: WideString;
    property IncludeCharts: Boolean;
    property IncludeImages: Boolean;
  end;

  TXLSXWorkbook = class
    constructor Create;
    destructor Destroy; override;
    function SaveAs(const FileName: WideString): Integer; overload;
    function SaveAs(const FileName: WideString; FileFormat: TXLSXFileFormat): Integer; overload;
    function SaveAs(Stream: TStream): Integer; overload;
    function SaveAs(Stream: TStream; FileFormat: TXLSXFileFormat): Integer; overload;
    function Open(const FileName: WideString): Integer; overload;
    function Open(const FileName: WideString; const Password: WideString): Integer; overload;
    function Open(Stream: TStream): Integer; overload;
    function OpenCSV(const FileName: WideString): Integer; overload;
    function OpenCSV(const FileName: WideString; ASeparator: WideChar;
      ADetectTypes: Boolean): Integer; overload;
    function OpenCSV(Stream: TStream): Integer; overload;
    function OpenCSV(Stream: TStream; ASeparator: WideChar;
      ADetectTypes: Boolean): Integer; overload;
    function OpenODS(const FileName: WideString): Integer; overload;
    function OpenODS(Stream: TStream): Integer; overload;
    function SaveAsODS(const FileName: WideString): Integer; overload;
    function SaveAsODS(Stream: TStream): Integer; overload;
    function SaveAsODS(const FileName: WideString; Options: TODSExportOptions): Integer; overload;
    function SaveAsODS(Stream: TStream; Options: TODSExportOptions): Integer; overload;
    function GetODSSheetNames(const FileName: WideString; AList: TStrings): Integer; overload;
    function GetODSSheetNames(Stream: TStream; AList: TStrings): Integer; overload;
    function GetSheetNames(const FileName: WideString; AList: TStrings): Integer; overload;
    function GetSheetNames(Stream: TStream; AList: TStrings): Integer; overload;
    function SaveAsCSV(const FileName: WideString): Integer; overload;
    function SaveAsCSV(const FileName: WideString; SheetIndex: Integer; Delimiter: WideChar): Integer; overload;
    function SaveAsCSV(Stream: TStream): Integer; overload;
    function SaveAsCSV(Stream: TStream; SheetIndex: Integer; Delimiter: WideChar): Integer; overload;
    function SaveAsHTML(const FileName: WideString): Integer; overload;
    function SaveAsHTML(const FileName: WideString; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsHTML(const FileName: WideString; SheetIndex: Integer): Integer; overload;
    function SaveAsHTML(const FileName: WideString; SheetIndex: Integer; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsHTML(Stream: TStream): Integer; overload;
    function SaveAsHTML(Stream: TStream; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsHTML(Stream: TStream; SheetIndex: Integer): Integer; overload;
    function SaveAsHTML(Stream: TStream; SheetIndex: Integer; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsRTF(const FileName: WideString): Integer; overload;
    function SaveAsRTF(const FileName: WideString; SheetIndex: Integer): Integer; overload;
    function SaveAsRTF(Stream: TStream): Integer; overload;
    function SaveAsRTF(Stream: TStream; SheetIndex: Integer): Integer; overload;
    // AES encryption (ECMA-376 Standard Encryption) write path.
    // OpenEncrypted still raises for encrypted packages.
    function SaveAsEncrypted(const FileName, APassword: WideString): Integer;
    function OpenEncrypted(const FileName, APassword: WideString): Integer;
    function CanReadEncrypted(const FileName: WideString): Boolean;
    function Calculate(const Formula: WideString): Variant;
    property OnUserFunction: TXLSUserFunctionEvent;
    property OnUserFunctionEx: TXLSUserFunctionExEvent;
    // Document properties (docProps/core.xml + docProps/app.xml).
    property Title, Author, Subject, Keywords, Description,
             Category, LastModifiedBy, Company,
             Application, AppVersion: WideString;
    property Created, Modified: TDateTime;
    // Workbook protection (16-bit legacy hash).
    procedure ProtectWorkbook; overload;
    procedure ProtectWorkbook(const APassword: WideString); overload;
    procedure ProtectWorkbook(const APassword: WideString; ALockStructure, ALockWindows: Boolean); overload;
    procedure UnProtectWorkbook;
    property IsWorkbookProtected: Boolean;
    property LockStructure, LockWindows: Boolean;
    // VBA project payload (round-trips byte-for-byte). Workbook is saved
    // with macro-enabled content type when HasVbaProject is True.
    procedure LoadVbaProjectFromFile(const AFileName: WideString);
    procedure ClearVbaProject;
    function HasVbaProject: Boolean;
    property VbaProjectDefined: Boolean;
    property VbaProject: AnsiString;
    property ParsedVBAProject: TXLSVBAProject;
    // Chart sheet helper — creates a sheet flagged IsChartSheet and
    // seeds Charts[0] with a default full-page anchor.
    function AddChartSheet(const AName: WideString;
      AChartType: TXLSXChartType; const ATitle: WideString): TXLSXWorksheet;
    // Streaming SaveAs path (TXLSWideStringBuilder + one sheet at a time).
    property StreamingWrite: Boolean;
    // Workbook-level collections.
    property ActiveSheet: Integer;
    property Minimized: Boolean;
    property WindowHidden: Boolean;
    property ShowHorizontalScroll: Boolean;
    property ShowVerticalScroll: Boolean;
    property ShowSheetTabs: Boolean;
    property XWindow: Integer;
    property YWindow: Integer;
    property WindowWidth: Integer;
    property WindowHeight: Integer;
    property TabRatio: Integer;
    property FirstSheet: Integer;
    property AutoFilterDateGrouping: Boolean;
    property Date1904: Boolean;
    property SourceFormat: TXLSXFileFormat;
    property IndexedColor[Index: Integer]: LongWord;
    function  HasCustomIndexedColor(Index: Integer): Boolean;
    function  CustomIndexedColorCount: Integer;
    procedure ResetIndexedColors;
    property Sheets: TXLSXSheets;
    property Fonts: TXLSXFonts;
    property Fills: TXLSXFills;
    property Borders: TXLSXBorders;
    property NumberFormats: TXLSXNumberFormats;
    property Alignments: TXLSXAlignments;
    property DefinedNames: TXLSXDefinedNames;
    property ExternalLinks: TXLSXExternalLinks;
  end;

メンバー

Sheets ワークシートコレクションです。TXLSXSheets を参照
Fonts ワークブックレベルのフォントパレットです。セルは TXLSXCell.FontIndex にこのコレクションへの 1 始まりインデックスを設定することでフォントを選択します。TXLSXFont / TXLSXFonts を参照
Fills ワークブックレベルのフィルパレットです。セルは TXLSXCell.FillIndex にこのコレクションへの 1 始まりインデックスを設定することでフィルを選択します。TXLSXFill / TXLSXFills を参照
Borders ワークブックレベルの罫線パレットです。セルは TXLSXCell.BorderIndex にこのコレクションへの 1 始まりインデックスを設定することで罫線を選択します。TXLSXBorder / TXLSXBorders を参照
NumberFormats ワークブックレベルのカスタム数値書式パレットです。セルは TXLSXCell.NumberFormatIndex にこのコレクションへの 1 始まりインデックスを設定することで書式を選択します TXLSXNumberFormat / TXLSXNumberFormats を参照
DefinedNames ワークブックレベルの名前付き範囲（ワークブックスコープまたはシートスコープ）です TXLSXDefinedName / TXLSXDefinedNames を参照
Calculate アクティブシートを対象に Excel 数式文字列をコンパイルして評価します。先頭の = も受け付けます。セル参照・範囲・参照セルに保存された数式・クロスシート参照・定義名範囲・サポートされているテキスト/日付/ワークデー/エンジニアリング・基数変換/ビット演算/統計/集計/数学関数が HotXLS 共有数式エンジンで評価されます。カスタムまたは未サポートの関数を処理するには OnUserFunction を参照
OnUserFunction, OnUserFunctionEx 数式がカスタムまたは未サポートの関数を呼び出したとき Calculate から使用されるコールバックです OnUserFunction / OnUserFunctionEx callback を参照
GetSheetNames(FileName, AList), GetSheetNames(Stream, AList) xl/workbook.xml を読み取り、ワークシートの XML を読み込まずにワークブック順でワークシート名を AList に追記します。ストリームオーバーロードは完全な XLSX パッケージストリームを要求します。読み取った名前数を返し、パッケージを開けない場合は -1 を返します
Alignments ワークブックレベルのセル配置パレットです。セルは TXLSXCell.AlignmentIndex にこのコレクションへの 1 始まりインデックスを設定することで配置を選択します TXLSXAlignment を参照
Document properties Title、Author、Subject、Keywords、Description、Category、LastModifiedBy、Company、Application、AppVersion、Created、Modified。いずれかを設定すると SaveAs 時に docProps/core.xml + docProps/app.xml に書き出されます（設定しない場合はワークブックに最小限のパーツセットが維持されます）
ProtectWorkbook / UnProtectWorkbook オプションの 16 ビットレガシーパスワードハッシュと LockStructure / LockWindows フラグを伴うワークブック保護のトグルです。xl/workbook.xml の <workbookProtection> として反映されます
LoadVbaProjectFromFile / VbaProject / HasVbaProject / VbaProjectDefined LoadVbaProjectFromFile は生の vbaProject.bin ペイロードをインポートします。VbaProject はそのバイト列を公開します。HasVbaProject と読み取り専用の VbaProjectDefined はどちらもペイロードの存在を返します。マクロを Excel で有効にするには .xlsm 拡張子で保存してください
ParsedVBAProject 現在の vbaProject.bin ペイロードの読み取り専用パースビューです。ペイロードが有効な OLE VBA ストレージである場合、モジュール名とソーステキストを公開する TXLSVBAProject を返します。それ以外の場合は nil を返します。生の VbaProject ペイロードが SaveAs/Open ラウンドトリップで使用される正式なバイト列です
AddChartSheet(Name, Type, Title) IsChartSheet = True にフラグされたワークシートを作成し、適切なデフォルトのフルページアンカーで Charts[0] を初期化します。SaveAs はこのようなシートを xl/chartsheets/sheetN.xml に書き出します TXLSXChart を参照
StreamingWrite True の場合、SaveAs はシートごとに WriteWorksheetXmlStreaming を使用します。シートの XML キャッシュを保持せず、すべてのシートが SST に追加された後に sharedStrings.xml を最後に出力します。行ごとの TXLSWideStringBuilder と組み合わせることで、大規模シートのメモリ消費を線形に抑えます。デフォルトは False（既存の動作）です
SaveAsEncrypted / OpenEncrypted / CanReadEncrypted ECMA-376 標準暗号化による書き込みサポートです。SaveAsEncrypted は空でないパスワードに対して AES-128 で保護された OLE Compound File コンテナを書き出します（利用可能な場合は AES-NI 高速化を使用し、そうでない場合はソフトウェアフォールバック）。暗号化されたファイルは Excel 2007 以降で保存時のパスワードを使って開けます。CanReadEncrypted は OLE2 マジックバイトを検出します。OpenEncrypted は暗号化されていないファイルに対して通常の Open にフォールバックしますが、復号サポートが実装されるまで暗号化パッケージに対しては EXlsxEncryptionNotImplemented を送出します
SaveAs(FileName) ワークブックを指定のファイルに書き出します。成功時は 1、失敗時は負の値を返します。シートがない場合はデフォルトの Sheet1 を追加してから書き出します
SaveAs(FileName, FileFormat) OOXML 出力には xlsxOpenXMLWorkbook、OpenDocument Spreadsheet (.ods) パッケージには xlsxOpenDocumentSpreadsheet を指定します。SaveAsODS は ODS パスの名前付きショートカットで、同じ出力形式にオプションの TODSExportOptions 制御を加えたものです
SaveAs(Stream) / SaveAs(Stream, FileFormat) ワークブックを任意の TStream に直接書き出します。FileFormat オーバーロードは xlsxOpenXMLWorkbook または xlsxOpenDocumentSpreadsheet を受け付けるため、インメモリの XLSX・ODS 生成や BLOB ストレージのパスに適しています。成功時は 1 を返します
Open(FileName) OOXML の .xlsx アーカイブを読み取り、Sheets コレクションをその内容で置き換えます。成功時は 1 を返します
Open(FileName, Password) 将来の暗号化 XLSX サポート向けに予約されています。現時点では Open(FileName) と同様に動作し、パスワードは無視されます
Open(Stream) TStream から OOXML の .xlsx アーカイブを読み取ります。成功時は 1 を返します
OpenCSV(FileName) / OpenCSV(Stream) CSV または TSV テキストをワークブックにインポートします。区切り文字の自動検出（,・;・タブ・パイプ）、BOM ベースの UTF-8/UTF-16 エンコーディング検出、RFC 4180 形式のクォートフィールド、ADetectTypes オーバーロードによるオプションの値型推定に対応しています。.csv または .tsv に対して Open(FileName) を呼び出すと自動的にこのインポータにルーティングされます OpenCSV メソッド を参照
OpenODS(FileName) / OpenODS(Stream) ファイルまたはストリームから OpenDocument Spreadsheet (.ods) パッケージをインポートします。シート名・スカラー値・キャッシュ済み数式結果・基本的な数式参照変換・繰り返し行/列/セル・結合範囲・リッチテキスト・ハイパーリンク・コメント・埋め込み画像・埋め込みグラフ・非表示行/列/シート・行の高さ・列の幅・継承/デフォルトスタイル・数値/日付/時刻/通貨/科学記数法/分数書式・セルおよびシートの保護状態・名前付き範囲・印刷範囲・手動改ページ・ペインの固定・AutoFilter 範囲・行/列アウトライングループ・ヘッダー/フッター・データ検証（プロンプト含む）・条件付き書式（数式/カラースケール/データバー含む）・シートタブの色を保持します。OpenFormula の完全なセマンティクス・ODS 保護キー・コメントのジオメトリ・高度なコメント書式・スプレッドシートコンテンツ外のパッケージ機能は変換されません
SaveAsODS(FileName) / SaveAsODS(Stream) ワークブックを有効な OpenDocument Spreadsheet パッケージとして保存します。ODF の mimetype・マニフェスト・メタデータ・スタイル・ワークシートコンテンツを直接書き出し、HotXLS ワークブックモデルで表現される範囲で型付き値・数式・スタイル・リッチテキスト・寸法・結合・ハイパーリンク・画像・グラフ・名前付き範囲・AutoFilter 範囲・条件付き書式・データ検証・ペインの固定・ページ設定・ヘッダー/フッター・印刷範囲・手動改ページ・アウトライングループ・タブの色・シートの表示状態を維持します
TODSExportOptions ODS エクスポートを制御します。Generator は meta.xml の meta:generator 値を上書きします（空の場合は HotXLS 組み込みのジェネレータ文字列を使用）。IncludeCharts と IncludeImages はデフォルト True で、False にすると対応する描画フレーム・パッケージパーツ・マニフェストエントリを一括削除し、孤立したグラフや画像参照のない出力を生成します。呼び出し側がオプションインスタンスを所有し、解放する必要があります
GetODSSheetNames(FileName, AList), GetODSSheetNames(Stream, AList) ワークブックをリセットまたは読み込まずに、content.xml から ODS のテーブル名だけを AList に読み取ります。ファイルピッカーやインポートワークフローでワークブックを読み込む前にシート名が必要な場合に使用してください
SaveAsCSV overloads 4 つのオーバーロード（FileName または Stream × アクティブシートデフォルト / 明示的な SheetIndex + Delimiter）があります。選択したシートを BOM 付き UTF-8 CSV として書き出します。日付値は yyyy-mm-dd hh:nn:ss 形式でレンダリングされます。数式セルはエクスポート前に計算され、計算できない場合にのみ数式テキストが使用されます。成功時は 0 を返します
SaveAsHTML overloads オプションオーバーロードは TXLSXHtmlExportOptions を受け付けます（Title・WriteDocument・IncludeStyles・IncludeBOM・TableClass）。テーブルフラグメントには WriteDocument を False に設定し、既存の UTF-8 レスポンスに埋め込む場合は IncludeBOM を False に設定します。エクスポート出力はセルのハイパーリンクを <a> アンカーとして、アンカー画像をインライン data: URI として保持します。セルコメントは <td> の title 属性としてエスケープして出力されます。IncludeStyles が有効の場合、明示的な ColWidth は <col> 幅として、RowHeight は <tr> の height スタイルとして出力されます。リッチテキストのセル実行は <span> 要素としてインラインスタイルで出力されます。セルの罫線は CSS の border ルールとして出力されます。RowHidden / ColHidden でマークされた非表示行・列と幅ゼロの列は生成されるテーブルからスキップされます。垂直配置設定は CSS の vertical-align ルールとして出力されます
SaveAsRTF overloads 4 つのオーバーロード（FileName または Stream × アクティブシートデフォルト / 明示的な SheetIndex）があります。選択したシートをプレーンテーブル付きの RTF 1.6 ドキュメントとして書き出します。列幅は ColWidth データから取得されます（1 文字単位 ≈ 96 twips、デフォルト 809 twips）。セルごとの太字・イタリック・フォントサイズが適用されます。非 ASCII 文字は符号付き 16 ビットの \uN? RTF Unicode エスケープとしてエンコードされます。結合セルはスパンされません。成功時は 0 を返します
ActiveSheet アクティブ（選択中）シートの 1 始まりインデックスです（なければ 0）。クラシック XLS エンジンの ActiveSheetIndex と一致します。SaveAs はワークブックビューオプションを出力する必要がある場合に <workbookView> の activeTab="N" を書き込み（OOXML の activeTab 属性自体は 0 始まりのまま）、対応するシートに tabSelected="1" をマークします
Minimized / WindowHidden / ShowHorizontalScroll / ShowVerticalScroll <workbookView> に書き込まれるワークブックウィンドウのクロームフラグです。Minimized は minimized="1"、WindowHidden は visibility="hidden" を書き込みます。ShowHorizontalScroll / ShowVerticalScroll はワークブックのスクロールバーを表示または非表示にします。Open は 4 つの値すべてをラウンドトリップします
XWindow / YWindow / WindowWidth / WindowHeight <workbookView> に書き込まれるワークブックウィンドウのジオメトリです。XWindow と YWindow はウィンドウの原点を、WindowWidth と WindowHeight はそのサイズを格納します。値は 0..65535 にクランプされ、読み込み時にラウンドトリップします
ShowSheetTabs / TabRatio / FirstSheet / AutoFilterDateGrouping <workbookView> に書き込まれるワークブックウィンドウのビューオプションです。ShowSheetTabs はシートタブバーを表示または非表示にします。TabRatio はタブバーとスクロールバーの幅の比率を制御し 0..1000 にクランプされます。FirstSheet は最初の表示タブを 0 始まりのシートインデックスで指定し既存のシートにクランプされます。AutoFilterDateGrouping は AutoFilter ドロップダウンでの Excel の日付グループ化を制御します。Open は 4 つの値すべてをラウンドトリップします
Date1904 ワークブックの日付基準です。False（デフォルト）は Windows 1900 エポック、True は Mac 1904 エポック（すべての日付シリアルを 1462 日シフト）です。TDateTime セル値を代入する前に設定することで、Excel が同じカレンダー日付を表示します
SourceFormat 直近の成功した Open または OpenODS 呼び出しで読み込まれたパッケージファミリを返します。XLSX には xlsxOpenXMLWorkbook、ODS には xlsxOpenDocumentSpreadsheet を返します。新規作成したワークブックはファイルを開くまで xlsxOpenXMLWorkbook を返します
IndexedColor[Index] 指定した OOXML インデックスカラーパレットスロット（0..63）の ARGB 値です。読み取り時はユーザーが上書きした値があればそれを、なければ組み込みの OOXML デフォルト（XlsxDefaultIndexedPalette）を返します。書き込み時はスロット N を上書きし、SaveAs は 64 スロット全体の <indexedColors> ブロックを出力します
HasCustomIndexedColor / CustomIndexedColorCount / ResetIndexedColors HasCustomIndexedColor(N) はスロット N が明示的に上書きされている場合に True を返します。CustomIndexedColorCount は上書きされたスロットの数を返します（0 の場合 SaveAs は <colors> ブロックを出力しません）。ResetIndexedColors はすべての上書きを破棄してデフォルトパレットを復元します
ExternalLinks 外部ワークブック参照のコレクションです。各 TXLSXExternalLink エントリはターゲット URL と SheetNames リストを保持します。SaveAs は xl/workbook.xml の <externalReferences> ブロックと対応する xl/externalLinks/ パーツを出力します。Open はターゲットと SheetNames をラウンドトリップします。<sheetDataSet> 内のキャッシュ済みセル値は保持されません

使用例

ワークブックの書き込みと再オープン: 
uses lxHandleX;

var
  wb: TXLSXWorkbook;
begin
  wb := TXLSXWorkbook.Create;
  try
    wb.Sheets.Add('Demo').Cells.Item[1, 1].Value := 'Hello';
    wb.SaveAs('demo.xlsx');

    wb.Open('demo.xlsx');
    ShowMessage(wb.Sheets[0].Cells.Item[1, 1].Value);
  finally
    wb.Free;
  end;
end;

関連項目