はじめに

Aspose.Cells FOSS for C++ は 2 つの層で構成されています。コードが主に触れる層はファサードであり、Workbook、Worksheet、Cell、Style が含まれ、これらは本プラットフォームの発表および機能記事で取り上げられています。その下に第2層があり、Aspose::Cells_FOSS::Core 名前空間にあり、プレーンなデータレコード—WorkbookModel、WorksheetModel、CellRecord、StyleValue、および約 4 ダースの関連する *Model と *Value タイプで構成されています。これらのレコードは、実際に解析されたスプレッドシートの状態を保持します：CellAddress をキーとしたセル値、StyleValue としてのスタイル属性、ブックおよびシートの設定、ページ設定、フィルタ、ロード診断情報です。ファサードクラスは自身で状態を保持するのではなく、この層から読み書きします。

2 つの層の間の橋渡しは明示的で公開されています。Workbook::GetModel() は Core::WorkbookModel を返し、Worksheet::GetModel() は Core::WorksheetModel を返し、Style::ToCore() / Style::FromCore() は可変の Style を Core::StyleValue に相互変換します。DocumentProperties::GetModel() と ExtendedDocumentProperties::GetModel() もドキュメントメタデータに対して同様の変換を行います。利用者がこの層に直接アクセスするケースは、日常的なセル編集 API よりも限定的です：ブックのロードまたは保存時に記録された DiagnosticBag を検査したり、ブックレベルの StyleRepository を通じてスタイルを正規化したり、Cell / Row ラッパーオブジェクトではなく、プレーンオールドデータのセルおよび行レコードを直接操作したりします。

ここで説明したすべては、C++ 用 Aspose.Cells FOSS の他の部分と同じ MIT ライセンスの依存関係なしソースツリーに含まれており、CMake でビルドされ、事前構築バイナリではなくヘッダーとソースとして提供されます。まだファサード API を使用したことがない場合は、まず Workbook/Worksheet/Cell 機能に関する記事から始めてください — 本記事はその前提を踏まえ、下層に焦点を当てています。

含まれるもの

Workbook と Worksheet のモデルツリー

Core::WorkbookModel はルートレコードです。GetWorksheets() は std::deque<WorksheetModel> を返し、GetSettings() は WorkbookSettingsModel、GetProperties() は WorkbookPropertiesModel、GetDocumentProperties() は DocumentPropertiesModel、GetDiagnostics() は DiagnosticBag、GetStyles() は StyleRepository、GetSharedStrings() は SharedStringRepository、そして GetDefaultStyle() / SetDefaultStyle() は StyleValue を返します。また、GetDefinedNames() からの GetActiveSheetIndex() と std::vector<DefinedNameModel> も追跡します。Workbook::GetModel() はこのレコードへのエントリーポイントです。

Core::WorksheetModelは、Worksheet::GetModel()を通じてアクセスされ、セルはstd::unordered_map<CellAddress, CellRecord>としてGetCells()を介して、行はstd::unordered_map<int, RowModel>としてGetRows()を介して、列範囲はstd::vector<ColumnRangeModel>としてGetColumns()を介して、結合範囲はstd::vector<MergeRegion>としてGetMergeRegions()を介して格納されます。また、GetHyperlinks()、GetValidations()、GetConditionalFormattings()、GetPageSetup()、GetView()、GetProtection()、GetAutoFilter()、GetTabColor()、およびGetVisibility()（SheetVisibility値：Visible、Hidden、またはVeryHidden）も保持しています。

CellAddressは、そのセルマップで使用されるハッシュ可能なキー型です。A1形式のテキストをゼロベースの行/列インデックスに変換し、逆変換も行います――これは、このクラスターの中でFOSSリポジトリに直接テストカバレッジがある数少ないクラスの一つです：

#include "aspose/cells_foss/core/CellAddress.h"

using namespace Aspose::Cells_FOSS;

Core::CellAddress parsed = Core::CellAddress::Parse("AB3");
// parsed.GetRowIndex()    == 2    (zero-based row index)
// parsed.GetColumnIndex() == 27   (zero-based column index)
// parsed.ToString()       == "AB3"

CellRecordは、セルのCellValue、CellValueKind、オプションの数式文字列、StyleValue、および実際に書き込まれたセルと、行または列のデフォルトが触れたために存在するだけのセルとを区別するGetIsExplicitlyStored()フラグを保持します。RowModelはオプションの高さ、非表示フラグ、オプションのスタイルインデックスを持ち、ColumnRangeModelは同じ三つに加えて適用される最小/最大列スパンを保持します。MergeRegionは単純な「最初の行／最初の列／総行数／総列数」矩形です。

スタイルデータをプレーン値として

StyleValueは、変更可能なStyleファサードに対するCore対応物です――Style::ToCore()はStyleをStyleValueに変換し、Style::FromCore()はStyleからStyleを構築します。これらはGetFont()（FontValue）、GetPattern()（FillPatternKind）、GetForegroundColor() / GetBackgroundColor()（ColorValue）、GetBorders()（BordersValue）、GetAlignment()（AlignmentValue）、GetProtection()（ProtectionValue）およびGetNumberFormat()（NumberFormatValue）をグループ化し、さらに静的なStyleValue::Default()とClone()を含みます。FontValueはFontの各フィールド、すなわち name、size、bold、italic、underline、strike-through、そしてColorValueを鏡のように映し出します。ColorValue自体はプレーンなARGBタプル（GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()）であり、ファサードのColorクラスとは異なりFromArgb()スタイルのファクトリを持たないため、ColorValueは通常既存のスタイルから取得され、直接構築されることはありません。

BordersValueは、左、右、上、下、斜めの5つのBorderSideValueメンバーを保持し、各メンバーはBorderStyle列挙値とColorValueを組み合わせます。AlignmentValueは水平および垂直の配置、テキストの折り返し、インデントレベル、テキストの回転、縮小表示、そして読み順をモデル化します。ProtectionValueとNumberFormatValueはセル保護フラグと、Styleが公開する数値フォーマットID/カスタム文字列ペアを支えます。

StyleRepositoryは、WorkbookModel::GetStyles()を通じてアクセスされ、Normalize(style) -> StyleValueという単一の操作を公開します。ワークブックは、読み込みや保存時に同等のスタイルを内部化し、同一のStyleValueレコードを重複させないように内部で使用します――現在のAPIの表面では、インデックスベースの検索を行う汎用スタイルキャッシュではありません。

ドキュメントプロパティとワークブックレベルの設定

DocumentPropertiesModel は GetCore() をグループ化します（CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status, および created/modified タイムスタンプ）および GetExtended()（ExtendedDocumentPropertiesModel: application, app version, company, manager, doc security, hyperlink base, および scale-crop / links-up-to-date / shared-doc フラグ）。DocumentProperties::GetModel() と ExtendedDocumentProperties::GetModel() はファサードクラスからこれらのレコードへのブリッジです。

WorkbookPropertiesModel は WorkbookProperties をミラーします ― コード名、show-objects、filter privacy、backup-file、関連フラグ ― そして WorkbookProtectionModel（lock structure/windows/revision、workbook と revisions パスワード）、WorkbookViewModel（ウィンドウ位置とサイズ、最初に表示されるシート、スクロールバーとシートタブの表示、タブ比率、最小化状態、自動フィルタの日付グルーピング）、および CalculationPropertiesModel（計算モード、反復設定、フル精度、同時計算）をネストします。WorkbookSettingsModel は DateSystem 値（Windows1900 または Mac1904）と表示カルチャを保持し、これは WorkbookSettings::GetDate1904() / GetCulture() のモデルレベルの対応物です。このグループのほとんどの *Model タイプは CopyFrom(source) と HasStoredState() を公開し、シリアライザはそれらを使用して明示的に設定された値と未設定のデフォルトを区別した上で XML を書き込みます。

ワークシート機能モデル

WorksheetProtectionModel は WorksheetProtection フィールドをフィールドごとにミラーし、保存されたパスワードフィールド（GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount()）を追加しますが、ファサード WorksheetProtection はそれらを直接表面化しません。WorksheetViewModel はグリッドライン、ヘッダー、ゼロ表示、右から左へのレイアウト、ズームスケールを保持します。PageSetupModel は PageMarginsModel（左/右/上/下/ヘッダー/フッターマージンを倍精度で表す）と PrintOptionsModel（グリッドライン、見出し、水平・垂直のセンタリング）と HeaderFooterModel（左/中央/右のヘッダーおよびフッターテキスト）をネストし、紙サイズ、向き、スケール、幅/高さに合わせてフィット、印刷領域、印刷タイトル行/列、ページ区切りベクトルとともに保持します。

AutoFilterModel は範囲文字列、std::vector<FilterColumnModel>、および AutoFilterSortStateModel を保持します。FilterColumnModel はさらに AutoFilterColorFilterModel、AutoFilterDynamicFilterModel、AutoFilterTop10Model をネストし、フィルタ値文字列のプレーンリストと std::vector<AutoFilterCustomFilterModel> を追加します。ConditionalFormattingModel は std::vector<CellArea> と std::vector<FormatConditionModel> をペアにし、各条件はそのタイプ、演算子、数式、カラースケール/データバー/アイコンセットフィールド、そして結果の書式用 StyleValue を保持します。ValidationModel と HyperlinkModel は Validation と Hyperlink ファサードをプレーンレコードとしてミラーし、DefinedNameModel は DefinedName をミラーします。SheetVisibility は Worksheet::GetVisibilityType() の背後にあるモデル層列挙型です。

これらのレコードが裏付けるファサード機能のうち、特に AutoFilter と ConditionalFormattingCollection は、製品ドキュメントで本リリースで依然としてアクティブに開発中であると記載されています。上記の構造を、モデルとシリアライザが構築されている構造的ターゲットとして扱い、現在保存されたワークブックを介してすべてのフィールドが往復できることの保証とはみなさないでください。

診断と共有状態

DiagnosticBag は WorkbookModel::GetDiagnostics() 経由で到達でき、DiagnosticEntry レコードを収集します ― 各レコードは GetCode()、GetSeverity()（DiagnosticSeverity: Warning, Recoverable, または LossyRecoverable）、GetMessage()、GetRepairApplied() フラグ、そして GetDataLossRisk() フラグを持ち、ワークブックが解析またはシリアライズされる間に生成されます。これは Workbook::GetLoadDiagnostics() と並行して実行され、ファサードレベルの LoadDiagnostics / LoadIssue タイプは同じ DiagnosticSeverity 列挙型を共有します。生のモデルレコードが必要で LoadIssue ラッパーではなく、ワークブックモデル上の GetDiagnostics() を通じて取得します。

SharedStringRepository は xlsx の shared-strings テーブルを支えます: GetValues() はインターンされた文字列ベクタを返し、TryGetValue(index, value) はインデックスをテキストに戻し、Intern(value) はエントリを追加または再利用します — これは SaveOptions::SetUseSharedStrings(true) が設定されているときに内部で使用されます。DateSerialConverter は DateTime と Excel がセルに格納する OLE スタイルのシリアル番号との間を変換し、DateSystem を受け取って 1900 年ベースと 1904 年ベースのブックが同じ暦日付にデコードされるようにします。

クイックスタート

ライブラリをサブディレクトリとして CMake プロジェクトに追加し、ライブラリが定義するターゲットをリンクします:

add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)
target_link_libraries(MyApp PRIVATE Aspose.Cells.Foss.Cpp)

以下の例はファサードを介してセルを書き込み、続いて基礎となるモデルにアクセスして診断バッグと CellAddress パースを取得します — これは WorksheetModel::GetCells() が内部でセルマップのキー付けに使用するのと同じ操作です:

#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
#include "aspose/cells_foss/Cell.h"
#include "aspose/cells_foss/core/CellAddress.h"
#include <iostream>

using namespace Aspose::Cells_FOSS;

int main() {
    Workbook workbook;
    Worksheet& sheet = workbook.GetWorksheets()[0];
    sheet.SetName("Report");
    sheet.GetCells()["A1"].PutValue("Total");
    workbook.Save("report.xlsx");

    Core::CellAddress address = Core::CellAddress::Parse("A1");
    std::cout << "Row: " << address.GetRowIndex()
              << " Column: " << address.GetColumnIndex() << "\n";

    for (const auto& entry : workbook.GetModel().GetDiagnostics().GetEntries()) {
        std::cout << "Diagnostic: " << entry.GetMessage() << "\n";
    }

    return 0;
}

サポートされているフォーマット

フォーマット拡張子読み取り書き込み
XLSX.xlsx✓✓

ここで説明するモデル層は、xlsx リーダーとライターが操作するインメモリ表現です; それ自体はライブラリの他の部分がサポートする Xlsx のインポート/エクスポート以外の追加ファイル形式には結び付けられていません。

オープンソースとライセンス

Aspose.Cells FOSS for C++ は MIT ライセンスです。この記事で参照されている Aspose::Cells_FOSS::Core モデルヘッダーを含むソースコードは GitHub にあります; 商用利用、改変、再配布が許可されています。

スタートガイド

関連リソース