
umya-spreadsheet
مكتبة Rust نقية لملفات XLSX/XLSM
قراءة، كتابة، تنسيق، وتعديل جداول XLSX/XLSM بدون أي تبعيات خارجية.
ما هو umya-spreadsheet؟
umya-spreadsheet هي مكتبة Rust نقية وعالية الأداء لقراءة وكتابة ملفات جداول Excel بصيغ XLSX و XLSM. صُممت للسلامة والكفاءة، وتتجنب الشيفرة غير الآمنة والاعتمادات الخارجية، مما يجعلها مثالية لتطبيقات سطح المكتب، ومعالجة الخادم، وبيئات WebAssembly. توفر المكتبة واجهة برمجة تطبيقات Rust نظيفة وإيديوماتية للوصول إلى الخلايا والصفوف والأعمدة والأنماط والمخططات والصور، مما يمكّن المطورين من بناء أدوات جداول بيانات قوية دون الاعتماد على Microsoft Office أو COM interop.
بدعم كامل للتحميل الكسول، وحماية بكلمة مرور، وتنسيق غني، يجسر umya-spreadsheet الفجوة بين الأداء وسهولة الاستخدام. يدعم تصدير CSV، وإنشاء المخططات، وإدراج الصور، وعمليات النطاق مثل النقل والنسخ. المشروع يُصان بنشاط، موثق جيدًا، ومختبر، مع تركيز على الدقة والتوافق مع ميزات Excel الحديثة. يمكن للمطورين دمجه في أدوات سطر الأوامر، أو خلفيات الويب، أو تطبيقات سطح المكتب باستخدام أطر مثل Tauri أو Axo.
البدء مع umya-spreadsheet
لبدء استخدام umya-spreadsheet، أضفه إلى ملف Cargo.toml الخاص بك باستخدام `umya-spreadsheet = "3.1.1"`. لدعم WebAssembly، فعّل ميزة `js`. المكتبة خفيفة الاعتماد وتُترجم بسرعة. بعد التثبيت، استوردها عبر `extern crate umya_spreadsheet;` وابدأ بقراءة أو كتابة جداول البيانات. يمكنك أيضًا استكشاف GitHub umya-spreadsheet للحصول على أمثلة واختبارات ووثائق. تدعم التحميل الكسول للملفات الكبيرة وتوفر معالجة أخطاء قوية.
تثبيت umya-spreadsheet عبر Cargo
[dependencies]
umya-spreadsheet = "3.1.1"
# WebAssembly support
umya-spreadsheet = { version = "3.1.1", features = ["js"] }
قراءة وكتابة ملفات XLSX/XLSM
توفر umya-spreadsheet واجهات برمجة تطبيقات بديهية لقراءة وكتابة ملفات XLSX و XLMS. استخدم `reader::xlsx::read()` لتحميل دفتر عمل من القرص، أو `new_file()` لإنشاء دفتر فارغ. الكتابة بسيطة بنفس القدر: استدعِ `writer::xlsx::write()` مع دفتر العمل والمسار المستهدف. تدعم المكتبة التحميل الكسول عبر `lazy_read()` لتحسين الأداء على الملفات الكبيرة، وتسمح بالكتابة المحمية بكلمة مرور أو تعيين كلمات مرور بعد الإنشاء. جميع العمليات آمنة، وتستخدم النسخ الصفري حيثما أمكن، وتتجنب الثنائيات الخارجية.
كيفية قراءة وكتابة ملف XLSX عبر Rust؟
use std::path::Path;
// Read file
let path = Path::new("./input.xlsx");
let mut book = umya_spreadsheet::reader::xlsx::read(path).unwrap();
// Write file
let out_path = Path::new("./output.xlsx");
umya_spreadsheet::writer::xlsx::write(&book, out_path).unwrap();
الوصول إلى الخلايا وتعديل الأنماط
الوصول إلى قيم الخلايا وتعديلها سهل وبسيط: استخدم `cell("A1")` أو `cell((1,1))` للقراءة، و`cell_mut()` للكتابة. تُدار الأنماط عبر `style_mut()`، مما يسمح بتغيير لون الخلفية، الخط، الحدود، ومحاذاة النص. تُظهر المكتبة مجموعة غنية من خصائص النمط مع الحفاظ على ضمانات عدم القابلية للتغيير حيثما أمكن. يمكنك أيضًا استرجاع القيم المنسقة، تطبيق المنطق الشرطي، وتحديث الأنماط دفعة واحدة عبر النطاقات. هذا يجعلها مثالية لإنشاء تقارير، لوحات معلومات، أو تصدير بيانات بتنسيق موحد.
كيف تعديل قيمة الخلية والنمط باستخدام Rust؟
let mut book = umya_spreadsheet::new_file();
book.sheet_by_name_mut("Sheet1")
.unwrap()
.cell_mut("A1")
.set_value("Hello, Rust!");
let mut style = book.sheet_by_name_mut("Sheet1")
.unwrap()
.style_mut("A1");
style.set_background_color(umya_spreadsheet::Color::COLOR_RED);
دعم المخططات والصور
يدعم umya-spreadsheet إنشاء وتحرير المخططات—بما في ذلك مخططات الخط، الشريط، والمساحة—عن طريق تعريف نطاقات السلاسل والعلامات. يمكنك تضمين الصور مباشرةً في الأوراق باستخدام بنية `Image`، مع دعم PNG وغيرها من الصيغ حسب الميزات المفعلة. تتكامل المخططات والصور بسلاسة مع إحداثيات الخلايا وطبقات الرسم، مما يتيح إنشاء لوحات تحكم ديناميكية. بينما لا تزال بعض ميزات الرسم المتقدمة قيد التطوير، فإن الوظيفة الأساسية جاهزة للإنتاج وقابلة للتوسيع.
كيف إضافة مخطط خطي إلى جدول بيانات باستخدام Rust؟
let mut book = umya_spreadsheet::new_file();
let mut from_marker = umya_spreadsheet::structs::drawing::spreadsheet::MarkerType::default();
from_marker.set_coordinate("C1");
let mut to_marker = umya_spreadsheet::structs::drawing::spreadsheet::MarkerType::default();
to_marker.set_coordinate("D11");
let series = vec!["Sheet1!$A$1:$A$10", "Sheet1!$B$1:$B$10"];
let mut chart = umya_spreadsheet::structs::Chart::default();
chart.new_chart(
umya_spreadsheet::structs::ChartType::LineChart,
from_marker,
to_marker,
series,
);
book.sheet_by_name_mut("Sheet1")
.unwrap()
.add_chart(chart);
عمليات النطاق وحماية كلمة المرور
قم بأداء عمليات متقدمة مثل نقل، نسخ، وتغيير حجم النطاقات باستخدام `move_range()`، مما يتيح إعادة تنظيم البيانات ديناميكيًا. تدعم المكتبة أيضًا دفاتر العمل المحمية بكلمة مرور: كتابة الملفات باستخدام `write_with_password()` أو تطبيق كلمات مرور على الملفات الموجودة عبر `set_password()`. هذه الميزات حاسمة لمعالجة البيانات بأمان في التطبيقات المؤسسية أو الحساسة للامتثال. مع التصميم الخالي من الاعتمادات وتوافق WASM، يقدم umya-spreadsheet كلًا من المرونة والأمان.
كيف نقل نطاق وحماية ملف بكلمة مرور باستخدام Rust؟
// Move range
let range = "A1:A3";
book.sheet_by_name_mut("Sheet1")
.unwrap()
.move_range(range, &10, &2);
// Password protection
umya_spreadsheet::writer::xlsx::write_with_password(
&book,
Path::new("./protected.xlsx"),
"mypassword",
).unwrap();
