Introducción

Aspose.Cells FOSS para Rust expone su funcionalidad a través del crate aspose-cells-foss-rust, centrado en un conjunto compacto de tipos principales: Workbook, Worksheet, Cells, Cell y DocumentProperties, cada uno con los accesores *Mut correspondientes para escritura. Este artículo es un recorrido sistemático por esa superficie central de API, no una característica aislada, sino los fundamentos que toda aplicación construida sobre el crate termina usando: crear y nombrar hojas de cálculo, leer y escribir valores de celda tipados, establecer metadatos del documento, proteger y ocultar hojas de cálculo, dimensionar filas y columnas, combinar celdas y cargar archivos de forma defensiva.

El crate tiene licencia MIT y está dirigido a la edición 2021 de Rust. Casi toda operación que puede fallar devuelve Result<_, CellsError>, por lo que el manejo de errores con el operador ? se aplica en los ejemplos a continuación de la misma manera que lo hace en código real. El crate incorpora un pequeño conjunto de dependencias en tiempo de ejecución en lugar de reimplementar todo desde cero — chrono para valores de fecha y hora, zip para el formato de paquete XLSX, roxmltree para el análisis de XML, serde_json para datos estructurados, sha2 y base64 para hashing y codificación, y getrandom para generación de aleatoriedad.

Cada sección a continuación cubre una área de API con los tipos y métodos concretos involucrados, respaldada por ejemplos funcionales en Rust extraídos del código de ejemplo propio del crate.

Características clave

Fundamentos del libro de trabajo y la hoja de cálculo

Un Workbook comienza vacío con Workbook::new(), conteniendo una hoja de cálculo llamada "Sheet1". Hojas adicionales se obtienen mediante WorksheetsMut::add(name), que devuelve el índice de la nueva hoja. Worksheets/WorksheetsMut también rastrean qué hoja está activa a través de active_sheet_name() y 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());

Valores de Celda Tipados y Fórmulas

Cells/CellsMut referencian una celda mediante referencia al estilo A1 (get("B3")) o mediante índice de fila/columna (get_by_index(row, column)). Cada Cell/CellMut acepta valores tipados a través de setters dedicados, por lo que no se requieren conversiones basadas en cadenas, y las fórmulas se escriben junto con un valor en caché para que el archivo se abra con resultados correctos antes de cualquier recalculación.

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

Propiedades del Documento

Workbook::get_document_properties_mut() accede a un objeto DocumentProperties que cubre los campos de metadatos comunes (título, asunto, autor, palabras clave, categoría, empresa), además de un CoreDocumentProperties anidado (get_core_mut()) y ExtendedDocumentProperties (get_extended_mut()) para los conjuntos de propiedades centrales/extensas de 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());

Protección y Visibilidad de la Hoja de Cálculo

Un Worksheet puede ocultarse con set_visibility_type(VisibilityType::Hidden), teñirse con set_tab_color y bloquearse con protect() más un objeto WorksheetProtection (a través de get_protection_mut()) que controla exactamente qué acciones — formatear celdas, seleccionar celdas bloqueadas, etc. — permanecen disponibles una vez activada la protección.

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

Filas, Columnas y Celdas Combinadas

CellsMut expone get_rows()/get_columns() como RowsMut/ColumnsMut para dimensionar y ocultar filas y columnas individuales, y merge(first_row, first_column, total_rows, total_columns) para combinar un rango de celdas en una única región combinada.

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

Carga defensiva con diagnósticos

Los archivos XLSX del mundo real no siempre están bien formados. LoadOptions expone banderas de reparación (try_repair_package, try_repair_xml), y Workbook::get_load_diagnostics() devuelve un objeto LoadDiagnostics cuyo issues() informa lo que el cargador encontró y reparó.

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

Inicio rápido

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

Una sesión mínima que toca lo básico de libro de trabajo, hoja de cálculo, celda y propiedad de documento:

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

Formatos admitidos

FormatoExtensiónLeerEscribir
XLSX.xlsx✓✓

XLSX es el enfoque de la versión actual: lectura y escritura de ida y vuelta completas mediante Workbook::load_xlsx y Workbook::save, con los enums LoadFormat y SaveFormat que controlan la selección explícita de formato.

Código abierto y licencias

Aspose.Cells FOSS para Rust está bajo licencia MIT. El código fuente completo está disponible en GitHub, y la licencia permite el uso comercial, la modificación y la redistribución.

Primeros pasos

Recursos relacionados