직접 읽기/쓰기 API 참조

TXLSDirectReader 및 TXLSDirectWriter 는 전체 워크시트 그리드를 메모리에 보관하지 않고 XLSX 패키지를 처리하므로 시트를 설명하는 API 호출은 해당 스트리밍 단계 이전 또는 도중에 수행해야 합니다

쓰기 수명 주기 및 셀 값

TXLSDirectWriter.BeginFile 또는 BeginStream 은 패키지를 시작하고, 시트 메서드는 한 번에 하나의 워크시트를 정의하며, Finish 는 최종 패키지를 커밋합니다

행과 열은 공개 작성기 표면에서 1부터 시작하며 워크시트 순방향 순서로 제공되어야 합니다

워크시트 패치 수명 주기

BeginPatch는 손대지 않은 패키지 파트를 보존하면서 워크시트 하나를 교체하거나 새 워크시트를 삽입합니다. 초기화가 실패하면 소스 아카이브와 소스 스트림이 즉시 해제됩니다. 여기에는 워크시트 누락, 필수 패키지 파트 누락, 잘못된 아카이브, 대상 생성 실패가 포함됩니다. 소스 파일과 호출자가 소유한 임시 등록의 처리는 여전히 호출자의 책임이고, 해제된 핸들 덕분에 그 소스들을 제거하거나 해제할 수 있습니다

Close와 파괴는 활성 대상이 없거나 패치 마무리가 예외를 던져도 소스 핸들을 해제합니다. 대상 교체가 실패해도 스테이징된 출력은 검사할 수 있도록 유지되며, 초기화 실패 이후에도 writer는 다음 패치나 일반 파일 작업을 시작할 수 있습니다

재사용 가능한 스타일

AddCellStyle 는 변경할 수 없는 패키지 수준 스타일 핸들을 등록하고 CloneCellStyle 은 워크시트 행을 유지하지 않고 새 핸들을 파생합니다

정의된 이름 및 하이퍼링크

AddDefinedName, AddLocalDefinedName, AddDefinedRange및 AddLocalDefinedRange 는 패키지 최종화 전에 통합 문서 또는 시트 로컬 이름을 추가합니다

AddHyperlink, AddHyperlinkRange, AddInternalHyperlink및 AddInternalHyperlinkRange 는 하나의 셀 또는 범위에 대한 외부 관계 또는 내부 시트 위치를 생성합니다

데이터 유효성 검사

AddDataValidation 및 AddDataValidationSqRef 는 전체 규칙 표면을 노출하며, AddListValidation, AddWholeNumberValidation, AddDecimalValidation, AddDateValidation, AddTimeValidation, AddTextLengthValidation및 AddCustomValidation 은 형식화된 도우미를 제공합니다

조건부 서식

AddConditionalFormat, AddConditionalFormatExpression, AddConditionalFormatContainsText, AddConditionalFormatNotContainsText, AddConditionalFormatBeginsWith, AddConditionalFormatEndsWith, AddConditionalFormatTop10, AddConditionalFormatAboveAverage, AddConditionalFormatDuplicateValues, AddConditionalFormatUniqueValues, AddConditionalFormatContainsBlanks, AddConditionalFormatNotContainsBlanks, AddConditionalFormatContainsErrors및 AddConditionalFormatNotContainsErrors 는 스칼라 규칙을 추가합니다

AddConditionalFormatDataBar, AddConditionalFormatColorScale2, AddConditionalFormatColorScale3및 AddConditionalFormatIconSet 은 시각적 규칙을 추가합니다. ClearConditionalFormats 는 현재 시트의 대기 중인 규칙을 제거합니다

자동 필터 및 표

AddAutoFilterValue, AddAutoFilterDateGroup및 AddAutoFilterSortCondition 은 워크시트 필터를 구성합니다

AddTable 은 표 부분을 만들고, AddTableFilterValue, AddTableFilterDateGroup및 AddTableSortCondition 은 해당 필터 및 정렬 상태를 구성합니다

보호 및 페이지 나누기

ProtectSheet, UnprotectSheet, AddProtectedRange및 ClearProtectedRanges 는 워크시트 보호를 구성합니다. ProtectWorkbook 및 UnprotectWorkbook 은 통합 문서 구조 및 창 잠금을 구성합니다

AddHorizontalPageBreak 및 AddVerticalPageBreak 은 현재 워크시트에 수동 페이지 나누기를 생성합니다

직접 판독기 저장소 진단

TXLSDirectReader.SharedStringMemoryLimit 은 디코딩된 공유 문자열 메모리를 제한하고, SharedStringsOnDisk 는 임시 인덱스 저장소로의 마이그레이션을 보고하며, SharedStringCount 는 로드된 항목 수를 보고하고, ParallelDiag 는 제한된 병렬 파서 진단을 노출합니다

판독기 프로젝션 및 수식 상태

FirstRow, LastRow, IncludeColumn, ClearColumnProjection 은 값, 수식, 리치 텍스트가 할당되기 전에 행과 1 기반 열 선택을 워크시트 파서로 밀어 넣습니다

IncludeFormulaText 의 기본값은 true입니다. 비활성화하면 캐시된 값, 좌표, 스타일, HasFormula 는 유지되지만 FormulaTextAvailable 은 false가 되고 Formula 는 빈 채로 남습니다

행 커서

TXLSRowCursor.Open 은 XLS, XLSX, XLSM, ODS, CSV, TSV 파일이나 스트림을 받습니다. ZIP 자동 감지는 시트를 열기 전에 ODS 패키지와 Open XML 통합 문서를 구분합니다

SelectSheet 및 SelectSheetByName 은 워크시트를 선택합니다. SheetCount, SheetNames, SheetIndex, RowIndex및 Eof 는 탐색 상태를 노출하며, SharedStringMemoryLimit 은 직접 판독기와 동일한 제한된 공유 문자열 정책을 적용합니다

FirstRow, LastRow, IncludeColumn, ClearColumnProjection 은 모든 커서 형식에서 동일한 1 기반 필터를 사용합니다. 옵션은 FindFirst 와 EOF 사이에서 바꿀 수 없지만 EOF 이후, 시트를 다시 선택한 후, 또는 커서를 닫은 후에는 다시 변경할 수 있습니다

각 TXLSRowCursorCell 은 HasFormula 과 별개로 FormulaTextAvailable를 보고합니다. 클래식 XLS는 사용할 수 없는 토큰 텍스트까지 주장하지 않으면서 수식 존재 여부와 캐시된 결과를 노출하고, IncludeFormulaText 는 XLSX와 ODS 수식 텍스트를 누적 전에 억제할 수 있습니다

ODS 순회는 물리적 행 템플릿 하나를 유지하고, 반복 행 블록을 요청한 구간으로 잘라내며, 반복 구간 안에서 선택된 열 사이를 직접 이동하고, 덮인 셀을 값으로 반환하지 않고 건너뛰며, 잘못되었거나 그리드 한도를 초과하는 반복 횟수는 OnSkippedRecord

State 는 xrcsClosed, xrcsBeforeFirst, xrcsActive, xrcsEof, xrcsCancelled, xrcsFaulted를 구분합니다. Cancel 은 멱등(idempotent)하며 현재 행을 무효화하고, 소스는 유지한 채 활성 워크시트 스트림을 해제하므로 시트를 명시적으로 다시 선택해 새 패스를 시작할 수 있습니다

스트림 오버로드의 기본값은 xsoBorrowed이며 닫을 때 호출자의 초기 위치를 복원합니다. xsoOwned 를 지정하면 열기에 성공한 후 소유권이 이전됩니다. 열기에 실패하면 호출자의 소유권을 소비하지 않습니다

CurrentRowView 는 현재 행 배열을 복사하지 않고 빌려 오며 매 접근마다 세대(generation)를 검사합니다. 커서를 전진시키거나 시트를 선택·취소하거나 닫거나 파괴하면 뷰가 무효화되고 이후 접근에서 EXLSRowCursorViewInvalidated 가 발생합니다

PeakRowBufferedBytes 는 가장 최근 Open 이후 논리 행 하나를 위해 유지되는 셀 레코드, 관리 페이로드, 리치 텍스트, 포맷 백엔드 데이터의 단조 증가 추정치입니다. 정확한 힙 회계가 아니라 제한된 메모리 회귀 진단용입니다

SheetPassesStarted 는 워크시트 백엔드가 성공적으로 시작된 횟수를 셉니다. 콜백 퍼사드를 통해 시트 이름을 조회하거나 시트를 건너뛰는 것은 워크시트 파트를 열지 않습니다

순방향 콜백 어댑터

TXLSForwardReader 는 XLS, XLSX, ODS, CSV, TSV 디코딩을 TXLSRowCursor에 위임하고 현재 행의 각 셀을 OnCell 콜백으로 변환하며, 동일한 행 경계, 열 프로젝션, 수식 상태, 리치 텍스트, 암호, 건너뛴 레코드, 스트림 위치, 제한된 버퍼 계약을 유지합니다

PeakRowBufferedBytes 와 SheetPassesStarted 는 콜백 표면에서 공유 커서 진단을 노출하고, 클래식 XLS는 추가로 ClassicBytesRead 와 ClassicPeakBufferedBytes

판독기 이벤트 및 레코드 타입

판독기와 행 커서는 선택적 콜백과 일반 레코드를 노출하며 모두 lxDirectRead에 선언됩니다. 모든 콜백은 같은 모양을 따릅니다. 레코드가 스트리밍된 항목 하나를 기술하고, Abort 를 설정하면 스캔이 중단됩니다(시트 이벤트는 추가로 SkipSheet를 허용합니다)

작성기 매개변수 및 스타일 타입

작성기의 형식화된 도우미(lxDirectWrite)는 레코드와 열거형을 받으므로 호출이 할당 없이 이루어집니다. WriteRichString 은 TXLSDirectRichText를 받고, AddCellStyle 은 TXLSDirectCellStyle 로 패키지 수준 스타일을 만듭니다. 이 스타일의 정렬(TXLSDirectHorizontalAlignment, TXLSDirectVerticalAlignment), 밑줄(TXLSDirectUnderline), 채우기 패턴(TXLSDirectFillPattern), 테두리 변(TXLSDirectStyleBorder 가 있는 TXLSDirectBorderSide)은 OOXML 스타일 모델을 따릅니다. 조건부 서식은 TXLSDirectConditionalFormat / TXLSDirectCfKind / TXLSDirectCfOperator / TXLSDirectCfValue 와 TXLSDirectCfValueKind 이 있는 TXLSDirectIconSetType을, 데이터 유효성 검사는 TXLSDirectDataValidation을, 표는 TXLSDirectTable을, 하이퍼링크는 TXLSDirectHyperlink를, 정의된 이름은 TXLSDirectDefinedName을, 차등 스타일은 TXLSDirectDxfStyle을, 메모는 TXLSDirectComment를, 이미지는 TXLSDirectImage 이 있는 TXLSDirectImageFormat를, 차트는 TXLSDirectChart 와 TXLSDirectChartSeries 이 있는 TXLSDirectChartType를, 병합은 TXLSDirectMergeRange를, 보호된 범위는 TXLSDirectProtectedRange를, 시트 보호는 TXLSDirectSheetProtectionOptions 의 집합인 TXLSDirectSheetProtectionOption를, 자동 필터 정렬 상태는 TXLSDirectSortState를, 열 옵션은 TXLSDirectColumnOption을, 페이지 지오메트리는 TXLSDirectPageMargins 레코드를 전달합니다

TXLSDirectNeedRow = procedure(Sender: TObject; RowIndex: Integer;
  var Eof: Boolean) of object;

function XLSDirectColName(Col: Integer): WideString;
function XLSDirectParseRef(const Ref: WideString;
  out Col, Row: Integer): Boolean;
function XLSDirectPasswordHash(const Password: WideString): WideString;
      

OnNeedRow 는 애플리케이션에서 행을 끌어 옵니다. 공급자는 writer를 통해 행의 셀을 곧바로 기록하고 Eof = False로 두거나, Eof = True 로 고갈을 선언해 루프를 멈춥니다. 도우미들은 좌표와 보호 프리미티브 사이를 변환합니다. XLSDirectColName 은 0 기반 열을 A1 문자로 렌더링하고, XLSDirectParseRef 는 A1 셀 참조를 파싱하며, XLSDirectPasswordHash 는 시트 보호 레코드가 저장하는 레거시 암호 해시를 계산합니다

참고 항목

• 대용량 스프레드시트 스트리밍
• TXLSForwardReader