Einleitung
Aspose.Cells FOSS für Rust stellt seine Funktionalität über das aspose-cells-foss-rust-Crate bereit, das sich auf einen kompakten Satz von Kerntypen konzentriert: Workbook, Worksheet, Cells, Cell und DocumentProperties, jeweils mit passenden *Mut-Accessoren für Schreibzugriff. Dieser Beitrag ist eine systematische Tour durch die Kern-API-Oberfläche – nicht nur ein enges Feature, sondern die Grundlagen, die jede auf dem Crate basierende Anwendung letztlich nutzt: Arbeitsblätter erstellen und benennen, typisierte Zellwerte lesen und schreiben, Dokument-Metadaten setzen, Arbeitsblätter schützen und ausblenden, Zeilen und Spalten dimensionieren, Zellen zusammenführen und Dateien defensiv laden.
Das Crate ist unter der MIT-Lizenz veröffentlicht und zielt auf die Rust-Edition 2021 ab. Fast jede fehlbare Operation gibt Result<_, CellsError> zurück, sodass die Fehlerbehandlung mit dem ?-Operator in den nachfolgenden Beispielen genauso abläuft wie im realen Code. Das Crate zieht eine kleine Menge von Laufzeit-Abhängigkeiten nach, anstatt alles von Grund auf neu zu implementieren – chrono für Datums- und Zeitwerte, zip für das XLSX-Paketformat, roxmltree für XML-Parsing, serde_json für strukturierte Daten, sha2 und base64 für Hashing und Kodierung sowie getrandom für Zufälligkeit.
Jeder Abschnitt unten behandelt einen Bereich des API mit den konkreten Typen und Methoden, unterstützt durch funktionierende Rust-Beispiele, die aus dem eigenen Beispielcode des Crates stammen.
Wesentliche Merkmale
Workbook- und Worksheet-Grundlagen
Ein Workbook startet leer mit Workbook::new() und enthält ein Arbeitsblatt mit dem Namen "Sheet1". Weitere Blätter werden über WorksheetsMut::add(name) erzeugt, das den Index des neuen Blatts zurückgibt. Worksheets/WorksheetsMut verfolgen ebenfalls, welches Blatt aktiv ist, über active_sheet_name() und 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());
Typisierte Zellwerte und Formeln
Cells/CellsMut adressieren eine Zelle mittels A1-Stil-Referenz (get("B3")) oder mittels Zeilen-/Spalten-Index (get_by_index(row, column)). Jede Cell/CellMut akzeptiert typisierte Werte über dedizierte Setter, sodass keine string-basierten Konvertierungen nötig sind, und Formeln werden zusammen mit einem zwischengespeicherten Wert geschrieben, damit die Datei mit korrekten Ergebnissen geöffnet wird, bevor irgendeine Neuberechnung stattfindet.
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());
Dokumenteigenschaften
Workbook::get_document_properties_mut() greift auf ein DocumentProperties-Objekt zu, das die gängigen Metadatenfelder (Titel, Betreff, Autor, Schlüsselwörter, Kategorie, Unternehmen) abdeckt, plus ein verschachteltes CoreDocumentProperties (get_core_mut()) und ExtendedDocumentProperties (get_extended_mut()) für OOXML-Kern-/Erweiterte-Eigenschaftssätze.
{
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());
Blattschutz und Sichtbarkeit
Ein Worksheet kann mit set_visibility_type(VisibilityType::Hidden) verborgen, mit set_tab_color eingefärbt und mit protect() gesperrt werden, plus ein WorksheetProtection-Objekt (über get_protection_mut()), das exakt steuert, welche Aktionen — Zellen formatieren, gesperrte Zellen auswählen usw. — verfügbar bleiben, sobald der Schutz aktiviert ist.
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());
Zeilen, Spalten und zusammengeführte Zellen
CellsMut stellt get_rows()/get_columns() als RowsMut/ColumnsMut zur Größenanpassung und zum Ausblenden einzelner Zeilen und Spalten bereit und merge(first_row, first_column, total_rows, total_columns), um einen Zellbereich zu einer zusammengeführten Region zu kombinieren.
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());
Defensives Laden mit Diagnosen
XLSX-Dateien aus der Praxis sind nicht immer wohlgeformt. LoadOptions stellt Reparatur-Flags (try_repair_package, try_repair_xml) bereit, und Workbook::get_load_diagnostics() gibt ein LoadDiagnostics-Objekt zurück, dessen issues() meldet, was der Lader gefunden und repariert hat.
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());
Schnellstart
# Cargo.toml
[dependencies]
aspose-cells-foss-rust = { git = "https://github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-Rust" }Eine minimale Sitzung, die Arbeitsmappe, Arbeitsblatt, Zelle und Dokument-Eigenschafts-Grundlagen berührt:
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(())
}
Unterstützte Formate
| Format | Erweiterung | Lesen | Schreiben |
|---|---|---|---|
| XLSX | .xlsx | ✓ | ✓ |
XLSX steht im Mittelpunkt der aktuellen Version: vollständiges Round-Trip-Lesen und -Schreiben über Workbook::load_xlsx und Workbook::save, wobei LoadFormat- und SaveFormat-Enums die explizite Formatwahl steuern.
Open Source & Lizenzierung
Aspose.Cells FOSS für Rust ist unter der MIT-Lizenz lizenziert. Der vollständige Quellcode ist verfügbar auf GitHub, und die Lizenz erlaubt kommerzielle Nutzung, Modifikation und Weiterverteilung.
