مقدمه

مدیریت صفحات گسترده بخشی از 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 را رعایت می‌کند.

استایل‌دهی با Style، Font، Color و Borders

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);

این مقادیر همانند محتوای سلول، از ذخیره‌سازی تا بارگذاری مجدد به‌صورت دوری (round-trip) رفتار می‌کنند، که برای گزارش‌هایی که به متادیتای سازگار در میان فایل‌های تولید شده نیاز دارند، مفید است.

شروع سریع

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 در دسترس است، و کتابخانه می‌تواند در پروژه‌های تجاری و منبع باز بدون هزینه‌های زمان اجرا استفاده، تغییر و بازتوزیع شود.

شروع کار

منابع مرتبط