مقدمه

Aspose.Cells FOSS برای Rust عملکرد خود را از طریق crate aspose-cells-foss-rust ارائه می‌دهد، که حول یک مجموعه فشرده از انواع هسته‌ای متمرکز است: Workbook، Worksheet، Cells، Cell و DocumentProperties، که هر کدام دارای accessorهای *Mut متناظر برای دسترسی نوشتنی هستند. این پست یک تور سیستماتیک از سطح هسته‌ای API است — نه یک ویژگی محدود، بلکه اصولی که هر برنامه‌ای ساخته‌شده بر پایه این crate در نهایت از آن استفاده می‌کند: ایجاد و نام‌گذاری worksheets، خواندن و نوشتن مقادیر سلول‌های تایپ‌شده، تنظیم metadata سند، محافظت و مخفی‌کردن worksheets، تعیین اندازه ردیف‌ها و ستون‌ها، ادغام سلول‌ها، و بارگذاری فایل‌ها به‌صورت ایمن.

این crate تحت مجوز MIT است و هدف‌گذاری آن نسخهٔ Rust edition 2021 است. تقریباً هر عملیات خطاپذیری Result<_, CellsError> را برمی‌گرداند، بنابراین مدیریت خطا با عملگر ? در مثال‌های زیر همان‌گونه که در کد واقعی اجرا می‌شود، اعمال می‌شود. این crate مجموعه‌ای کوچک از وابستگی‌های زمان اجرا را وارد می‌کند به‌جای اینکه همه چیز را از صفر بازنویسی کند — chrono برای مقادیر تاریخ-زمان، zip برای فرمت بسته XLSX، roxmltree برای تجزیهٔ XML، serde_json برای داده‌های ساختاری، sha2 و base64 برای هش‌گذاری و رمزگذاری، و getrandom برای تصادفی‌سازی.

هر بخش زیر یک حوزه از API را با انواع و روش‌های مشخص مرتبط پوشش می‌دهد، که توسط مثال‌های عملی Rust استخراج‌شده از کد نمونهٔ خود crate پشتیبانی می‌شود.


ویژگی‌های کلیدی

اصول پایهٔ Workbook و Worksheet

یک Workbook به‌صورت خالی با Workbook::new() شروع می‌شود، که یک worksheet به نام "Sheet1" دارد. شیت‌های اضافی از WorksheetsMut::add(name) به دست می‌آیند که اندیس شیت جدید را برمی‌گرداند. Worksheets/WorksheetsMut همچنین با استفاده از active_sheet_name() و set_active_sheet_name() شیت فعال را پیگیری می‌کنند.

let mut workbook = Workbook::new();
{
    let mut worksheets = workbook.get_worksheets_mut();
    let sheet = worksheets.get(0)?;
    sheet.set_name("Summary")?;

    let detail_index = worksheets.add("Detail")?;
    let detail = worksheets.get(detail_index)?;
    detail.get_cells_mut().get("A1")?.put_value_string("Detail data")?;

    worksheets.set_active_sheet_name("Detail")?;
}

let sheets = workbook.get_worksheets();
println!("Worksheet count: {}", sheets.count());
println!("Active sheet: {}", sheets.active_sheet_name());

مقادیر سلولی تایپ‌شده و فرمول‌ها

Cells/CellsMut یک سلول را با ارجاع به سبک A1 (get("B3")) یا با اندیس ردیف/ستون (get_by_index(row, column)) آدرس می‌دهند. هر Cell/CellMut مقادیر تایپ‌شده را از طریق setterهای اختصاصی می‌پذیرند، بنابراین نیازی به تبدیل‌های رشته‌ای نیست، و فرمول‌ها همراه با مقدار کش‌شده نوشته می‌شوند به‌طوری که فایل قبل از هر بازمحاسبه‌ای با نتایج صحیح باز می‌شود.

let mut workbook = Workbook::new();
{
    let mut worksheets = workbook.get_worksheets_mut();
    let sheet = worksheets.get(0)?;
    let mut cells = sheet.get_cells_mut();

    cells.get("A1")?.put_value_string("Hello")?;
    cells.get("B1")?.put_value_i32(123)?;
    cells.get("C1")?.put_value_bool(true)?;
    cells.get("D1")?.put_value_decimal(12.5)?;
    cells.get("F1")?.put_value_i32(10)?;
    cells.get("G1")?
        .put_formula_with_cached_value("=F1*2", CellValue::Number(20.0))?;
}
workbook.save("typed-values.xlsx")?;

let loaded = Workbook::load_xlsx("typed-values.xlsx")?;
let sheet = loaded.worksheet("Sheet1")?;
let cells = sheet.get_cells();
println!(
    "{:?}: {}",
    cells.get("B1")?.value_type(),
    cells.get("B1")?.display_string_value()
);
println!("G1 cached value -> {}", cells.get("G1")?.display_string_value());

ویژگی‌های سند

Workbook::get_document_properties_mut() به یک شیء DocumentProperties دست می‌یابد که شامل فیلدهای متادیتای عمومی (عنوان، موضوع، نویسنده، کلمات کلیدی، دسته‌بندی، شرکت) است، به‌علاوه یک CoreDocumentProperties تو در تو (get_core_mut()) و ExtendedDocumentProperties (get_extended_mut()) برای مجموعه‌های ویژگی‌های اصلی/گسترش‌ یافته OOXML.

{
    let properties = workbook.get_document_properties_mut();
    properties.set_title("Annual Sales Report 2024");
    properties.set_subject("Financial Performance Analysis");
    properties.set_author("Finance Department");
    properties.set_keywords("sales, finance, 2024, report");
    properties.set_category("Financial Reports");
    properties.set_company("Acme Corporation");

    let core = properties.get_core_mut();
    core.set_creator("Finance Department");
    core.set_created(Some(Utc::now()));

    let extended = properties.get_extended_mut();
    extended.set_company("Acme Corporation");
}
workbook.save("with-properties.xlsx")?;

let loaded = Workbook::load_xlsx("with-properties.xlsx")?;
let properties = loaded.get_document_properties();
println!("Title: {}", properties.get_title());
println!("Core creator: {}", properties.get_core().get_creator());

حفاظت و نمایش برگه کاری

یک Worksheet می‌تواند با set_visibility_type(VisibilityType::Hidden) مخفی شود، با set_tab_color رنگ‌آمیزی شود، و با protect() به همراه یک شیء WorksheetProtection (از طریق get_protection_mut()) قفل شود که دقیقاً تعیین می‌کند کدام اقدامات — قالب‌بندی سلول‌ها، انتخاب سلول‌های قفل‌شده، و غیره — پس از فعال شدن حفاظت قابل دسترسی باقی می‌مانند.

let mut workbook = Workbook::new();
{
    let mut worksheets = workbook.get_worksheets_mut();
    let layout = worksheets.get(0)?;
    layout.set_name("Layout")?;
    layout.set_visibility_type(VisibilityType::Hidden);
    layout.set_tab_color(Color::from_argb(255, 34, 68, 102));
    layout.set_show_gridlines(false);
    layout.set_right_to_left(true);
    layout.set_zoom(85)?;
    layout.protect();

    let protection = layout.get_protection_mut();
    protection.set_objects(true);
    protection.set_format_cells(true);
    protection.set_select_locked_cells(true);
}
workbook.save("protected.xlsx")?;

let loaded = Workbook::load_xlsx("protected.xlsx")?;
let sheet = loaded.worksheet("Layout")?;
println!("Visibility: {:?}", sheet.get_visibility_type());
println!("Protected: {}", sheet.is_protected());

ردیف‌ها، ستون‌ها و سلول‌های ادغام‌شده

CellsMut get_rows()/get_columns() را به‌عنوان RowsMut/ColumnsMut برای تنظیم اندازه و مخفی‌سازی ردیف‌ها و ستون‌های فردی، و merge(first_row, first_column, total_rows, total_columns) برای ترکیب یک دامنه از سلول‌ها به یک ناحیه ادغام‌شده ارائه می‌دهد.

let mut workbook = Workbook::new();
{
    let mut worksheets = workbook.get_worksheets_mut();
    let sheet = worksheets.get(0)?;
    let mut cells = sheet.get_cells_mut();

    cells.get("A1")?.put_value_string("Merged")?;
    cells.get("C4")?.put_value_i32(99)?;
    cells.get_rows().get(1).set_height(22.5)?;
    cells.get_rows().get(3).set_is_hidden(true)?;
    cells.get_columns().get(0).set_width(18.25)?;
    cells.get_columns().get(2).set_is_hidden(true)?;

    let mut cells = sheet.get_cells_mut();
    cells.merge(0, 0, 2, 2)?;
}
workbook.save("rows-columns.xlsx")?;

let loaded = Workbook::load_xlsx("rows-columns.xlsx")?;
let sheet = loaded.worksheet("Sheet1")?;
println!(
    "Row 2 height: {}",
    sheet.get_rows().get(1).get_height().unwrap_or_default()
);
println!(
    "Column A width: {}",
    sheet.get_columns().get(0).get_width().unwrap_or_default()
);
println!("Merged regions: {}", sheet.get_cells().get_merged_cells().len());

بارگذاری دفاعی با تشخیص‌ها

فایل‌های XLSX دنیای واقعی همیشه به‌درستی قالب‌بندی نمی‌شوند. LoadOptions پرچم‌های تعمیر (try_repair_package، try_repair_xml) را در دسترس می‌گذارد و Workbook::get_load_diagnostics() یک شیء LoadDiagnostics باز می‌گرداند که issues() آن گزارش می‌دهد که بارگذار چه چیزی را یافته و تعمیر کرده است.

let options = LoadOptions {
    try_repair_package: true,
    try_repair_xml: true,
    ..LoadOptions::default()
};

let loaded = Workbook::load_xlsx_with_options(&path, &options)?;
let sheet = loaded.worksheet("Sheet1")?;
let cells = sheet.get_cells();

println!(
    "Loaded workbook with {} worksheet(s) and {} diagnostic issue(s).",
    loaded.get_worksheets().count(),
    loaded.get_load_diagnostics().issues().len()
);
println!("First item: {}", cells.get("A2")?.display_string_value());

شروع سریع

# Cargo.toml
[dependencies]
aspose-cells-foss-rust = { git = "https://github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-Rust" }

یک جلسهٔ حداقل که به اصول کتاب‌کار، برگه کاری، سلول و ویژگی‌های سند می‌پردازد:

use aspose_cells_foss_rust::{CellValue, Workbook};
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    let mut workbook = Workbook::new();
    {
        let mut worksheets = workbook.get_worksheets_mut();
        let sheet = worksheets.get(0)?;
        sheet.set_name("Report")?;

        let mut cells = sheet.get_cells_mut();
        cells.get("A1")?.put_value_string("Item")?;
        cells.get("B1")?.put_value_string("Quantity")?;
        cells.get("A2")?.put_value_string("Widgets")?;
        cells.get("B2")?.put_value_i32(12)?;
        cells.get("B3")?
            .put_formula_with_cached_value("=SUM(B2:B2)", CellValue::Number(12.0))?;
    }

    workbook.get_document_properties_mut().set_title("Quick Start Report");
    workbook.save("report.xlsx")?;

    let loaded = Workbook::load_xlsx("report.xlsx")?;
    let sheet = loaded.worksheet("Report")?;
    let cells = sheet.get_cells();
    println!("Title: {}", loaded.get_document_properties().get_title());
    println!("Total formula -> {}", cells.get("B3")?.display_string_value());

    Ok(())
}

قالب‌های پشتیبانی‌شده

قالبپسوندخواندننوشتن
XLSX.xlsx✓✓

XLSX محور نسخهٔ فعلی است: خواندن و نوشتن کامل دور‌به‌دور از طریق Workbook::load_xlsx و Workbook::save، با enumهای LoadFormat و SaveFormat که انتخاب صریح قالب را کنترل می‌کنند.


منبع باز و مجوزدهی

Aspose.Cells FOSS برای Rust تحت مجوز MIT است. کد منبع کامل در GitHub موجود است و این مجوز اجازه استفاده تجاری، تغییر و توزیع مجدد را می‌دهد.


شروع کار

منابع مرتبط