API прямого чтения и записи

TXLSDirectReader и TXLSDirectWriter обрабатывают пакеты XLSX без удержания полной сетки листа в памяти, поэтому вызовы API, описывающие лист, должны выполняться до или во время соответствующей фазы потоковой обработки

Жизненный цикл записи и значения ячеек

TXLSDirectWriter.BeginFile или BeginStream запускает пакет, методы листа определяют по одному листу за раз, а Finish фиксирует конечный пакет

Строки и столбцы нумеруются с единицы в открытой поверхности записи и должны подаваться в прямом порядке листа

Жизненный цикл патча листа

BeginPatch заменяет один лист или вставляет новый лист, сохраняя нетронутые части пакета. Неудачная инициализация немедленно освобождает исходный архив и исходный поток — в том числе при отсутствующем листе, отсутствующей обязательной части пакета, недопустимом архиве или сбое создания места назначения. Исходные файлы и временные регистрации, созданные вызывающим кодом, остаются его ответственностью; освободившиеся дескрипторы позволяют удалить или освободить эти источники

Close и уничтожение объекта освобождают дескрипторы источников, даже когда активного места назначения нет или финализация патча возбудила исключение. Неудавшаяся замена места назначения сохраняет подготовленный вывод для изучения, а писатель может начать следующий патч или обычную файловую операцию после неудачной инициализации

Многократно используемые стили

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 ,

IncludeFormulaText по умолчанию true; его отключение сохраняет кэшированные значения, координаты, стили и HasFormula while FormulaTextAvailable becomes false and Formula remains empty

Row cursor

TXLSRowCursor.Open принимает файлы или потоки XLS, XLSX, XLSM, ODS, CSV и TSV; автоопределение ZIP отличает пакеты ODS от книг Open XML до открытия листа

SelectSheet and SelectSheetByName choose a worksheet; SheetCount, SheetNames, SheetIndex, RowIndex, and Eof expose traversal state, while SharedStringMemoryLimit применяет ту же ограниченную политику shared strings, что и прямой читатель

FirstRow, LastRow, IncludeColumn, and ClearColumnProjection используют одни и те же фильтры с отсчётом от 1 по всем форматам курсора; параметры прохода не могут меняться между FindFirst и EOF, но снова становятся изменяемыми после EOF, выбора листа или закрытия

Each TXLSRowCursorCell reports HasFormula independently from FormulaTextAvailable; классический XLS раскрывает наличие формулы и кэшированные результаты, не выдавая недоступный текст токенов, тогда как IncludeFormulaText может подавлять текст формул XLSX и ODS до накопления

Обход ODS удерживает один физический шаблон строки, обрезает повторяющиеся блоки строк до запрошенного интервала, прыгает напрямую между выбранными столбцами внутри повторяющихся промежутков, продвигается через покрытые ячейки, не возвращая их как значения, и сообщает невалидные или ограниченные сеткой счётчики повторов через OnSkippedRecord

State distinguishes xrcsClosed, xrcsBeforeFirst, xrcsActive, xrcsEof, xrcsCancelled, and xrcsFaulted; Cancel идемпотентен, инвалидирует текущую строку и освобождает поток активного листа, удерживая источник, чтобы явный выбор листа мог начать новый проход

The stream overload defaults to xsoBorrowed, восстанавливает исходную позицию вызывающего при закрытии и принимает xsoOwned для передачи владения после успешного открытия; неудачные открытия никогда не поглощают владение вызывающего

CurrentRowView берёт массив текущей строки без копирования и проверяет поколение перед каждым доступом; продвижение, выбор, отмена, закрытие или уничтожение курсора инвалидирует представление и возбуждает EXLSRowCursorViewInvalidated on later access

PeakRowBufferedBytes — монотонная оценка с момента последнего Open по записям ячеек, управляемым данным, rich text и данным бэкенда форматов, удерживаемым для одной логической строки; он предназначен для регрессионной диагностики ограниченной памяти, а не для точного учёта кучи

SheetPassesStarted считает успешные запуски бэкенда листа; просмотр имён листов или пропуск листа через callback-фасад не открывает часть листа

Forward callback adapter

TXLSForwardReader делегирует декодирование XLS, XLSX, ODS, CSV и TSV в TXLSRowCursor, преобразует каждую ячейку текущей строки в OnCell callback и сохраняет те же контракты границ строк, проекции столбцов, состояния формул, rich text, пароля, пропущенных записей, позиции потока и ограниченного буфера

PeakRowBufferedBytes and SheetPassesStarted раскрывают общую диагностику курсора на callback-поверхности, тогда как классический XLS дополнительно хранит ClassicBytesRead and ClassicPeakBufferedBytes

Reader events and record types

Читатель и курсор строк предоставляют необязательные колбэки и простые записи, все объявленные в lxDirectRead. Каждый колбэк следует одной форме: запись описывает один потоковый элемент, а установка Abort останавливает сканирование (события листа дополнительно принимают SkipSheet)

Writer parameter and style types

The writer's typed helpers (lxDirectWrite) принимают записи и перечисления, так что вызовы остаются без аллокаций: WriteRichString takes a TXLSDirectRichText; AddCellStyle builds a package-level style from a TXLSDirectCellStyle whose alignment (TXLSDirectHorizontalAlignment, TXLSDirectVerticalAlignment), underline (TXLSDirectUnderline), fill pattern (TXLSDirectFillPattern), and border sides (TXLSDirectStyleBorder with TXLSDirectBorderSide) повторяют модель стилей OOXML. Условные форматы передают TXLSDirectConditionalFormat with TXLSDirectCfKind / TXLSDirectCfOperator / TXLSDirectCfValue / TXLSDirectCfValueKind and TXLSDirectIconSetType, data validation a TXLSDirectDataValidation, tables a TXLSDirectTable, hyperlinks a TXLSDirectHyperlink, defined names a TXLSDirectDefinedName, differential styles a TXLSDirectDxfStyle, comments a TXLSDirectComment, images a TXLSDirectImage with TXLSDirectImageFormat, charts a TXLSDirectChart with TXLSDirectChartSeries and TXLSDirectChartType, merges a TXLSDirectMergeRange, protected ranges a TXLSDirectProtectedRange, sheet protection a TXLSDirectSheetProtectionOptions set of TXLSDirectSheetProtectionOption, auto-filter sort state a TXLSDirectSortState, column options a TXLSDirectColumnOption, and page geometry a TXLSDirectPageMargins record

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 тянет строки из приложения: поставщик записывает ячейки строки напрямую через писатель и оставляет Eof = False, or declares exhaustion with Eof = True , XLSDirectColName и XLSDirectParseRef предоставляют состояние обхода, а XLSDirectPasswordHash применяет ту же ограниченную политику общих строк, что и прямое чтение

См. также

• Потоковая обработка больших таблиц
• TXLSForwardReader