مقدمه

Aspose.Cells FOSS برای C++ به صورت دو لایه ساخته شده است. لایه‌ای که بیشتر کدها به آن دست می‌زنند، سطح نمایشی (facade) است: 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 در سطح کتاب‌کار، یا کار مستقیم با رکوردهای plain-old-data سلول و ردیف به جای اشیای wrapper Cell / Row.

همهٔ موارد توصیف‌شده در اینجا در همان درخت منبع بدون وابستگی و تحت مجوز MIT که بقیهٔ Aspose.Cells FOSS برای C++ را شامل می‌شود، ارسال می‌شوند؛ این درخت با CMake ساخته می‌شود و به‌صورت هدرها و سورس گنجانده شده است نه به‌صورت باینری پیش‌ساخته. اگر هنوز با 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 برای نمای سطح mutable 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 — که هر کدام یک مقدار enum BorderStyle را با یک ColorValue جفت می‌کند. AlignmentValue تراز افقی و عمودی، پیچش متن، سطح تورفتگی، چرخش متن، فشرده‌سازی به‌منظور جاگیری و ترتیب خواندن را مدل می‌کند. ProtectionValue و NumberFormatValue پرچم‌های حفاظت سلول و جفت id فرمت عددی/رشته سفارشی که Style نشان می‌دهد را پشتیبانی می‌کنند.

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 timestamps) و 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 و revisions password)، WorkbookViewModel (window position and size، first visible sheet، scroll-bar و 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() را نشان می‌دهند، که serializer از آن‌ها برای تشخیص مقدار به‌صورت صریح تنظیم‌شده از پیش‌فرض تنظیم‌نشده پیش از نوشتن XML استفاده می‌کند.

مدل‌های ویژگی برگه کاری

WorksheetProtectionModel بازتاب WorksheetProtection فیلد به فیلد است و فیلدهای رمز عبور ذخیره‌شده — GetPasswordHash()، GetAlgorithmName()، GetHashValue()، GetSaltValue()، GetSpinCount() — را که facade WorksheetProtection به‌صورت مستقیم نشان نمی‌دهد، اضافه می‌کند. WorksheetViewModel شامل grid-line، header و zero visibility، چیدمان راست-به-چپ، و مقیاس زوم است. 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 facadeها به‌عنوان رکوردهای ساده هستند، و 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 را به اشتراک می‌گذارند؛ کدی که به رکورد مدل خام به‌جای wrapper LoadIssue نیاز دارد، از طریق GetDiagnostics() روی مدل کتاب‌کار به آن دست می‌یابد.

SharedStringRepository پشت جدول shared-strings در xlsx را پشتیبانی می‌کند: GetValues() بردار رشته‌های داخلی را برمی‌گرداند، TryGetValue(index, value) یک شاخص را به متن برمی‌گرداند، و Intern(value) یک ورودی را اضافه یا دوباره استفاده می‌کند — که به‌صورت داخلی زمانی که SaveOptions::SetUseSharedStrings(true) تنظیم شده باشد، استفاده می‌شود. DateSerialConverter بین یک DateTime و شماره سریال سبک 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 برای C++ تحت مجوز MIT است. کد منبع، شامل سرآیندهای مدل Aspose::Cells_FOSS::Core که در این پست اشاره شده‌اند، در GitHub قرار دارد؛ استفاده تجاری، اصلاح و توزیع مجاز است.

شروع کار

منابع مرتبط