umya-spreadsheet

 
 

کتابخانهٔ Rust خالص برای فایل‌های XLSX/XLSM

خواندن، نوشتن، استایل‌دهی و دستکاری صفحات گسترده XLSX/XLSM بدون هیچ وابستگی خارجی.

umya-spreadsheet چیست؟

umya-spreadsheet یک کتابخانهٔ با عملکرد بالا و خالص Rust برای خواندن و نوشتن فایل‌های صفحه‌گستردهٔ Excel در فرمت‌های XLSX و XLSM است. این کتابخانه برای ایمنی و کارایی طراحی شده و از کدهای ناامن و وابستگی‌های خارجی اجتناب می‌کند، که آن را برای برنامه‌های دسکتاپ، پردازش سمت سرور و محیط‌های WebAssembly ایده‌آل می‌سازد. این کتابخانه یک API تمیز و بومی Rust برای دسترسی به سلول‌ها، ردیف‌ها، ستون‌ها، سبک‌ها، نمودارها و تصاویر فراهم می‌کند و به توسعه‌دهندگان امکان می‌دهد ابزارهای صفحه‌گستردهٔ قدرتمندی بسازند بدون اینکه به Microsoft Office یا COM interop وابسته باشند.

با پشتیبانی کامل از بارگذاری تنبل، حفاظت با رمز عبور و قالب‌بندی غنی، umya-spreadsheet فاصله بین عملکرد و قابلیت استفاده را پر می‌کند. این کتابخانه از خروجی CSV، تولید نمودار، جاسازی تصویر و عملیات بر روی بازه‌ها مانند جابجایی و کپی پشتیبانی می‌کند. پروژه به‌صورت فعال نگهداری می‌شود، مستندات خوبی دارد و تست شده است، با تمرکز بر صحت و سازگاری با ویژگی‌های مدرن Excel. توسعه‌دهندگان می‌توانند آن را در ابزارهای خط فرمان، بک‌اندهای وب یا برنامه‌های دسکتاپ با استفاده از چارچوب‌هایی مانند Tauri یا Axo یکپارچه کنند.

Previous Next

شروع کار با 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 APIهای شهودی برای خواندن و نوشتن فایل‌های XLSX و XLMS فراهم می‌کند. برای بارگذاری یک کتاب‌کار از دیسک از `reader::xlsx::read()` استفاده کنید، یا برای ایجاد یک فایل خالی از `new_file()` استفاده کنید. نوشتن به همان اندازه ساده است: با کتاب‌کار و مسیر هدف، `writer::xlsx::write()` را فراخوانی کنید. این کتابخانه از بارگذاری تنبل از طریق `lazy_read()` برای بهبود عملکرد در فایل‌های بزرگ پشتیبانی می‌کند و امکان نوشتن با رمز عبور یا تنظیم رمز عبور پس از ایجاد را فراهم می‌آورد. تمام عملیات‌ها ایمن هستند، در صورت امکان بدون کپی‌سازی (zero-copy) انجام می‌شوند و از باینری‌های خارجی جلوگیری می‌کنند.

چگونه یک فایل 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();
 فارسی