บทนำ

Aspose.Cells FOSS สำหรับ C++ ถูกสร้างเป็นสองชั้น ชั้นที่โค้ดส่วนใหญ่สัมผัสคือเฟซาด: Workbook, Worksheet, Cell และ Style, ซึ่งเป็นสิ่งที่ประกาศและโพสต์ฟีเจอร์สำหรับแพลตฟอร์มนี้ครอบคลุม ด้านล่างมีชั้นที่สองใน namespace Aspose::Cells_FOSS::Core, ประกอบด้วยบันทึกข้อมูลธรรมดา — WorkbookModel, WorksheetModel, CellRecord, StyleValue, และประมาณสี่สิบประเภทที่เกี่ยวข้องของ *Model และ *Value. บันทึกเหล่านี้เก็บสถานะสเปรดชีตที่ถูกแปลงแล้วจริงๆ: ค่าของเซลล์ที่ระบุด้วย CellAddress, แอตทริบิวต์สไตล์เป็น StyleValue, การตั้งค่าเวิร์กบุ๊กและเวิร์กชีต, การตั้งค่าหน้ากระดาษ, ตัวกรอง, และการวินิจฉัยการโหลด. คลาสเฟซาดอ่านและเขียนกับชั้นนี้แทนที่จะเก็บสถานะด้วยตนเอง.

การเชื่อมระหว่างสองชั้นเป็นแบบชัดเจนและสาธารณะ Workbook::GetModel() คืนค่า Core::WorkbookModel, Worksheet::GetModel() คืนค่า Core::WorksheetModel, และ Style::ToCore() / Style::FromCore() แปลง Style ที่สามารถแก้ไขได้ ไปยังและจาก Core::StyleValue. DocumentProperties::GetModel() และ ExtendedDocumentProperties::GetModel() ทำเช่นเดียวกันสำหรับเมตาดาต้าเอกสาร ผู้ใช้จะเข้าถึงชั้นนี้โดยตรงในกรณีที่แคบกว่า API การแก้ไขเซลล์ประจำวัน: ตรวจสอบ DiagnosticBag ที่บันทึกขณะโหลดหรือบันทึกเวิร์กบุ๊ก, ทำให้สไตล์เป็นมาตรฐานผ่าน StyleRepository ระดับเวิร์กบุ๊ก, หรือทำงานกับบันทึกเซลล์และแถวแบบ plain-old-data โดยตรงแทนวัตถุหุ้ม Cell / Row.

ทุกอย่างที่อธิบายไว้ที่นี่จัดส่งในต้นไม้ซอร์สเดียวกันที่มีสัญญาอนุญาต MIT, ไม่มีการพึ่งพาอื่น ๆ เช่นเดียวกับส่วนที่เหลือของ Aspose.Cells FOSS สำหรับ C++, สร้างด้วย 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. มันยังติดตาม GetActiveSheetIndex() และ std::vector<DefinedNameModel> จาก GetDefinedNames(). 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 คือคู่ตรง Core ของเฟซาดที่เปลี่ยนแปลงได้ Style — Style::ToCore() แปลง Style ให้เป็นหนึ่ง, และ Style::FromCore() สร้าง 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 มีสมาชิก BorderSideValue จำนวนห้า — left, right, top, bottom, และ diagonal — แต่ละคู่ค่าตัวนับ BorderStyle กับ ColorValue. AlignmentValue จำลองการจัดแนวแนวนอนและแนวตั้ง, การตัดบรรทัด, ระดับการเยื้อง, การหมุนข้อความ, การย่อให้พอดี, และลำดับการอ่าน. ProtectionValue และ NumberFormatValue รองรับแฟล็กการปกป้องเซลล์และคู่ id/สตริงกำหนดรูปแบบตัวเลขที่ Style แสดงออก.

StyleRepository, ที่เข้าถึงผ่าน WorkbookModel::GetStyles(), เปิดเผยการดำเนินการหนึ่ง: Normalize(style) -> StyleValue. Workbook ใช้มันภายในขณะโหลดและบันทึกเพื่อทำให้สไตล์ที่เทียบเท่าถูกเก็บภายในแทนการทำซ้ำบันทึก StyleValue ที่เหมือนกัน — มันไม่ใช่แคชสไตล์แบบทั่วไปที่มีการค้นหาโดยดัชนีในพื้นผิว API ปัจจุบัน.

คุณสมบัติเอกสารและการตั้งค่าระดับ Workbook

DocumentPropertiesModel กลุ่ม GetCore() (CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status, และ timestamps ของ 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() ทำหน้าที่เชื่อมระหว่างคลาส facade กับบันทึกเหล่านี้.

WorkbookPropertiesModel สะท้อน WorkbookProperties — code name, show-objects, filter privacy, backup-file, และแฟล็กที่เกี่ยวข้อง — และบรรจุ WorkbookProtectionModel (lock structure/windows/revision, workbook and revisions password), WorkbookViewModel (ตำแหน่งและขนาดหน้าต่าง, แผ่นแรกที่มองเห็น, การมองเห็น scroll-bar และ sheet-tab, อัตราส่วนแท็บ, สถานะ minimized, การจัดกลุ่มวันที่ของ auto-filter), และ CalculationPropertiesModel (โหมดการคำนวณ, การตั้งค่า iteration, full precision, concurrent calculation). WorkbookSettingsModel มีค่า DateSystem (Windows1900 หรือ Mac1904) และวัฒนธรรมการแสดงผล — ตัวเทียบระดับโมเดลของ WorkbookSettings::GetDate1904() / GetCulture(). ประเภท *Model ส่วนใหญ่ในกลุ่มนี้เปิดเผย CopyFrom(source) และ HasStoredState(), ซึ่ง serializer ใช้เพื่อแยกค่าที่ตั้งอย่างชัดเจนจากค่าเริ่มต้นที่ไม่ได้ตั้งก่อนเขียน XML.

โมเดลคุณลักษณะ Worksheet

WorksheetProtectionModel สะท้อนฟิลด์ WorksheetProtection ทีละฟิลด์และเพิ่มฟิลด์รหัสผ่านที่จัดเก็บ — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — ซึ่ง facade WorksheetProtection ไม่แสดงโดยตรง. WorksheetViewModel เก็บข้อมูลการมองเห็น grid-line, header, และ zero, การจัดวางแบบขวาไปซ้าย, และระดับการซูม. PageSetupModel บรรจุ PageMarginsModel (ขอบซ้าย/ขวา/บน/ล่าง/header/footer เป็นค่า double), PrintOptionsModel (grid lines, headings, การจัดกึ่งกลางแนวนอนและแนวตั้ง), และ HeaderFooterModel (ข้อความ header และ footer ซ้าย/กึ่งกลาง/ขวา), พร้อมกับขนาดกระดาษ, การวางแนว, สเกล, fit-to-width/height, พื้นที่พิมพ์, แถว/คอลัมน์หัวเรื่องพิมพ์, และเวกเตอร์การแบ่งหน้า.

AutoFilterModel เก็บสตริงช่วง, std::vector<FilterColumnModel>, และ AutoFilterSortStateModel. FilterColumnModel จะบรรจุ AutoFilterColorFilterModel, AutoFilterDynamicFilterModel, และ AutoFilterTop10Model, พร้อมรายการธรรมดาของสตริงค่าตัวกรองและ std::vector<AutoFilterCustomFilterModel>. ConditionalFormattingModel จับคู่ std::vector<CellArea> กับ std::vector<FormatConditionModel> — แต่ละเงื่อนไขมีประเภท, ตัวดำเนินการ, สูตร, ฟิลด์ color-scale/data-bar/icon-set, และ StyleValue สำหรับรูปแบบผลลัพธ์. ValidationModel และ HyperlinkModel สะท้อน facades Validation และ Hyperlink เป็นบันทึกธรรมดา, และ DefinedNameModel สะท้อน DefinedName. SheetVisibility คือ enum ระดับโมเดลที่อยู่เบื้องหลัง Worksheet::GetVisibilityType().

บางฟีเจอร์ของ facade ที่บันทึกเหล่านี้สนับสนุน — โดยเฉพาะ AutoFilter และ ConditionalFormattingCollection — ถูกระบุในเอกสารผลิตภัณฑ์ว่าอยู่ระหว่างการพัฒนาอย่างต่อเนื่องในรุ่นนี้. ให้ถือรูปแบบข้างต้นเป็นเป้าหมายเชิงโครงสร้างที่โมเดลและ serializer ถูกสร้างขึ้นรอบ ๆ แทนที่จะเป็นการรับประกันว่าทุกฟิลด์จะทำการ round-trip ผ่านเวิร์กบุ๊กที่บันทึกไว้ในวันนี้.

การวินิจฉัยและสถานะที่แชร์ร่วมกัน

DiagnosticBag ที่เข้าถึงผ่าน WorkbookModel::GetDiagnostics() รวบรวมบันทึก DiagnosticEntry — แต่ละบันทึกมี GetCode(), GetSeverity() (DiagnosticSeverity: Warning, Recoverable, หรือ LossyRecoverable), GetMessage(), ธง GetRepairApplied(), และธง GetDataLossRisk() — ซึ่งสร้างขึ้นระหว่างการพาร์สหรือซีเรียลไลซ์เวิร์กบุ๊ก. สิ่งนี้ทำงานคู่กับ Workbook::GetLoadDiagnostics(), ซึ่งประเภท LoadDiagnostics / LoadIssue ระดับ facade ใช้ enum DiagnosticSeverity เดียวกัน; โค้ดที่ต้องการบันทึกโมเดลดิบแทนการห่อ LoadIssue จะเข้าถึงผ่าน GetDiagnostics() บนโมเดลเวิร์กบุ๊ก.

SharedStringRepository รองรับตาราง shared-strings ของ xlsx: GetValues() คืนค่าเวกเตอร์สตริงที่ interned, TryGetValue(index, value) แปลงดัชนีกลับเป็นข้อความ, และ Intern(value) เพิ่มหรือใช้รายการที่มีอยู่แล้ว — ใช้ภายในเมื่อ SaveOptions::SetUseSharedStrings(true) ถูกตั้งค่า. DateSerialConverter แปลงระหว่าง DateTime กับหมายเลขซีเรียลแบบ OLE ที่ Excel เก็บในเซลล์, โดยรับ DateSystem เพื่อให้เวิร์กบุ๊กที่ใช้ระบบ 1900 และ 1904 แปลเป็นวันที่เดียวกันในปฏิทิน.

เริ่มต้นอย่างรวดเร็ว

เพิ่มไลบรารีไปยังโครงการ CMake เป็นซับไดเรกทอรีและลิงก์เป้าหมายที่มันกำหนดไว้:

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

ตัวอย่างด้านล่างเขียนเซลล์ผ่าน facade, จากนั้นเข้าถึงโมเดลพื้นฐานเพื่อรับ diagnostic bag และการวิเคราะห์ 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 สำหรับ C++ มีสัญญาอนุญาต MIT. โค้ดต้นฉบับ, รวมถึงหัวไฟล์โมเดล Aspose::Cells_FOSS::Core ที่อ้างอิงในโพสต์นี้, อยู่บน GitHub; การใช้เชิงพาณิชย์, การแก้ไข, และการแจกจ่ายใหม่ได้รับอนุญาต.

เริ่มต้น

แหล่งข้อมูลที่เกี่ยวข้อง