소개
Aspose.Cells FOSS for C++는 두 개의 레이어로 구성됩니다. 대부분의 코드는 파사드 레이어를 사용합니다: Workbook, Worksheet, Cell, Style이며, 이는 이 플랫폼에 대한 발표 및 기능 포스트가 다루는 내용입니다. 그 아래에는 Aspose::Cells_FOSS::Core 네임스페이스에 위치한 두 번째 레이어가 있으며, 순수 데이터 레코드 — WorkbookModel, WorksheetModel, CellRecord, StyleValue 및 약 4십여 개의 관련 *Model 및 *Value 타입으로 구성됩니다. 이러한 레코드들은 실제 파싱된 스프레드시트 상태를 보유합니다: CellAddress을 키로 하는 셀 값, StyleValue 형태의 스타일 속성, 워크북 및 워크시트 설정, 페이지 설정, 필터 및 로드 진단 정보. 파사드 클래스는 자체적으로 상태를 저장하지 않고 이 레이어를 읽고 씁니다.
두 레이어 사이의 다리는 명시적이며 공개되어 있습니다. Workbook::GetModel()은 Core::WorkbookModel을 반환하고, Worksheet::GetModel()은 Core::WorksheetModel을 반환하며, Style::ToCore() / Style::FromCore()는 가변 Style을 Core::StyleValue로 변환하고 그 반대도 수행합니다. DocumentProperties::GetModel()와 ExtendedDocumentProperties::GetModel()는 문서 메타데이터에 대해서도 동일하게 동작합니다. 일반적인 셀 편집 API보다 제한된 경우에 소비자는 이 레이어에 직접 접근합니다: 워크북이 로드되거나 저장될 때 기록된 DiagnosticBag을 검사하거나, 워크북 수준의 StyleRepository을 통해 스타일을 정규화하거나, Cell / Row 래퍼 객체 대신 순수 데이터 셀 및 행 레코드를 직접 작업합니다.
여기서 설명하는 모든 내용은 C++용 Aspose.Cells FOSS의 나머지 부분과 동일한 MIT 라이선스의 종속성 없는 소스 트리에서 제공되며, CMake로 빌드되어 사전 컴파일된 바이너리가 아니라 헤더와 소스로 포함됩니다. 아직 파사드 API를 사용해 본 적이 없다면 먼저 Workbook/Worksheet/Cell 기능 포스트부터 시작하십시오 — 이 포스트는 그 기반을 전제로 하며 하부에 위치한 내용을 중점적으로 다룹니다.
포함된 내용
Workbook 및 Worksheet 모델 트리
Core::WorkbookModel은 루트 레코드입니다. GetWorksheets()은 std::deque<WorksheetModel>를 반환하고, GetSettings()은 WorkbookSettingsModel를, GetProperties()은 WorkbookPropertiesModel를, GetDocumentProperties()은 DocumentPropertiesModel를, GetDiagnostics()은 DiagnosticBag를, GetStyles()은 StyleRepository를, GetSharedStrings()은 SharedStringRepository를, GetDefaultStyle() / SetDefaultStyle()은 StyleValue를 반환합니다. 또한 GetDefinedNames()에서 온 GetActiveSheetIndex() 및 std::vector<DefinedNameModel>를 추적합니다. Workbook::GetModel()은 이 레코드의 진입점입니다.
Core::WorksheetModel은 Worksheet::GetModel()을 통해 접근하며, 셀을 std::unordered_map<CellAddress, CellRecord> (via GetCells()) 로, 행을 std::unordered_map<int, RowModel> (via GetRows()) 로, 열 범위를 std::vector<ColumnRangeModel> (via GetColumns()) 로, 병합된 범위를 std::vector<MergeRegion> (via GetMergeRegions()) 로 저장합니다. 또한 GetHyperlinks(), GetValidations(), GetConditionalFormattings(), GetPageSetup(), GetView(), GetProtection(), GetAutoFilter(), GetTabColor(), 그리고 GetVisibility()을(를) 포함하고 있으며 (이는 SheetVisibility 값: Visible, Hidden, 또는 VeryHidden) 입니다.
CellAddress은 해당 셀 맵에 사용되는 해시 가능한 키 타입입니다. A1 스타일 텍스트를 0 기반 행/열 인덱스로 파싱하고 다시 역변환합니다 — 이것은 이 클러스터에서 FOSS 저장소에 직접 테스트 커버리지가 있는 몇 안 되는 클래스 중 하나입니다:
#include "aspose/cells_foss/core/CellAddress.h"
using namespace Aspose::Cells_FOSS;
Core::CellAddress parsed = Core::CellAddress::Parse("AB3");
// parsed.GetRowIndex() == 2 (zero-based row index)
// parsed.GetColumnIndex() == 27 (zero-based column index)
// parsed.ToString() == "AB3"
CellRecord은 셀의 CellValue, CellValueKind, 선택적 수식 문자열, StyleValue, 그리고 실제로 기록된 셀과 행이나 열 기본값에 의해 존재하게 된 셀을 구분하는 GetIsExplicitlyStored() 플래그를 보유합니다. RowModel는 선택적 높이, 숨김 플래그, 선택적 스타일 인덱스를 포함하고; ColumnRangeModel은 동일한 세 항목에 더해 적용되는 최소/최대 열 범위를 포함합니다. MergeRegion은 첫 행/첫 열/전체 행/전체 열 사각형을 나타내는 단순 구조입니다.
스타일 데이터를 단순 값으로
StyleValue은 변경 가능한 Style 파사드에 대응하는 Core 버전입니다 — Style::ToCore()은 Style를 StyleValue으로 변환하고, Style::FromCore()은 StyleValue으로부터 Style을 생성합니다. 이는 GetFont() (FontValue), GetPattern() (FillPatternKind), GetForegroundColor() / GetBackgroundColor() (ColorValue), GetBorders() (BordersValue), GetAlignment() (AlignmentValue), GetProtection() (ProtectionValue), 그리고 GetNumberFormat() (NumberFormatValue)을 그룹화하며, 정적 StyleValue::Default()와 Clone()도 포함합니다. FontValue는 Font의 각 필드—name, size, bold, italic, underline, strike-through, 그리고 ColorValue—를 그대로 반영합니다. ColorValue 자체는 순수 ARGB 튜플 (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode())이며, 파사드 Color 클래스와 달리 FromArgb() 스타일 팩토리를 제공하지 않으므로 ColorValue은 일반적으로 직접 생성하기보다 기존 스타일에서 얻습니다.
BordersValue은 다섯 개의 BorderSideValue 멤버—left, right, top, bottom, diagonal—를 보유하며, 각각 BorderStyle 열거값과 ColorValue을 짝지어 있습니다. AlignmentValue는 가로 및 세로 정렬, 텍스트 자동 줄바꿈, 들여쓰기 수준, 텍스트 회전, 축소 맞춤, 그리고 읽기 순서를 모델링합니다. ProtectionValue와 NumberFormatValue은 셀 보호 플래그와 Style이 노출하는 숫자 형식 id/사용자 정의 문자열 쌍을 지원합니다.
StyleRepository은 WorkbookModel::GetStyles()을 통해 접근할 수 있으며, 하나의 연산 Normalize(style) -> StyleValue를 노출합니다. 워크북은 로드 및 저장 시 동일한 StyleValue 레코드를 중복 생성하지 않고 동등한 스타일을 내부적으로 인터닝하기 위해 이를 사용합니다 — 현재 API 표면에서는 인덱스 기반 조회가 가능한 범용 스타일 캐시가 아닙니다.
문서 속성 및 워크북 수준 설정
DocumentPropertiesModel은(는) GetCore()을(를) 그룹화합니다 (CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status, 및 created/modified 타임스탬프) 및 GetExtended() (ExtendedDocumentPropertiesModel: application, app version, company, manager, doc security, hyperlink base, 그리고 scale-crop / links-up-to-date / shared-doc 플래그). DocumentProperties::GetModel()과(와) ExtendedDocumentProperties::GetModel()은(는) 파사드 클래스와 이러한 레코드 사이를 연결합니다.
WorkbookPropertiesModel은(는) WorkbookProperties을(를) 반영합니다 — 코드명, show-objects, filter privacy, backup-file 및 관련 플래그 — 그리고 WorkbookProtectionModel(lock structure/windows/revision, workbook 및 revisions 비밀번호), WorkbookViewModel(윈도우 위치와 크기, 첫 번째 표시 시트, 스크롤바 및 시트 탭 가시성, 탭 비율, 최소화 상태, 자동 필터 날짜 그룹화), 그리고 CalculationPropertiesModel(계산 모드, 반복 설정, 전체 정밀도, 동시 계산)를 중첩합니다. WorkbookSettingsModel는 DateSystem 값(Windows1900 또는 Mac1904)과 표시 문화권을 포함합니다 — 이는 WorkbookSettings::GetDate1904() / GetCulture()의 모델 수준 대응물입니다. 이 그룹의 대부분 *Model 타입은 CopyFrom(source)와 HasStoredState()을 노출하며, 직렬화 프로그램은 이를 사용해 XML을 쓰기 전에 명시적으로 설정된 값과 기본값이 설정되지 않은 값을 구분합니다.
워크시트 기능 모델
WorksheetProtectionModel은(는) WorksheetProtection 필드를 필드별로 반영하고 저장된 비밀번호 필드 — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — 를 추가합니다. 이는 파사드 WorksheetProtection가 직접 노출하지 않습니다. WorksheetViewModel은(는) 그리드 라인, 헤더, 제로 가시성, 오른쪽에서 왼쪽으로 레이아웃, 그리고 확대/축소 비율을 보유합니다. PageSetupModel는 PageMarginsModel(왼쪽/오른쪽/위/아래/헤더/푸터 여백을 double로 지정), PrintOptionsModel(그리드 라인, 헤더, 수평 및 수직 중앙 정렬), 그리고 HeaderFooterModel(좌/중/우 헤더 및 푸터 텍스트)를 중첩하며, 종이 크기, 방향, 스케일, 폭/높이에 맞추기, 인쇄 영역, 인쇄 제목 행/열, 그리고 페이지 구분 벡터와 함께 제공합니다.
AutoFilterModel은(는) 범위 문자열, std::vector<FilterColumnModel>, 그리고 AutoFilterSortStateModel를 보유합니다. FilterColumnModel은(는) 차례로 AutoFilterColorFilterModel, AutoFilterDynamicFilterModel, AutoFilterTop10Model을(를) 중첩하고, 필터 값 문자열의 단순 목록과 std::vector<AutoFilterCustomFilterModel>을(를) 추가합니다. ConditionalFormattingModel은(는) std::vector<CellArea>와 std::vector<FormatConditionModel>을(를) 짝지으며 — 각 조건은 유형, 연산자, 수식, 색상 스케일/데이터 바/아이콘 집합 필드, 그리고 결과 형식에 대한 StyleValue을(를) 포함합니다. ValidationModel와 HyperlinkModel은(는) Validation와 Hyperlink 파사드를 단순 레코드로 반영하고, DefinedNameModel은(는) DefinedName을(를) 반영합니다. SheetVisibility은(는) Worksheet::GetVisibilityType() 뒤에 있는 모델 레이어 열거형입니다.
이 레코드들이 지원하는 파사드 기능 중 일부 — 특히 AutoFilter와 ConditionalFormattingCollection — 는 이번 릴리스에서 여전히 활발히 개발 중임을 제품 문서에서 언급하고 있습니다. 위의 구조를 모델 및 직렬화 프로그램이 기반으로 하는 구조적 목표로 보되, 오늘 저장된 워크북을 통해 모든 필드가 라운드트립된다는 보장은 아닙니다.
진단 및 공유 상태
DiagnosticBag은(는) WorkbookModel::GetDiagnostics()을 통해 접근할 수 있으며, DiagnosticEntry 레코드를 수집합니다 — 각각 GetCode(), GetSeverity()(DiagnosticSeverity: Warning, Recoverable, 또는 LossyRecoverable), GetMessage(), GetRepairApplied() 플래그, 및 GetDataLossRisk() 플래그를 가지고 있으며 — 워크북이 파싱되거나 직렬화되는 동안 생성됩니다. 이는 Workbook::GetLoadDiagnostics()와 함께 실행되며, 해당 파사드 수준의 LoadDiagnostics/LoadIssue 타입은 동일한 DiagnosticSeverity 열거형을 공유합니다; LoadIssue 래퍼 대신 원시 모델 레코드가 필요한 코드는 워크북 모델의 GetDiagnostics()을 통해 접근합니다.
SharedStringRepository은(는) xlsx shared-strings 테이블을 지원합니다: GetValues()은(는) interned string vector를 반환하고, TryGetValue(index, value)은(는) 인덱스를 텍스트로 다시 해석하며, Intern(value)은(는) 항목을 추가하거나 재사용합니다 — SaveOptions::SetUseSharedStrings(true)가 설정될 때 내부적으로 사용됩니다. DateSerialConverter은(는) DateTime과 Excel이 셀에 저장하는 OLE 스타일 일련 번호 사이를 변환하며, DateSystem을 받아 1900 및 1904 기반 워크북이 동일한 달력 날짜로 디코딩되도록 합니다.
빠른 시작
라이브러리를 CMake 프로젝트에 서브디렉터리로 추가하고, 라이브러리가 정의하는 타깃을 링크합니다:
add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)
target_link_libraries(MyApp PRIVATE Aspose.Cells.Foss.Cpp)
아래 예제는 파사드를 통해 셀을 기록한 다음, 기본 모델에 접근하여 진단 bag 및 CellAddress 파싱을 수행합니다 — 이와 동일한 작업을 WorksheetModel::GetCells()이(가) 내부적으로 셀 맵의 키로 사용합니다:
#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
#include "aspose/cells_foss/Cell.h"
#include "aspose/cells_foss/core/CellAddress.h"
#include <iostream>
using namespace Aspose::Cells_FOSS;
int main() {
Workbook workbook;
Worksheet& sheet = workbook.GetWorksheets()[0];
sheet.SetName("Report");
sheet.GetCells()["A1"].PutValue("Total");
workbook.Save("report.xlsx");
Core::CellAddress address = Core::CellAddress::Parse("A1");
std::cout << "Row: " << address.GetRowIndex()
<< " Column: " << address.GetColumnIndex() << "\n";
for (const auto& entry : workbook.GetModel().GetDiagnostics().GetEntries()) {
std::cout << "Diagnostic: " << entry.GetMessage() << "\n";
}
return 0;
}
지원되는 형식
| 형식 | 확장자 | 읽기 | 쓰기 |
|---|---|---|---|
| XLSX | .xlsx | ✓ | ✓ |
여기서 설명하는 모델 계층은 xlsx 리더와 라이터가 작동하는 인메모리 표현이며, 라이브러리 나머지 부분이 지원하는 Xlsx 가져오기/내보내기를 제외하고 추가적인 파일 형식에 묶여 있지 않습니다.
오픈 소스 및 라이선스
Aspose.Cells FOSS for C++은 MIT 라이선스를 따릅니다. 이 게시물에서 언급된 Aspose::Cells_FOSS::Core 모델 헤더를 포함한 소스 코드는 GitHub에 있습니다; 상업적 사용, 수정 및 재배포가 허용됩니다.
