Pendahuluan

Aspose.Cells FOSS untuk Rust mengekspos fungsionalitasnya melalui crate aspose-cells-foss-rust, berfokus pada sekumpulan tipe inti yang kompak: Workbook, Worksheet, Cells, Cell, dan DocumentProperties, masing-masing dengan accessor *Mut yang cocok untuk akses menulis. Posting ini merupakan tur sistematis dari antarmuka API inti — bukan satu fitur sempit, melainkan dasar-dasar yang digunakan oleh setiap aplikasi yang dibangun di atas crate: membuat dan memberi nama worksheet, membaca dan menulis nilai sel bertipe, mengatur metadata dokumen, melindungi dan menyembunyikan worksheet, mengatur ukuran baris dan kolom, menggabungkan sel, serta memuat file secara defensif.

Crate ini berlisensi MIT dan menargetkan Rust edition 2021. Hampir setiap operasi yang dapat gagal mengembalikan Result<_, CellsError>, sehingga penanganan error dengan operator ? berjalan melalui contoh di bawah dengan cara yang sama seperti dalam kode nyata. Crate ini menarik sekumpulan kecil dependensi runtime alih-alih mengimplementasikan semuanya dari awal — chrono untuk nilai tanggal-waktu, zip untuk format paket XLSX, roxmltree untuk parsing XML, serde_json untuk data terstruktur, sha2 dan base64 untuk hashing dan encoding, serta getrandom untuk randomness.

Setiap bagian di bawah ini membahas satu area API dengan tipe konkret dan metode yang terlibat, didukung oleh contoh Rust yang berfungsi yang diambil dari kode contoh crate itu sendiri.

Fitur Utama

Fundamental Workbook dan Worksheet

Sebuah Workbook dimulai kosong dengan Workbook::new(), membawa satu worksheet bernama "Sheet1". Lembar tambahan diperoleh dari WorksheetsMut::add(name), yang mengembalikan indeks lembar baru. Worksheets/WorksheetsMut juga melacak lembar mana yang aktif melalui active_sheet_name() dan 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());

Nilai Sel Bertipe dan Rumus

Cells/CellsMut mengakses sel dengan referensi gaya A1 (get("B3")) atau dengan indeks baris/kolom (get_by_index(row, column)). Setiap Cell/CellMut menerima nilai bertipe melalui setter khusus, sehingga tidak diperlukan konversi yang berbasis string, dan rumus ditulis bersama nilai cache sehingga file dibuka dengan hasil yang benar sebelum perhitungan ulang apa pun.

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

Properti Dokumen

Workbook::get_document_properties_mut() mencapai objek DocumentProperties yang mencakup bidang metadata umum (title, subject, author, keywords, category, company), serta CoreDocumentProperties bersarang (get_core_mut()) dan ExtendedDocumentProperties (get_extended_mut()) untuk set properti inti/ekstensi 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());

Proteksi dan Visibilitas Lembar Kerja

Sebuah Worksheet dapat disembunyikan dengan set_visibility_type(VisibilityType::Hidden), diwarnai dengan set_tab_color, dan dikunci dengan protect() plus objek WorksheetProtection (melalui get_protection_mut()) yang mengontrol secara tepat tindakan mana — memformat sel, memilih sel terkunci, dan sebagainya — yang tetap tersedia setelah proteksi diaktifkan.

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

Baris, Kolom, dan Sel yang Digabung

CellsMut mengekspos get_rows()/get_columns() sebagai RowsMut/ColumnsMut untuk mengatur ukuran dan menyembunyikan baris serta kolom individual, serta merge(first_row, first_column, total_rows, total_columns) untuk menggabungkan rentang sel menjadi satu wilayah yang digabung.

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

Pemuatan Defensif dengan Diagnostik

File XLSX dunia nyata tidak selalu terbentuk dengan baik. LoadOptions menampilkan flag perbaikan (try_repair_package, try_repair_xml), dan Workbook::get_load_diagnostics() mengembalikan objek LoadDiagnostics yang issues() melaporkan apa yang ditemukan dan diperbaiki oleh pemuat.

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

Panduan Cepat

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

Sesi minimal yang menyentuh dasar-dasar workbook, worksheet, cell, dan 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(())
}

Format yang Didukung

FormatEkstensiBacaTulis
XLSX.xlsx✓✓

XLSX menjadi fokus rilis saat ini: pembacaan dan penulisan round-trip penuh melalui Workbook::load_xlsx dan Workbook::save, dengan enum LoadFormat dan SaveFormat yang mengatur pemilihan format secara eksplisit.

Sumber Terbuka & Lisensi

Aspose.Cells FOSS untuk Rust berlisensi MIT. Kode sumber lengkap tersedia di GitHub, dan lisensi tersebut mengizinkan penggunaan komersial, modifikasi, serta redistribusi.

Memulai

Sumber Daya Terkait