Introduzione

Aspose.Cells FOSS per Rust espone la sua funzionalità tramite il crate aspose-cells-foss-rust, incentrato su un set compatto di tipi core: Workbook, Worksheet, Cells, Cell e DocumentProperties, ognuno con corrispondenti accessors *Mut per l’accesso in scrittura. Questo post è un tour sistematico di quella superficie core API — non una singola funzionalità, ma i fondamenti che ogni applicazione costruita sul crate finisce per utilizzare: creare e denominare i fogli di lavoro, leggere e scrivere valori di cella tipizzati, impostare i metadati del documento, proteggere e nascondere i fogli di lavoro, dimensionare righe e colonne, unire celle e caricare file in modo difensivo.

Il crate è rilasciato sotto licenza MIT e mira all’edizione Rust 2021. Quasi ogni operazione fallibile restituisce Result<_, CellsError>, quindi la gestione degli errori con l’operatore ? scorre attraverso gli esempi qui sotto allo stesso modo in cui lo fa nel codice reale. Il crate incorpora un piccolo set di dipendenze di runtime anziché reinventare tutto da zero — chrono per i valori data-ora, zip per il formato del pacchetto XLSX, roxmltree per il parsing XML, serde_json per i dati strutturati, sha2 e base64 per l’hashing e la codifica, e getrandom per la casualità.

Ogni sezione qui sotto copre un’area del API con i tipi concreti e i metodi coinvolti, supportata da esempi Rust funzionanti tratti dal codice di esempio del crate.

Caratteristiche Principali

Fondamenti di Workbook e Worksheet

Un Workbook inizia vuoto con Workbook::new(), contenendo un foglio di lavoro denominato "Sheet1". Fogli aggiuntivi provengono da WorksheetsMut::add(name), che restituisce l’indice del nuovo foglio. Worksheets/WorksheetsMut tracciano anche quale foglio è attivo tramite active_sheet_name() e 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());

Valori di cella tipizzati e formule

Cells/CellsMut indicano una cella mediante riferimento in stile A1 (get("B3")) o tramite indice riga/colonna (get_by_index(row, column)). Ogni Cell/CellMut accetta valori tipizzati tramite setter dedicati, quindi non sono necessarie conversioni basate su stringhe, e le formule vengono scritte insieme a un valore memorizzato nella cache in modo che il file si apra con risultati corretti prima di qualsiasi ricalcolo.

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());

Proprietà del documento

Workbook::get_document_properties_mut() raggiunge un oggetto DocumentProperties che copre i campi di metadati comuni (title, subject, author, keywords, category, company), più un CoreDocumentProperties annidato (get_core_mut()) e ExtendedDocumentProperties (get_extended_mut()) per i set di proprietà core/estese 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());

Protezione e visibilità del foglio di lavoro

Un Worksheet può essere nascosto con set_visibility_type(VisibilityType::Hidden), tintato con set_tab_color e bloccato con protect() più un oggetto WorksheetProtection (tramite get_protection_mut()) che controlla esattamente quali azioni — formattare le celle, selezionare le celle bloccate, ecc. — rimangono disponibili una volta attivata la protezione.

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());

Righe, colonne e celle unite

CellsMut espone get_rows()/get_columns() come RowsMut/ColumnsMut per dimensionare e nascondere righe e colonne individuali, e merge(first_row, first_column, total_rows, total_columns) per combinare un intervallo di celle in un’unica regione unita.

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());

Caricamento difensivo con diagnostica

I file XLSX del mondo reale non sono sempre ben formati. LoadOptions espone flag di riparazione (try_repair_package, try_repair_xml), e Workbook::get_load_diagnostics() restituisce un oggetto LoadDiagnostics il cui issues() riporta ciò che il caricatore ha trovato e riparato.

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());

Avvio rapido

# Cargo.toml
[dependencies]
aspose-cells-foss-rust = { git = "https://github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-Rust" }

Una sessione minima che tocca le basi di workbook, worksheet, cell e document-property:

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(())
}

Formati supportati

FormatoEstensioneLeggiScrivi
XLSX.xlsx✓✓

XLSX è il fulcro della versione attuale: lettura e scrittura complete round-trip tramite Workbook::load_xlsx e Workbook::save, con i enums LoadFormat e SaveFormat che governano la selezione esplicita del formato.

Open Source e licenze

Aspose.Cells FOSS per Rust è rilasciato con licenza MIT. Il codice sorgente completo è disponibile su GitHub, e la licenza consente l’uso commerciale, la modifica e la ridistribuzione.

Iniziare

Risorse correlate