Εισαγωγή

Aspose.Cells FOSS για Rust αποκαλύπτει τη λειτουργικότητά του μέσω του crate aspose-cells-foss-rust, εστιάζοντας σε ένα συμπαγές σύνολο βασικών τύπων: Workbook, Worksheet, Cells, Cell και DocumentProperties, ο καθένας με αντίστοιχες προσβάσεις *Mut για εγγραφή. Αυτή η ανάρτηση είναι μια συστηματική περιήγηση στην κύρια επιφάνεια του API — όχι μια στενή λειτουργία, αλλά τα θεμέλια που κάθε εφαρμογή που βασίζεται στο crate χρησιμοποιεί: δημιουργία και ονομασία φύλλων εργασίας, ανάγνωση και εγγραφή τιμών κελιών με τύπο, ορισμός μεταδεδομένων εγγράφου, προστασία και απόκρυψη φύλλων εργασίας, προσαρμογή μεγέθους γραμμών και στηλών, συγχώνευση κελιών και ασφαλές φόρτωμα αρχείων.

Το crate είναι αδειοδοτημένο υπό την άδεια MIT και στοχεύει στην έκδοση Rust 2021. Σχεδόν κάθε ενέργεια που μπορεί να αποτύχει επιστρέφει Result<_, CellsError>, έτσι ο χειρισμός σφαλμάτων με τον τελεστή ? εκτελείται στα παρακάτω παραδείγματα με τον ίδιο τρόπο όπως σε πραγματικό κώδικα. Το crate εισάγει ένα μικρό σύνολο εξαρτήσεων χρόνου εκτέλεσης αντί να επανεισάγει τα πάντα από την αρχή — chrono για τιμές ημερομηνίας-ώρας, zip για τη μορφή πακέτου XLSX, roxmltree για την ανάλυση XML, serde_json για δομημένα δεδομένα, sha2 και base64 για κατακερματισμό και κωδικοποίηση, και getrandom για τυχαιοποίηση.

Κάθε ενότητα παρακάτω καλύπτει μία περιοχή του API με τους συγκεκριμένους τύπους και μεθόδους που εμπλέκονται, υποστηριζόμενη από λειτουργικά παραδείγματα Rust που προέρχονται από τον δικό του κώδικα παραδείγματος του crate.

Βασικά Χαρακτηριστικά

Βασικές Αρχές Βιβλίου Εργασίας και Φύλλου Εργασίας

Ένα 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, ώστε να μην απαιτούνται μετατροπές τύπου string, και οι τύποι γράφονται μαζί με μια αποθηκευμένη τιμή ώστε το αρχείο να ανοίγει με σωστά αποτελέσματα πριν από οποιαδήποτε επαναϋπολογισμό.

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, με LoadFormat και SaveFormat enums που καθορίζουν την ρητή επιλογή μορφής.

Ανοιχτού Κώδικα & Άδειες

Aspose.Cells FOSS για Rust έχει άδεια MIT. Ο πλήρης κώδικας πηγής είναι διαθέσιμος στο GitHub, και η άδεια επιτρέπει εμπορική χρήση, τροποποίηση και αναδιανομή.

Ξεκινώντας

Σχετικοί πόροι