Pendahuluan
Aspose.Cells FOSS untuk C++ dibangun sebagai dua lapisan. Lapisan yang paling banyak disentuh kode adalah fasad: Workbook, Worksheet, Cell, dan Style, yang merupakan apa yang dibahas dalam pengumuman dan posting fitur untuk platform ini. Di bawahnya terdapat lapisan kedua, dalam namespace Aspose::Cells_FOSS::Core, yang terdiri dari rekaman data polos — WorkbookModel, WorksheetModel, CellRecord, StyleValue, dan kira-kira empat lusin tipe *Model dan *Value terkait. Rekaman ini menyimpan keadaan spreadsheet yang telah diurai: nilai sel yang diindeks oleh CellAddress, atribut gaya sebagai StyleValue, pengaturan workbook dan worksheet, pengaturan halaman, filter, dan diagnostik pemuatan. Kelas fasad membaca dari dan menulis ke lapisan ini alih-alih menyimpan keadaan sendiri.
Jembatan antara dua lapisan tersebut bersifat eksplisit dan publik. Workbook::GetModel() mengembalikan Core::WorkbookModel, Worksheet::GetModel() mengembalikan Core::WorksheetModel, dan Style::ToCore() / Style::FromCore() mengonversi Style yang dapat diubah ke dan dari Core::StyleValue. DocumentProperties::GetModel() dan ExtendedDocumentProperties::GetModel() melakukan hal yang sama untuk metadata dokumen. Konsumen akan mengakses lapisan ini secara langsung dalam kasus yang lebih sempit dibandingkan dengan API pengeditan sel sehari-hari: memeriksa DiagnosticBag yang tercatat saat workbook dimuat atau disimpan, menormalkan gaya melalui StyleRepository tingkat workbook, atau bekerja langsung dengan rekaman sel dan baris plain-old-data alih-alih objek pembungkus Cell / Row.
Semua yang dijelaskan di sini dikirim dalam pohon sumber yang sama berlisensi MIT, bebas ketergantungan, seperti sisanya dari Aspose.Cells FOSS untuk C++, dibangun dengan CMake dan disertakan sebagai header dan sumber alih-alih binary yang sudah dibangun sebelumnya. Jika Anda belum bekerja dengan fasad API, mulailah dengan posting fitur Workbook/Worksheet/Cell terlebih dahulu — posting ini mengasumsikan dasar tersebut dan fokus pada apa yang berada di bawahnya.
Apa yang Disertakan
Pohon Model Workbook dan Worksheet
Core::WorkbookModel adalah rekaman akar. GetWorksheets() mengembalikan std::deque<WorksheetModel>, GetSettings() WorkbookSettingsModel, GetProperties() WorkbookPropertiesModel, GetDocumentProperties() DocumentPropertiesModel, GetDiagnostics() DiagnosticBag, GetStyles() StyleRepository, GetSharedStrings() SharedStringRepository, dan GetDefaultStyle() / SetDefaultStyle() StyleValue. Ia juga melacak GetActiveSheetIndex() dan std::vector<DefinedNameModel> dari GetDefinedNames(). Workbook::GetModel() adalah titik masuk ke rekaman ini.
Core::WorksheetModel, yang diakses melalui Worksheet::GetModel(), menyimpan sel sebagai std::unordered_map<CellAddress, CellRecord> melalui GetCells(), baris sebagai std::unordered_map<int, RowModel> melalui GetRows(), rentang kolom sebagai std::vector<ColumnRangeModel> melalui GetColumns(), dan rentang gabungan sebagai std::vector<MergeRegion> melalui GetMergeRegions(). Itu juga membawa GetHyperlinks(), GetValidations(), GetConditionalFormattings(), GetPageSetup(), GetView(), GetProtection(), GetAutoFilter(), GetTabColor(), dan GetVisibility() (sebuah nilai SheetVisibility: Visible, Hidden, atau VeryHidden).
CellAddress adalah tipe kunci yang dapat di-hash yang digunakan untuk peta sel tersebut. Ia mengurai teks gaya A1 menjadi indeks baris/kolom berbasis nol dan kembali — ini adalah salah satu dari sedikit kelas dalam klaster ini yang memiliki cakupan tes langsung di repositori 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 menyimpan CellValue, CellValueKind sel, string formula opsional, sebuah StyleValue, dan sebuah flag GetIsExplicitlyStored() yang membedakan sel yang benar-benar ditulis dari yang hanya ada karena nilai default baris atau kolom menyentuhnya. RowModel membawa tinggi opsional, flag tersembunyi, dan indeks gaya opsional; ColumnRangeModel membawa tiga hal yang sama ditambah rentang kolom min/maks yang diterapkannya. MergeRegion adalah persegi panjang sederhana baris-pertama/kolom-pertama/jumlah-baris/jumlah-kolom.
Data Gaya sebagai Nilai Biasa
StyleValue adalah padanan Core untuk fasad Style yang dapat diubah — Style::ToCore() mengonversi sebuah Style menjadi satu, dan Style::FromCore() membangun sebuah Style darinya. Ia mengelompokkan GetFont() (FontValue), GetPattern() (FillPatternKind), GetForegroundColor() / GetBackgroundColor() (ColorValue), GetBorders() (BordersValue), GetAlignment() (AlignmentValue), GetProtection() (ProtectionValue), dan GetNumberFormat() (NumberFormatValue), plus sebuah StyleValue::Default() statis dan sebuah Clone(). FontValue mencerminkan bidang Font satu per satu: nama, ukuran, tebal, miring, garis bawah, coret, dan sebuah ColorValue. ColorValue sendiri adalah tuple ARGB sederhana (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()) — tidak seperti kelas fasad Color yang memiliki pabrik gaya FromArgb(), sehingga sebuah ColorValue biasanya didapatkan dari gaya yang sudah ada alih-alih dibuat secara langsung.
BordersValue menyimpan lima anggota BorderSideValue — kiri, kanan, atas, bawah, dan diagonal — masing-masing memadukan nilai enum BorderStyle dengan sebuah ColorValue. AlignmentValue memodelkan perataan horizontal dan vertikal, pembungkus teks, tingkat indentasi, rotasi teks, penyusutan-agar-muat, dan urutan baca. ProtectionValue dan NumberFormatValue mendukung flag perlindungan sel serta pasangan id format-angka/string-kustom yang diekspos oleh Style.
StyleRepository, yang diakses melalui WorkbookModel::GetStyles(), mengekspos satu operasi: Normalize(style) -> StyleValue. Workbook menggunakannya secara internal saat memuat dan menyimpan untuk mengintern gaya ekuivalen alih-alih menduplikasi catatan StyleValue yang identik — ini bukan cache gaya tujuan umum dengan pencarian berbasis indeks pada permukaan API saat ini.
Properti Dokumen dan Pengaturan Tingkat Workbook
DocumentPropertiesModel grup GetCore() (CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status, dan created/modified timestamps) dan GetExtended() (ExtendedDocumentPropertiesModel: application, app version, company, manager, doc security, hyperlink base, dan flag scale-crop / links-up-to-date / shared-doc). DocumentProperties::GetModel() dan ExtendedDocumentProperties::GetModel() menjembatani dari kelas facade ke record ini.
WorkbookPropertiesModel mencerminkan WorkbookProperties — code name, show-objects, filter privacy, backup-file, dan flag terkait — dan menampung WorkbookProtectionModel (lock structure/windows/revision, workbook and revisions password), WorkbookViewModel (window position and size, first visible sheet, scroll-bar and sheet-tab visibility, tab ratio, minimized state, auto-filter date grouping), serta CalculationPropertiesModel (calculation mode, iteration settings, full precision, concurrent calculation). WorkbookSettingsModel membawa nilai DateSystem (Windows1900 atau Mac1904) dan budaya tampilan — padanan tingkat model dari WorkbookSettings::GetDate1904() / GetCulture(). Sebagian besar tipe *Model dalam grup ini mengekspos CopyFrom(source) dan HasStoredState(), yang digunakan serializer untuk membedakan nilai yang ditetapkan secara eksplisit dari default yang belum diatur sebelum menulis XML.
Model Fitur Lembar Kerja
WorksheetProtectionModel mencerminkan bidang WorksheetProtection satu per satu dan menambahkan bidang password yang disimpan — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — yang tidak ditampilkan secara langsung oleh facade WorksheetProtection. WorksheetViewModel menyimpan visibilitas grid-line, header, dan zero, tata letak kanan-ke-kiri, serta skala zoom. PageSetupModel menampung PageMarginsModel (margin kiri/kanan/atas/bawah/header/footer sebagai double), PrintOptionsModel (garis kisi, heading, penjajaran horizontal dan vertikal), dan HeaderFooterModel (teks header dan footer kiri/tengah/kanan), bersamaan dengan ukuran kertas, orientasi, skala, cocok-lebar/tinggi, area cetak, baris/kolom judul cetak, dan vektor pemisah halaman.
AutoFilterModel menyimpan string rentang, sebuah std::vector<FilterColumnModel>, dan sebuah AutoFilterSortStateModel. FilterColumnModel selanjutnya menampung AutoFilterColorFilterModel, AutoFilterDynamicFilterModel, dan AutoFilterTop10Model, serta daftar sederhana string nilai filter dan sebuah std::vector<AutoFilterCustomFilterModel>. ConditionalFormattingModel memadukan std::vector<CellArea> dengan std::vector<FormatConditionModel> — setiap kondisi membawa tipe, operator, formula, bidang color-scale/data-bar/icon-set, dan sebuah StyleValue untuk format hasil. ValidationModel dan HyperlinkModel mencerminkan facade Validation dan Hyperlink sebagai record sederhana, dan DefinedNameModel mencerminkan DefinedName. SheetVisibility adalah enum lapisan model di belakang Worksheet::GetVisibilityType().
Beberapa fitur facade yang didukung oleh record ini — khususnya AutoFilter dan ConditionalFormattingCollection — disebutkan dalam dokumentasi produk sebagai masih dalam pengembangan aktif pada rilis ini. Anggaplah bentuk di atas sebagai target struktural yang menjadi dasar model dan serializer, bukan sebagai jaminan bahwa setiap bidang dapat melakukan round-trip melalui workbook yang disimpan saat ini.
Diagnostik dan Status Bersama
DiagnosticBag, yang dicapai melalui WorkbookModel::GetDiagnostics(), mengumpulkan record DiagnosticEntry — masing-masing dengan GetCode(), GetSeverity() (DiagnosticSeverity: Warning, Recoverable, atau LossyRecoverable), GetMessage(), flag GetRepairApplied(), dan flag GetDataLossRisk() — yang dihasilkan saat workbook diurai atau diserialisasi. Ini berjalan berdampingan dengan Workbook::GetLoadDiagnostics(), yang tipe LoadDiagnostics / LoadIssue pada level facade-nya berbagi enum DiagnosticSeverity yang sama; kode yang membutuhkan record model mentah alih-alih pembungkus LoadIssue mencapainya melalui GetDiagnostics() pada model workbook.
SharedStringRepository mendukung tabel shared-strings xlsx: GetValues() mengembalikan vektor string yang di-intern, TryGetValue(index, value) menyelesaikan indeks kembali ke teks, dan Intern(value) menambahkan atau menggunakan kembali entri — digunakan secara internal ketika SaveOptions::SetUseSharedStrings(true) diatur. DateSerialConverter mengkonversi antara DateTime dan nomor seri bergaya OLE yang disimpan Excel dalam sel, mengambil DateSystem sehingga buku kerja berbasis 1900 dan 1904 didekode ke tanggal kalender yang sama.
Mulai Cepat
Tambahkan pustaka ke proyek CMake sebagai subdirektori dan tautkan target yang didefinisikannya:
add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)
target_link_libraries(MyApp PRIVATE Aspose.Cells.Foss.Cpp)
Contoh di bawah menulis sel melalui facade, lalu mengakses model yang mendasari untuk mendapatkan kantong diagnostik dan parse CellAddress — operasi yang sama WorksheetModel::GetCells() gunakan secara internal untuk memberi kunci pada peta selnya:
#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;
}
Format yang Didukung
| Format | Ekstensi | Baca | Tulis |
|---|---|---|---|
| XLSX | .xlsx | ✓ | ✓ |
Lapisan model yang dijelaskan di sini adalah representasi dalam memori yang digunakan oleh pembaca dan penulis xlsx; lapisan ini tidak terikat pada format file tambahan apa pun selain impor/ekspor Xlsx yang didukung oleh bagian lain pustaka.
Sumber Terbuka & Lisensi
Aspose.Cells FOSS untuk C++ berlisensi MIT. Kode sumber, termasuk header model Aspose::Cells_FOSS::Core yang disebutkan dalam posting ini, berada di GitHub; penggunaan komersial, modifikasi, dan redistribusi diizinkan.
