הקדמה

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 ייעודיים, כך שאין צורך בהמרות מסוג stringly-typed, והנוסחאות נכתבות יחד עם ערך מטמון כך שהקובץ נפתח עם תוצאות נכונות לפני כל חישוב מחדש.

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 שמכסה את שדות המטא-דאטה המשותפים (title, subject, author, keywords, category, company), בנוסף ל-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, והרישיון מאפשר שימוש מסחרי, שינוי והפצה מחדש.


התחלה

מקורות קשורים