מבוא

Aspose.Cells FOSS עבור C++ בנוי משתי שכבות. השכבה שהקוד נוגע בה ברובו היא ה-facade: Workbook, Worksheet, Cell, ו-Style, שהיא מה שמכסים הודעות ההכרזה ופוסטים על תכונות עבור פלטפורמה זו. מתחתיה נמצאת שכבה שנייה, במרחב השמות Aspose::Cells_FOSS::Core, המורכבת מרשומות נתונים פשוטות — WorkbookModel, WorksheetModel, CellRecord, StyleValue, וכ-כארבעה עשר עשרות סוגי *Model ו-*Value קשורים. רשומות אלו מחזיקות את מצב הגיליון האלקטרוני המפוענח בפועל: ערכי תאים שמקושרים לפי CellAddress, תכונות סגנון כ-StyleValue, הגדרות חוברת עבודה וגליון, הגדרת דף, מסננים, ואבחוני טעינה. מחלקות ה-facade קוראות ומכתבות לשכבה זו במקום לאחסן מצב בעצמן.

הגשר בין שתי השכבות הוא מפורש וציבורי. 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 ונכלל כקבצי כותרת ומקור במקום קובץ בינארי מוכן. אם עדיין לא עבדת עם ה-facade API, התחל תחילה בפוסט על תכונות Workbook/Worksheet/Cell — פוסט זה מניח את הבסיס הזה ומתמקד במה שיושב מתחתיו.

מה כלול

עץ מודל חוברת העבודה וגליון העבודה

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 ל-Facade המשתנה Style — Style::ToCore() ממיר Style ל-StyleValue, ו-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()) — שלא כמו מחלקת ה-Facade Color אין לו מפעל בסגנון FromArgb(), ולכן ColorValue בדרך כלל מתקבל מסגנון קיים במקום שנבנה ישירות.

BordersValue מכיל חמישה חברים של BorderSideValue — שמאל, ימין, למעלה, למטה, ואלכסוני — שכל אחד מצמיד ערך enum של BorderStyle עם ColorValue. AlignmentValue מדגם יישור אופקי ואנכי, גלישת טקסט, רמת הזחה, סיבוב טקסט, הקטנה להתאמה, וסדר קריאה. ProtectionValue ו-NumberFormatValue תומכים בדגלי הגנת התא ובזוג מזהה פורמט-מספר/מחרוזת מותאמת שה-Style חושף.

StyleRepository, המושג דרך WorkbookModel::GetStyles(), חושף פעולה אחת: Normalize(style) -> StyleValue. חוברת העבודה משתמשת בו פנימית בזמן טעינה ושמירה כדי לאחד סגנונות שווים במקום לשכפל רשומות StyleValue זהות — הוא אינו מטמון סגנונות כללי עם חיפוש מבוסס אינדקס במשטח API הנוכחי.

מאפייני המסמך והגדרות ברמת חוברת העבודה

DocumentPropertiesModel מקבץ GetCore() (CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status, and created/modified timestamps) and GetExtended() (ExtendedDocumentPropertiesModel: application, app version, company, manager, doc security, hyperlink base, and the scale-crop / links-up-to-date / shared-doc flags). DocumentProperties::GetModel() ו-ExtendedDocumentProperties::GetModel() מחברים את מחלקות החזית אל הרשומות האלו.

WorkbookPropertiesModel משקף את WorkbookProperties — code name, show-objects, filter privacy, backup-file, and related flags — ומקיף את 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) ותרבות תצוגה — המקביל ברמת המודל של WorkbookSettings::GetDate1904() / GetCulture(). רוב סוגי *Model בקבוצה זו חושפים את CopyFrom(source) ו-HasStoredState(), שהסיריאלייזר משתמש בהם כדי להבדיל בין ערך שהוגדר במפורש לערך ברירת מחדל שלא הוגדר לפני כתיבת XML.

מודלי תכונות גיליון עבודה

WorksheetProtectionModel משקף את WorksheetProtection שדה אחרי שדה ומוסיף את שדות הסיסמה השמורים — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — שה-WorksheetProtection של החזית אינו מציג ישירות. WorksheetViewModel מכיל קו רשת, כותרת, ונראות אפס, פריסה מימין לשמאל, וקנה מידה של זום. PageSetupModel כולל את PageMarginsModel (מרווחים של שמאל/ימין/למעלה/למטה/כותרת/תחתונה כערכים מסוג double), PrintOptionsModel (קווי רשת, כותרות, יישור אופקי ואנכי), ו-HeaderFooterModel (טקסט כותרת ותחתית שמאל/מרכז/ימין), לצד גודל נייר, כיוון, קנה מידה, התאמה לרוחב/גובה, אזור הדפסה, שורות/עמודות כותרת להדפסה, ווקטורי שבירת עמוד.

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 משקפים את המופעים Validation ו-Hyperlink של החזית כרשומות פשוטות, ו-DefinedNameModel משקף את DefinedName. SheetVisibility הוא ה-enum של שכבת המודל מאחורי Worksheet::GetVisibilityType().

חלק מהתכונות של החזית שהרשומות הללו תומכות בהן — במיוחד AutoFilter ו-ConditionalFormattingCollection — מצוינות בתיעוד המוצר כעדיין בפיתוח פעיל בגרסה זו. יש להתייחס לצורות שלמעלה כאל היעד המבני שהמודל והסיריאלייזר נבנים סביבו ולא כהבטחה שכל שדה יעבור בצורה מלאה דרך חוברת עבודה שמורה היום.

אבחון ומצב משותף

DiagnosticBag, שניגשים אליו דרך WorkbookModel::GetDiagnostics(), אוסף רשומות DiagnosticEntry — כל אחת עם GetCode(), GetSeverity() (DiagnosticSeverity: Warning, Recoverable, או LossyRecoverable), GetMessage(), דגל GetRepairApplied(), ודגל GetDataLossRisk() — שנוצרו בזמן שגיליון עבודה מפוענח או מסיריאליזד. זה רץ לצד Workbook::GetLoadDiagnostics(), שבו סוגי LoadDiagnostics / LoadIssue ברמת החזית חולקים את אותו enum DiagnosticSeverity; קוד שצריך את רשומת המודל הגולמית במקום העטיפה LoadIssue מגיע אליו דרך GetDiagnostics() במודל הגיליון.

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; שימוש מסחרי, שינוי והפצה מותרות.

התחלה

משאבים קשורים