소개
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"라는 이름의 워크시트 하나를 가지고 있습니다. 추가 워크시트는 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는 전용 setter를 통해 타입된 값을 받아들이므로 문자열 기반 변환이 필요 없으며, 수식은 캐시된 값과 함께 기록되어 파일이 재계산 전에 올바른 결과로 열립니다.
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());
워크시트 보호 및 가시성
A 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)를 사용해 셀 범위를 하나의 병합 영역으로 결합합니다.
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에서 이용 가능하며, 라이선스는 상업적 사용, 수정 및 재배포를 허용합니다.
