用 Rust 或 Python 讀取、寫入與編輯 XLSX 檔案。
CrabXL 的 Rust crate 與 Python 套件共用同一個 Rust 引擎。Python 套件遵循 openpyxl 的用法。讀取大型工作表時,記憶體用量有上限。儲存編輯時,沒有修改的部分會原樣保留。
安裝
cargo add [email protected]請使用 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 秒
| 列數 | CrabXL | openpyxl | calamine | |||
|---|---|---|---|---|---|---|
| 執行時間 | 記憶體峰值 | 執行時間 | 記憶體峰值 | 執行時間 | 記憶體峰值 | |
| 10,000 | 0.072 秒 | 1.52 MiB | 0.538 秒 | 33.80 MiB | 0.032 秒 | 8.54 MiB |
| 100,000 | 0.713 秒 | 1.54 MiB | 4.382 秒 | 41.68 MiB | 0.316 秒 | 70.42 MiB |
| 1,000,000 | 6.943 秒 | 1.50 MiB | 56.569 秒 | 119.25 MiB | 3.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 次。執行時間包含程序啟動。本測試不包含文字、樣式、公式、編輯與語言綁定。
查看原始數據與測試方法已支援
- 串流讀取與整張工作表的快照
- 循序寫入與 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