داخل نموذج البيانات Aspose.Cells FOSS في C++ | File Format Processing Plugins for C# .NET Core

المقدمة

Aspose.Cells FOSS للـ C++ مبني على طبقتين. الطبقة التي يلمسها معظم الشيفرة هي الواجهة: Workbook، Worksheet، Cell، وStyle، وهي ما تغطيه إعلانات ومواضيع المميزات لهذا المنصّة. تحتها توجد الطبقة الثانية، في مساحة الأسماء 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 على مستوى المصنف، أو العمل مباشرةً مع سجلات الخلايا والصفوف ذات البيانات البسيطة بدلاً من كائنات الغلاف Cell / Row.

كل ما هو موصوف هنا يُوزَّع في شجرة المصدر نفسها المرخصة برخصة MIT وخالية من الاعتمادات، مثل باقي Aspose.Cells FOSS للـ C++، مبنية باستخدام CMake ومضمنة كملفات ترويسية ومصادر بدلاً من ملف ثنائي مُسبق البناء. إذا لم تكن قد عملت مع واجهة API بعد، ابدأ أولاً بمقال ميزات المصنف/الورقة/الخلية — هذا المقال يفترض تلك الأساسيات ويركز على ما يقع تحتها.

ما الذي يتضمنه

شجرة نموذج المصنف والورقة

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 حقلًا تلو الآخر: الاسم، الحجم، عريض، مائل، تحتي، شطب، وColorValue. ColorValue نفسه هو زوج ARGB بسيط (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()) — على عكس فئة الواجهة Color لا يمتلك مصنعًا بنمط FromArgb()، لذا عادةً ما يتم الحصول على ColorValue من نمط موجود بدلًا من إنشائه مباشرة.

BordersValue يحتوي على خمسة أعضاء BorderSideValue — اليسار، اليمين، الأعلى، الأسفل، والقطري — كلٌ يقرن قيمة تعداد BorderStyle مع ColorValue. AlignmentValue يُنمذج المحاذاة الأفقية والرؤية، لف النص، مستوى الإزاحة، دوران النص، تصغير ليتناسب، وترتيب القراءة. ProtectionValue وNumberFormatValue يدعمان علامات حماية الخلية وزوج معرّف تنسيق الأرقام/السلسلة المخصصة الذي يقدمه Style.

StyleRepository، يتم الوصول إليه عبر WorkbookModel::GetStyles()، يكشف عن عملية واحدة: Normalize(style) -> StyleValue. يستخدم المصنف ذلك داخليًا أثناء التحميل والحفظ لتوحيد الأنماط المكافئة بدلاً من تكرار سجلات StyleValue المتطابقة — وهو ليس ذاكرة تخزين مؤقتة للأنماط ذات غرض عام مع بحث قائم على الفهرس في سطح API الحالي.

خصائص المستند وإعدادات مستوى المصنف

DocumentPropertiesModel مجموعات GetCore() (CoreDocumentPropertiesModel: العنوان، الموضوع، المنشئ، الكلمات المفتاحية، الوصف، آخر تعديل بواسطة، المراجعة، الفئة، حالة المحتوى، وcreated/modified الطوابع الزمنية) وGetExtended() (ExtendedDocumentPropertiesModel: التطبيق، إصدار التطبيق، الشركة، المدير، أمان المستند، قاعدة الارتباط التشعبي، وعلامات scale-crop / links-up-to-date / shared-doc). DocumentProperties::GetModel() وExtendedDocumentProperties::GetModel() يربطان facade classes إلى هذه السجلات.

WorkbookPropertiesModel يعكس WorkbookProperties — code name، show-objects، filter privacy، backup-file، والعلامات المرتبطة — ويضمّن 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)، وCalculationPropertiesModel (calculation mode، iteration settings، full precision، concurrent calculation). WorkbookSettingsModel يحمل قيمة DateSystem (Windows1900 أو Mac1904) وثقافة عرض — النظير على مستوى model-level لـ WorkbookSettings::GetDate1904() / GetCulture(). معظم أنواع *Model في هذه المجموعة تعرض CopyFrom(source) وHasStoredState()، التي يستخدمها serializer للتمييز بين القيمة المحددة صراحةً والقيمة الافتراضية غير المحددة قبل كتابة XML.

نماذج ميزات ورقة العمل

WorksheetProtectionModel يعكس حقل WorksheetProtection حقلًا بآخر ويضيف حقول كلمة المرور المخزنة — GetPasswordHash()، GetAlgorithmName()، GetHashValue()، GetSaltValue()، GetSpinCount() — التي لا يعرضها facade WorksheetProtection مباشرة. WorksheetViewModel يحتفظ بـ grid-line, header, و zero visibility، تخطيط من اليمين إلى اليسار، ومقياس التكبير. PageSetupModel يضمّن PageMarginsModel (left/right/top/bottom/header/footer margins as doubles)، PrintOptionsModel (grid lines, headings, horizontal and vertical centering)، وHeaderFooterModel (left/center/right header and footer text)، إلى جانب paper size, orientation, scale, fit-to-width/height, print area, print title rows/columns, ومتجهات page-break.

AutoFilterModel يحتوي على range string، وstd::vector<FilterColumnModel>، وAutoFilterSortStateModel. FilterColumnModel بدوره يضمّن AutoFilterColorFilterModel، AutoFilterDynamicFilterModel، وAutoFilterTop10Model، بالإضافة إلى قائمة بسيطة من سلاسل قيم الفلتر وstd::vector<AutoFilterCustomFilterModel>. ConditionalFormattingModel يزوج std::vector<CellArea> مع std::vector<FormatConditionModel> — كل شرط يحمل نوعه، operator، الصيغ، حقول color-scale/data-bar/icon-set، وStyleValue للتنسيق الناتج. ValidationModel وHyperlinkModel يعكسان facades Validation وHyperlink كسجلات بسيطة، وDefinedNameModel يعكس DefinedName. SheetVisibility هو enum طبقة النموذج خلف Worksheet::GetVisibilityType().

بعض ميزات facade التي تدعمها هذه السجلات — AutoFilter وConditionalFormattingCollection على وجه الخصوص — تم الإشارة إليها في توثيق المنتج بأنها لا تزال قيد التطوير النشط في هذا الإصدار. اعتبر الأشكال أعلاه كهدف هيكلي يبني حوله النموذج والserializer بدلاً من ضمان أن كل حقل يعيد المرور عبر workbook محفوظ اليوم.

التشخيص والحالة المشتركة

DiagnosticBag، الذي يتم الوصول إليه عبر WorkbookModel::GetDiagnostics()، يجمع سجلات DiagnosticEntry — كل منها يحتوي على GetCode()، وGetSeverity() (DiagnosticSeverity: Warning، Recoverable، أو LossyRecoverable)، وGetMessage()، وعلامة GetRepairApplied()، وعلامة GetDataLossRisk() — تُولد أثناء تحليل أو تسلسل الworkbook. هذا يعمل جنبًا إلى جنب مع Workbook::GetLoadDiagnostics()، الذي تشترك أنواعه على مستوى facade LoadDiagnostics / LoadIssue في نفس enum DiagnosticSeverity; الكود الذي يحتاج إلى raw model record بدلاً من wrapper LoadIssue يصل إليه عبر GetDiagnostics() على workbook model.

SharedStringRepository يدعم جدول السلاسل المشتركة في xlsx: GetValues() يُعيد متجه السلاسل المُخزّن داخليًا، 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)

المثال أدناه يكتب خلية عبر الواجهة، ثم يتوغل إلى النموذج الأساسي للحصول على حقيبة تشخيصية و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; يُسمح بالاستخدام التجاري، والتعديل، وإعادة التوزيع.

بدء الاستخدام

الموارد ذات الصلة

Aspose.Cells — Enterprise Blog

المقدمة#

ما الذي يتضمنه#

شجرة نموذج المصنف والورقة#

بيانات النمط كقيم بسيطة#

خصائص المستند وإعدادات مستوى المصنف#

نماذج ميزات ورقة العمل#

التشخيص والحالة المشتركة#

البدء السريع#

الصيغ المدعومة#

المصدر المفتوح والترخيص#

بدء الاستخدام#

الموارد ذات الصلة#