مقدمة
Aspose.Cells FOSS للغة Rust يعرّف وظائفه عبر الحزمة aspose-cells-foss-rust، مركّزًا على مجموعة مدمجة من الأنواع الأساسية: Workbook، Worksheet، Cells، Cell، وDocumentProperties، كل منها يملك موصلات *Mut مطابقة للوصول للكتابة. هذه المشاركة هي جولة منهجية في سطح API الأساسي — ليس ميزة ضيقة واحدة، بل الأساسيات التي تستخدمها كل تطبيق مبني على الحزمة: إنشاء وتسمية أوراق العمل، قراءة وكتابة قيم الخلايا ذات النوع، ضبط بيانات تعريف المستند، حماية وإخفاء أوراق العمل، تحديد أحجام الصفوف والأعمدة، دمج الخلايا، وتحميل الملفات بطريقة دفاعية.
الحزمة مرخصة بموجب رخصة MIT وتستهدف إصدار Rust 2021. تقريبًا كل عملية قد تفشل تُعيد Result<_, CellsError>، لذا فإن معالجة الأخطاء باستخدام العامل ? تُطبق على الأمثلة أدناه بنفس الطريقة التي تُطبق بها على الكود الحقيقي. الحزمة تستورد مجموعة صغيرة من الاعتمادات التشغيلية بدلاً من إعادة تنفيذ كل شيء من الصفر — chrono لقيم التاريخ والوقت، zip لتنسيق حزمة XLSX، roxmltree لتحليل XML، serde_json للبيانات المهيكلة، sha2 وbase64 للتجزئة والترميز، وgetrandom للعشوائية.
كل قسم أدناه يغطي مجالًا واحدًا من API مع الأنواع والطرق المحددة المتضمنة، مدعومًا بأمثلة Rust عملية مأخوذة من كود العينة الخاص بالحزمة.
الميزات الرئيسية
أساسيات الدفتر وأوراق العمل
يبدأ Workbook فارغًا مع Workbook::new()، ويحمل ورقة عمل واحدة باسم "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 تقبل القيم المكتوبة عبر setters مخصصة، لذا لا حاجة لتحويلات نصية، وتُكتب الصيغ مع قيمة مُخزّنة مؤقتًا بحيث يفتح الملف بالنتائج الصحيحة قبل أي إعادة حساب.
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، مع LoadFormat وSaveFormat enums التي تتحكم في اختيار الصيغة الصريحة.
المصدر المفتوح والترخيص
Aspose.Cells FOSS للـ Rust مرخص برخصة MIT. الكود المصدر الكامل متاح على GitHub, وتسمح الرخصة بالاستخدام التجاري، والتعديل، وإعادة التوزيع.