Giới thiệu

Aspose.Cells FOSS cho Rust cung cấp chức năng của nó thông qua crate aspose-cells-foss-rust, tập trung vào một tập hợp gọn gàng các kiểu cốt lõi: Workbook, Worksheet, Cells, Cell và DocumentProperties, mỗi kiểu đều có các accessor *Mut tương ứng để ghi dữ liệu. Bài viết này là một chuyến tham quan có hệ thống về bề mặt API cốt lõi — không chỉ một tính năng hẹp, mà là những nền tảng mà mọi ứng dụng xây dựng trên crate này đều sử dụng: tạo và đặt tên cho các worksheet, đọc và ghi các giá trị ô có kiểu, thiết lập siêu dữ liệu tài liệu, bảo vệ và ẩn các worksheet, điều chỉnh kích thước hàng và cột, hợp nhất ô, và tải tập tin một cách an toàn.

Crate này được cấp phép MIT và nhắm tới Rust edition 2021. Hầu hết các thao tác có thể thất bại đều trả về Result<_, CellsError>, vì vậy việc xử lý lỗi với toán tử ? diễn ra trong các ví dụ dưới đây giống như trong mã thực tế. Crate này kéo vào một tập hợp nhỏ các phụ thuộc thời gian chạy thay vì triển khai lại mọi thứ từ đầu — chrono cho các giá trị ngày-giờ, zip cho định dạng gói XLSX, roxmltree cho việc phân tích XML, serde_json cho dữ liệu có cấu trúc, sha2 và base64 cho hàm băm và mã hoá, và getrandom cho tính ngẫu nhiên.

Mỗi phần dưới đây đề cập đến một lĩnh vực của API cùng với các kiểu và phương thức cụ thể liên quan, được hỗ trợ bằng các ví dụ Rust hoạt động lấy từ mã mẫu của crate.

Các tính năng chính

Các nguyên tắc cơ bản của Sổ làm việc và Worksheet

Một Workbook bắt đầu trống với Workbook::new(), chứa một worksheet có tên "Sheet1". Các sheet bổ sung được tạo bằng WorksheetsMut::add(name), hàm này trả về chỉ số của sheet mới. Worksheets/WorksheetsMut cũng theo dõi sheet đang hoạt động thông qua active_sheet_name() và 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());

Giá trị ô đã gõ và công thức

Cells/CellsMut định vị một ô bằng tham chiếu kiểu A1 (get("B3")) hoặc bằng chỉ số hàng/cột (get_by_index(row, column)). Mỗi Cell/CellMut chấp nhận các giá trị đã gõ qua các setter chuyên dụng, vì vậy không cần chuyển đổi kiểu chuỗi, và các công thức được ghi cùng với giá trị đã cache để tệp mở ra với kết quả đúng trước bất kỳ việc tính lại nào.

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

Thuộc tính tài liệu

Workbook::get_document_properties_mut() truy cập một đối tượng DocumentProperties bao gồm các trường siêu dữ liệu chung (tiêu đề, chủ đề, tác giả, từ khóa, thể loại, công ty), cộng với một CoreDocumentProperties lồng nhau (get_core_mut()) và ExtendedDocumentProperties (get_extended_mut()) cho các bộ thuộc tính lõi/mở rộng của 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());

Bảo vệ và Hiển thị Bảng tính

Một Worksheet có thể được ẩn bằng set_visibility_type(VisibilityType::Hidden), tô màu bằng set_tab_color, và khóa bằng protect() cùng với một đối tượng WorksheetProtection (thông qua get_protection_mut()) để kiểm soát chính xác những hành động — định dạng ô, chọn các ô đã khóa, v.v. — vẫn khả dụng khi bảo vệ được bật.

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

Hàng, Cột và Ô đã Gộp

CellsMut cung cấp get_rows()/get_columns() dưới dạng RowsMut/ColumnsMut để điều chỉnh kích thước và ẩn các hàng và cột riêng lẻ, và merge(first_row, first_column, total_rows, total_columns) để kết hợp một dải ô thành một vùng đã gộp.

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

Tải phòng thủ có chẩn đoán

Các tệp XLSX thực tế không phải lúc nào cũng chuẩn. LoadOptions cung cấp các cờ sửa chữa (try_repair_package, try_repair_xml), và Workbook::get_load_diagnostics() trả về một đối tượng LoadDiagnostics mà issues() báo cáo những gì bộ tải đã tìm thấy và sửa chữa.

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

Bắt đầu nhanh

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

Một phiên tối thiểu đề cập đến các khái niệm cơ bản của workbook, worksheet, cell và 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(())
}

Định dạng được hỗ trợ

Định dạngPhần mở rộngĐọcGhi
XLSX.xlsx✓✓

XLSX là trọng tâm của bản phát hành hiện tại: đọc và ghi vòng tròn đầy đủ thông qua Workbook::load_xlsx và Workbook::save, với các enum LoadFormat và SaveFormat điều khiển việc lựa chọn định dạng một cách rõ ràng.

Mã nguồn mở & Giấy phép

Aspose.Cells FOSS cho Rust được cấp phép MIT. Mã nguồn đầy đủ có sẵn trên GitHub, và giấy phép cho phép sử dụng thương mại, sửa đổi và phân phối lại.

Bắt đầu

Tài nguyên liên quan