Introduction

Aspose.Cells FOSS pour Rust expose ses fonctionnalités via la crate aspose-cells-foss-rust, centrée sur un ensemble compact de types de base : Workbook, Worksheet, Cells, Cell et DocumentProperties, chacun doté d’accesseurs *Mut correspondants pour l’écriture. Cet article est une visite systématique de cette interface de base du API — pas une fonctionnalité isolée, mais les fondamentaux que chaque application construite sur la crate utilise finalement : créer et nommer des feuilles de calcul, lire et écrire des valeurs de cellules typées, définir les métadonnées du document, protéger et masquer les feuilles de calcul, dimensionner les lignes et les colonnes, fusionner des cellules et charger les fichiers de manière défensive.

La crate est sous licence MIT et cible l’édition Rust 2021. Pratiquement chaque opération susceptible d’échouer renvoie Result<_, CellsError>, de sorte que la gestion des erreurs avec l’opérateur ? s’applique aux exemples ci-dessous de la même façon qu’au code réel. La crate intègre un petit ensemble de dépendances d’exécution plutôt que de tout réimplémenter à partir de zéro — chrono pour les valeurs date-heure, zip pour le format de paquet XLSX, roxmltree pour l’analyse du XML, serde_json pour les données structurées, sha2 et base64 pour le hachage et l’encodage, et getrandom pour l’aléatoire.

Chaque section ci-dessous couvre un domaine du API avec les types concrets et les méthodes associés, étayée par des exemples Rust fonctionnels tirés du code d’exemple de la crate.

Fonctionnalités clés

Fondamentaux du classeur et de la feuille de calcul

Un Workbook commence vide avec Workbook::new(), contenant une feuille de calcul nommée "Sheet1". Des feuilles supplémentaires sont obtenues via WorksheetsMut::add(name), qui renvoie l’indice de la nouvelle feuille. Worksheets/WorksheetsMut suivent également quelle feuille est active via active_sheet_name() et 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());

Valeurs de cellules typées et formules

Cells/CellsMut adresse une cellule par référence de style A1 (get("B3")) ou par indice de ligne/colonne (get_by_index(row, column)). Chaque Cell/CellMut accepte des valeurs typées via des setters dédiés, de sorte qu’aucune conversion de type chaîne n’est requise, et les formules sont écrites avec une valeur mise en cache afin que le fichier s’ouvre avec les résultats corrects avant tout recalcul.

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

Propriétés du document

Workbook::get_document_properties_mut() atteint un objet DocumentProperties couvrant les champs de métadonnées courants (title, subject, author, keywords, category, company), plus un CoreDocumentProperties imbriqué (get_core_mut()) et ExtendedDocumentProperties (get_extended_mut()) pour les ensembles de propriétés core/extended 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());

Protection et visibilité de la feuille de calcul

Un Worksheet peut être masqué avec set_visibility_type(VisibilityType::Hidden), teinté avec set_tab_color, et verrouillé avec protect() plus un objet WorksheetProtection (via get_protection_mut()) qui contrôle exactement quelles actions — mise en forme des cellules, sélection des cellules verrouillées, etc. — restent disponibles une fois la protection activée.

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

Lignes, colonnes et cellules fusionnées

CellsMut expose get_rows()/get_columns() en tant que RowsMut/ColumnsMut pour dimensionner et masquer les lignes et colonnes individuelles, et merge(first_row, first_column, total_rows, total_columns) pour combiner une plage de cellules en une région fusionnée.

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

Chargement défensif avec diagnostics

Les fichiers XLSX du monde réel ne sont pas toujours bien formés. LoadOptions expose des indicateurs de réparation (try_repair_package, try_repair_xml), et Workbook::get_load_diagnostics() renvoie un objet LoadDiagnostics dont le issues() indique ce que le chargeur a trouvé et réparé.

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

Démarrage rapide

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

Une session minimale abordant les bases du classeur, de la feuille de calcul, de la cellule et des propriétés du document :

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

Formats pris en charge

FormatExtensionLireÉcrire
XLSX.xlsx✓✓

XLSX est le sujet principal de la version actuelle : lecture et écriture complètes en aller-retour via Workbook::load_xlsx et Workbook::save, avec les énumérations LoadFormat et SaveFormat régissant la sélection explicite du format.

Open Source & licences

Aspose.Cells FOSS pour Rust est sous licence MIT. Le code source complet est disponible sur GitHub, et la licence autorise l’utilisation commerciale, la modification et la redistribution.

Premiers pas

Ressources associées