はじめに

Aspose.Cells FOSS for Rust は、その機能を aspose-cells-foss-rust クレートを通じて提供し、コンパクトなコア型セット（Workbook、Worksheet、Cells、Cell、DocumentProperties）を中心としています。各型は書き込み用の対応する *Mut アクセサを持ちます。本稿はそのコア API の表面を体系的に巡るものです——狭い機能だけでなく、クレート上に構築されたすべてのアプリケーションが最終的に利用する基本事項、すなわちワークシートの作成と命名、型付きセル値の読み書き、ドキュメントメタデータの設定、ワークシートの保護と非表示、行と列のサイズ設定、セルの結合、そしてファイルの防御的な読み込みを取り上げます。

このクレートは MIT ライセンスで、Rust エディション 2021 を対象としています。ほぼすべての失敗し得る操作は Result<_, CellsError> を返すため、? 演算子を用いたエラーハンドリングは、以下の例でも実際のコードと同様に行われます。クレートはすべてをゼロから実装するのではなく、少数のランタイム依存関係を取り込んでいます——日付時刻値のための chrono、XLSX パッケージ形式のための zip、XML パースのための roxmltree、構造化データのための serde_json、ハッシュ化とエンコードのための sha2 と base64、そしてランダム性のための getrandom。

以下の各セクションでは、API の特定領域を対象に、具体的な型とメソッドを取り上げ、クレートのサンプルコードから抽出した実用的な Rust の例で裏付けます。

主な機能

ワークブックとワークシートの基礎

Workbook は Workbook::new() で空の状態から始まり、"Sheet1" という名前のワークシートを 1 つ保持します。追加のシートは WorksheetsMut::add(name) から取得でき、新しいシートのインデックスが返されます。Worksheets/WorksheetsMut も active_sheet_name() と 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());

型付きセル値と数式

Cells/CellsMut はセルを A1 形式の参照 (get("B3")) または行/列インデックス (get_by_index(row, column)) で指定します。各 Cell/CellMut は専用のセッターを通じて型付きの値を受け取るため、文字列型の変換は不要です。また、数式はキャッシュされた値と共に記述されるので、再計算が行われる前でもファイルを開くと正しい結果が得られます。

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

ドキュメント プロパティ

Workbook::get_document_properties_mut() は、一般的なメタデータ項目（タイトル、サブジェクト、作成者、キーワード、カテゴリ、会社）を網羅する DocumentProperties オブジェクトに到達し、さらに OOXML コア/拡張プロパティセット用の入れ子になった CoreDocumentProperties（get_core_mut()）と ExtendedDocumentProperties（get_extended_mut()）を提供します。

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

ワークシートの保護と表示

Worksheet は set_visibility_type(VisibilityType::Hidden) で非表示にでき、set_tab_color で色付けでき、protect() と WorksheetProtection オブジェクト（get_protection_mut() を介して）でロックできます。このオブジェクトは、保護が有効になったときに利用可能な操作（セルの書式設定、ロックされたセルの選択など）を正確に制御します。

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

行、列、および結合セル

CellsMut は、個々の行や列のサイズ変更と非表示のために get_rows()/get_columns() を RowsMut/ColumnsMut として公開し、merge(first_row, first_column, total_rows, total_columns) を使用してセルの範囲を 1 つの結合領域にまとめます。

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

診断機能付き防御的読み込み

実際のXLSXファイルは必ずしも正しく構成されているとは限りません。LoadOptionsは修復フラグ（try_repair_package、try_repair_xml）を公開し、Workbook::get_load_diagnostics()はLoadDiagnosticsオブジェクトを返します。そのissues()はローダーが検出し修正した内容を報告します。

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

クイックスタート

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

ワークブック、ワークシート、セル、ドキュメントプロパティの基本に触れる最小限のセッション：

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

サポートされているフォーマット

形式拡張子読み取り書き込み
XLSX.xlsx✓✓

XLSXは現在のリリースの中心です：Workbook::load_xlsx と Workbook::save を介した完全なラウンドトリップの読み書き、LoadFormat と SaveFormat 列挙型が明示的なフォーマット選択を管理します。

オープンソースとライセンス

Aspose.Cells FOSS for Rust は MIT ライセンスです。完全なソースコードは GitHub で入手可能で、ライセンスは商用利用、改変、再配布を許可しています。

はじめに

関連リソース