跳到主要內容

用 Rust 或 Python 讀取、寫入與編輯 XLSX 檔案。

CrabXL 的 Rust crate 與 Python 套件共用同一個 Rust 引擎。Python 套件遵循 openpyxl 的用法。讀取大型工作表時,記憶體用量有上限。儲存編輯時,沒有修改的部分會原樣保留。

安裝

請使用 Rust 1.88 或更新版本。

程式碼範例

在 Rust 中,列號與欄號從 0 開始。在 Python 中,支援的呼叫遵循 openpyxl。相容的 openpyxl 程式碼,只要改一行 import 就能使用。

use crabxl::{CellAddress, CellValue, SaveOptions, WorkbookEditor, WorkbookReader};

fn main() -> crabxl::Result<()> {
    // Stream the cells that are present, row by row
    let mut workbook = WorkbookReader::open("input.xlsx")?;
    let mut rows = workbook.rows("Sheet1")?;
    while let Some(row) = rows.next_row()? {
        for cell in row.cells {
            println!("{:?}: {:?}", cell.address, cell.value);
        }
    }

    // Edit one value and keep everything else as it was
    let mut editor = WorkbookEditor::open("input.xlsx")?;
    editor.set_value("Sheet1", CellAddress::new(0, 0)?, CellValue::Integer(42))?;
    editor.save_path("output.xlsx", SaveOptions::default())?;
    Ok(())
}

功能

#功能說明
串流讀取

只讀取檔案中實際存在的儲存格。以固定大小的批次讀取,並保留每個儲存格的位置。若要把整張工作表留在記憶體中,請使用 read_sheet。

只讀取檔案中實際存在的儲存格。以固定大小的批次讀取,並保留每個儲存格的位置。若要把整張工作表留在記憶體中,請使用 read_sheet。
循序寫入

一次寫入一列,建立新的活頁簿。在 Python 的 write only 模式下,資料列會先寫入暫存檔,而且只能儲存一次。

一次寫入一列,建立新的活頁簿。在 Python 的 write only 模式下,資料列會先寫入暫存檔,而且只能儲存一次。
編輯既有檔案

修改支援的儲存格值後儲存。沒有修改的部分會保留原本的位元組。

修改支援的儲存格值後儲存。沒有修改的部分會保留原本的位元組。
讀取精確的值

精確讀取整數、文字、RTF 文字、日期、樣式與公式紀錄。

精確讀取整數、文字、RTF 文字、日期、樣式與公式紀錄。
控制記憶體

設定記憶體上限,或使用 Auto。Auto 會自動選擇串流或完整載入。共用字串可以放在 RAM 或磁碟上。

設定記憶體上限,或使用 Auto。Auto 會自動選擇串流或完整載入。共用字串可以放在 RAM 或磁碟上。
選擇壓縮等級

Deflate 壓縮等級可選 0 至 9,預設為 6。預設的後端是以 Rust 撰寫的 zlib-rs,也可以選用原生 zlib。

Deflate 壓縮等級可選 0 至 9,預設為 6。預設的後端是以 Rust 撰寫的 zlib-rs,也可以選用原生 zlib。
從 openpyxl 移轉

相容的程式碼只要寫 import crabxl as openpyxl。執行時不需要安裝 openpyxl。

相容的程式碼只要寫 import crabxl as openpyxl。執行時不需要安裝 openpyxl。

效能測試

這項測試讀取一張 10 欄的數值工作表。不論資料量多大,記憶體峰值都維持在約 1.5 MiB。在 100 萬列時,速度約為 openpyxl 的 8.1 倍,但約比 calamine 慢 2.2 倍。

100 萬列 × 10 欄

記憶體峰值
  • CrabXL1.50 MiB
  • openpyxl119.25 MiB
  • calamine688.43 MiB
執行時間
  • CrabXL6.943 秒
  • openpyxl56.569 秒
  • calamine3.103 秒
完整讀取數值資料時的執行時間與記憶體峰值中位數
列數CrabXLopenpyxlcalamine
執行時間記憶體峰值執行時間記憶體峰值執行時間記憶體峰值
10,0000.072 秒1.52 MiB0.538 秒33.80 MiB0.032 秒8.54 MiB
100,0000.713 秒1.54 MiB4.382 秒41.68 MiB0.316 秒70.42 MiB
1,000,0006.943 秒1.50 MiB56.569 秒119.25 MiB3.103 秒688.43 MiB

測試條件:Rust 1.88 release 建置、Python 3.12、read only 模式的 openpyxl 3.1.5,以及 calamine 0.36.1。測試機為 Linux x86_64,CPU 是 AMD EPYC 9V74。每種資料量先暖機 1 次,再正式測量 5 次。執行時間包含程序啟動。本測試不包含文字、樣式、公式、編輯與語言綁定。

查看原始數據與測試方法

開發狀態

遇到不支援的操作時,CrabXL 會回傳錯誤。在正式環境使用某項功能前,請先查看開發藍圖。

查看開發藍圖

已支援

  • 串流讀取與整張工作表的快照
  • 循序寫入與 write only 模式
  • 保留未修改部分的儲存格編輯
  • 支援操作的 openpyxl 式呼叫

尚未支援

  • 公式計算
  • 與 openpyxl 完全相容
  • 完整的樣式與 RTF 文字物件 API
  • 進階工作表功能與部分結構編輯

支援平台

Rust
Rust 1.88 或更新版本
Python
CPython 3.11 至 3.15,支援 Linux x86_64 與 ARM64、Windows x86_64,以及 Intel 和 Apple Silicon 的 macOS