مقدمة

إدارة جداول البيانات هي الجزء من Aspose.Cells FOSS للغة C++ الذي يلمسه معظم البرامج أولاً: الـWorkbook التي تمتلك الملف، وكائنات الـWorksheet الموجودة داخله، ومجموعة الـCells التي تحتفظ بالقيم والصيغ والتنسيق. يشرح هذا المقال هذا السطح بمزيد من العمق مقارنةً بالمقدمة العامة — كيفية إنشاء دفاتر العمل وأوراق العمل والتنقل بينها، وكيفية قراءة وكتابة قيم الخلايا والصيغ، وكيفية دمج Style وFont وColor وBorders لتنسيق المخرجات، وكيف يضيف PageSetup وHyperlink وDefinedName وValidation بنية حول شبكة الخلايا الخام.

كل فئة مغطاة هنا هي جزء من API الأصلي لـ C++ المعلن تحت رؤوس aspose/cells_foss/. لا يوجد تفاعل COM ولا اعتماد على تثبيت Microsoft Excel — المكتبة تقرأ وتكتب تنسيق الحزمة .xlsx مباشرةً، وهذا هو السبب أيضاً في أن الإصدار الحالي يدعم .xlsx فقط، سواءً عند التحميل أو الحفظ.

الأمثلة أدناه تُبنى على بعضها: يتم إنشاء دفتر عمل، وتعبئة أوراق العمل والخلايا، وتطبيق الأنماط، ثم حفظ الملف وإعادة تحميله لتأكيد عملية الدورة الكاملة. جميع الشيفرات مُستمدة من مجموعات اختبار التوافق، والاختبارات الذهبية، واختبارات الوحدة الخاصة بالمكتبة، لذا فهي تعكس عمليات تُجرى على مخرجات .xlsx الحقيقية.

الميزات الرئيسية

إدارة دفتر العمل وأوراق العمل

يبدأ Workbook بورقة عمل واحدة في WorksheetCollection. تُضاف أوراق العمل باستخدام Add()، ويتم البحث عنها حسب الفهرس أو الاسم، وإعادة تسميتها باستخدام SetName(). كما يتتبع WorksheetCollection أي ورقة نشطة:

#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"

using namespace Aspose::Cells_FOSS;

Workbook workbook;
Worksheet& sheet = workbook.GetWorksheets()[0];
sheet.SetName("Data");

int summaryIndex = workbook.GetWorksheets().Add("Summary");
workbook.GetWorksheets().SetActiveSheetIndex(0);

int sheetCount = workbook.GetWorksheets().GetCount(); // 2

حفظ وإعادة التحميل يمران عبر نفس نوع Workbook. Workbook::Save() تقبل مسار ملف، ويمكن إنشاء Workbook مباشرةً من مسار أو من مخزن بايت في الذاكرة، مما يعيد قيم الخلايا والصيغ بشكل كامل:

workbook.Save("report.xlsx");

Workbook loaded("report.xlsx");
Worksheet& reloadedSheet = loaded.GetWorksheets()["Data"];

قيم الخلايا والصيغ

Cells، الذي يتم الوصول إليه عبر Worksheet::GetCells()، يفهرس الخلايا باستخدام مرجع بنمط A1. Cell::PutValue() تقبل سلاسل نصية، أعداد صحيحة، أعداد مزدوجة، وبيانات منطقية، SetFormula() تخزن سلسلة صيغة Excel، وGetValue() تُرجع CellValue مع نواقل ذات نوعية (AsString()، AsInteger()، AsDouble()، AsBool()، AsDateTime()):

Cells& cells = sheet.GetCells();
cells["A1"].PutValue("Category");
cells["B1"].PutValue("Amount");
cells["A2"].PutValue("Travel");
cells["B2"].PutValue(482.50);
cells["A3"].PutValue("Supplies");
cells["B3"].PutValue(129.99);
cells["B4"].SetFormula("=SUM(B2:B3)");

CellValue amount = cells["B2"].GetValue();
if (amount.IsDouble()) {
    double value = amount.AsDouble();
}

std::string formula = cells["B4"].GetFormula();

Cell::GetType() يُبلّغ عن CellValueType المخزن (Blank، String، Number، Boolean، DateTime أو Formula)، وGetDisplayStringValue() تُعيد القيمة مُنسقة بالطريقة التي تظهر بها في Excel، مع احترام أي تنسيق رقمي يُطبق عبر Style.

التنسيق باستخدام النمط، الخط، اللون، والحدود

Cell::GetStyle() تُعيد كائن Style يمكن تعديله وإعادة تطبيقه باستخدام SetStyle(). Style تُظهر Font، مجموعة Borders، نمط تعبئة ولون، محاذاة، وتنسيق رقمي:

#include "aspose/cells_foss/Style.h"
#include "aspose/cells_foss/Color.h"

Cell headerCell = sheet.GetCells()["A1"];
Style style = headerCell.GetStyle();

Font font = style.GetFont();
font.SetBold(true);
font.SetColor(Color::FromArgb(255, 255, 255, 255));
style.SetFont(font);

style.SetPattern(FillPattern::Solid);
style.SetForegroundColor(Color::FromArgb(255, 34, 120, 212));
style.SetHorizontalAlignment(HorizontalAlignmentType::Center);

Borders borders = style.GetBorders();
Border bottomBorder = borders.GetBottom();
bottomBorder.SetLineStyle(BorderStyleType::Thin);
borders.SetBottom(bottomBorder);
style.SetBorders(borders);

style.SetNumberFormat("#,##0.00");
headerCell.SetStyle(style);

Style هو نوع قيمة: قراءته مرة أخرى باستخدام GetStyle() تعكس ما تم تعيينه آخرًا باستخدام SetStyle()، مما يجعل من السهل إنشاء نمط واحد وتطبيقه عبر صف الرأس أو نطاق من خلايا البيانات.

إعداد الصفحة وتكوين الطباعة

Worksheet::GetPageSetup() يُرجِع كائن PageSetup يغطي حجم الورق، الاتجاه، الهوامش، التحجيم، عناوين الطباعة، وفواصل الصفحات:

#include "aspose/cells_foss/PageSetup.h"

PageSetup& pageSetup = sheet.GetPageSetup();
pageSetup.SetOrientation(PageOrientationType::Landscape);
pageSetup.SetPaperSize(PaperSizeType::PaperA4);
pageSetup.SetFitToPagesWide(1);
pageSetup.SetFitToPagesTall(0);
pageSetup.SetPrintArea("$A$1:$D$20");
pageSetup.SetPrintTitleRows("$1:$1");
pageSetup.SetLeftMargin(0.5);
pageSetup.SetCenterFooter("Page &P of &N");
pageSetup.AddHorizontalPageBreak(20);

الهوامش متوفرة بوحدات خام (GetLeftMargin()) وبالبوصة (GetLeftMarginInch())، وGetHorizontalPageBreaks() / GetVerticalPageBreaks() تُعيد مواضع فواصل الصفحات الحالية المحددة على الورقة.

الروابط التشعبية، الأسماء المعرفة، والتحقق من صحة البيانات

Worksheet::GetHyperlinks() يُرجِع HyperlinkCollection. Add() يأخذ خلية أو نطاق هدف بالإضافة إلى عنوان ويُرجِع فهرس الرابط التشعبي الجديد، والذي يُستخدم لجلب كائن Hyperlink لإجراء تغييرات إضافية:

#include "aspose/cells_foss/Hyperlink.h"

sheet.GetCells()["A1"].PutValue("Documentation");
int linkIndex = sheet.GetHyperlinks().Add("A1", 1, 1, "https://example.com/docs");
Hyperlink link = sheet.GetHyperlinks()[linkIndex];
link.SetTextToDisplay("Documentation");
link.SetScreenTip("Open the docs site");

Workbook::GetDefinedNames() يدير النطاقات المسماة بنفس الطريقة — Add() يُرجِع فهرسًا إلى DefinedNameCollection:

#include "aspose/cells_foss/DefinedName.h"

int nameIndex = workbook.GetDefinedNames().Add("Total", "=Data!$B$2:$B$3");
DefinedName total = workbook.GetDefinedNames()[nameIndex];
total.SetComment("Sum of tracked expenses");

Worksheet::GetValidations() يتبع نمط الجمع نفسه لقواعد التحقق من صحة البيانات، المحددة إلى CellArea:

#include "aspose/cells_foss/Validation.h"
#include "aspose/cells_foss/CellArea.h"

int ruleIndex = sheet.GetValidations().Add(CellArea::CreateCellArea("B2", "B3"));
Validation amountRule = sheet.GetValidations()[ruleIndex];
amountRule.SetType(ValidationType::Decimal);
amountRule.SetOperator(OperatorType::GreaterThan);
amountRule.SetFormula1("0");
amountRule.SetErrorTitle("Invalid Amount");
amountRule.SetErrorMessage("Enter a positive number");

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

Workbook::GetDocumentProperties() يكشف حقول البيانات الوصفية الأساسية والموسعة في OOXML (العنوان، المؤلف، الشركة، المدير، وما شابه)، وWorkbook::GetSettings() يتحكم في سلوك مستوى المصنف مثل نظام التاريخ:

#include "aspose/cells_foss/DocumentProperties.h"

workbook.GetDocumentProperties().SetCompany("Example Corp");
workbook.GetDocumentProperties().SetManager("Finance Team");

workbook.GetSettings().SetDate1904(false);

هذه القيم تمر بعملية الحفظ وإعادة التحميل بنفس طريقة محتوى الخلية، مما يكون مفيدًا للتقارير التي تحتاج إلى بيانات وصفية متسقة عبر الملفات المُولدة.

البدء السريع

Aspose.Cells FOSS للغة C++ يتم بناؤه من المصدر باستخدام CMake. استنساخ المستودع وإما إضافته كدليل فرعي أو سحبه باستخدام FetchContent:

git clone https://github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-Cpp.git

cmake_minimum_required(VERSION 3.15)
project(MyProject CXX)
set(CMAKE_CXX_STANDARD 17)

add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Aspose.Cells.Foss.Cpp)

مثال بسيط لإدارة الجداول — إنشاء، تنسيق، حفظ، وإعادة تحميل:

#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
#include "aspose/cells_foss/Cell.h"

using namespace Aspose::Cells_FOSS;

int main() {
    Workbook workbook;
    Worksheet& sheet = workbook.GetWorksheets()[0];
    sheet.SetName("Expenses");

    Cells& cells = sheet.GetCells();
    cells["A1"].PutValue("Category");
    cells["B1"].PutValue("Amount");
    cells["A2"].PutValue("Travel");
    cells["B2"].PutValue(482.50);
    cells["A3"].PutValue("Supplies");
    cells["B3"].PutValue(129.99);
    cells["B4"].SetFormula("=SUM(B2:B3)");

    workbook.Save("expenses.xlsx");

    Workbook loaded("expenses.xlsx");
    Cells& loadedCells = loaded.GetWorksheets()["Expenses"].GetCells();
    double total = loadedCells["B4"].GetValue().AsDouble();

    return 0;
}

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

تنسيقامتدادقراءةكتابة
Xlsx.xlsx✓✓

LoadFormat و SaveFormat يقدمان قيمة Xlsx واحدة في هذا الإصدار؛ مُنشئا Workbook(path) و Workbook(bytes) يحملان مدخلات .xlsx، و Workbook::Save() يكتب مخرجات .xlsx إلى مسار، أو تدفق، أو مخزن في الذاكرة.

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

Aspose.Cells FOSS للغة C++ يُصدر تحت رخصة MIT. الكود المصدري متاح على GitHub، ويمكن استخدام المكتبة وتعديلها وإعادة توزيعها في المشاريع التجارية ومشاريع المصدر المفتوح دون رسوم تشغيل.

البدء

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