API de leitor e gravador diretos

TXLSDirectReader e TXLSDirectWriter processam pacotes XLSX sem manter uma grade completa de planilha em memória, portanto, chamadas de API que descrevem uma planilha devem ser feitas antes ou durante a fase de streaming correspondente

Ciclo de vida do gravador e valores de célula

TXLSDirectWriter.BeginFile ou BeginStream inicia um pacote, os métodos de planilha definem uma planilha por vez e Finish confirma o pacote final

Linhas e colunas usam base 1 na superfície pública do gravador e devem ser fornecidas na ordem de avanço da planilha

Ciclo de vida do patch de planilha

BeginPatch substitui uma planilha ou insere uma nova preservando as partes intocadas do pacote. Inicialização que falha libera imediatamente o arquivo de origem e o stream de origem, incluindo planilha ausente, parte obrigatória do pacote ausente, arquivo inválido ou falha na criação do destino. Arquivos de origem e registros temporários de propriedade do chamador continuam sendo responsabilidade dele; os handles liberados permitem remover ou liberar essas fontes

Close e a destruição liberam os handles de origem mesmo quando não há destino ativo ou a finalização do patch lança uma exceção. Uma substituição de destino mal-sucedida mantém a saída preparada para inspeção, e o gravador pode iniciar um patch subsequente ou uma operação de arquivo comum após uma falha de inicialização

Estilos reutilizáveis

AddCellStyle registra um identificador de estilo imutável no nível do pacote e CloneCellStyle deriva um novo identificador sem reter linhas da planilha

Nomes definidos e hiperlinks

AddDefinedName, AddLocalDefinedName, AddDefinedRangee AddLocalDefinedRange adicionam nomes de pasta de trabalho ou locais da planilha antes da finalização do pacote

AddHyperlink, AddHyperlinkRange, AddInternalHyperlinke AddInternalHyperlinkRange emitem relacionamentos externos ou locais internos de planilha para uma célula ou um intervalo

Validação de dados

AddDataValidation e AddDataValidationSqRef expõem a superfície completa de regras, enquanto AddListValidation, AddWholeNumberValidation, AddDecimalValidation, AddDateValidation, AddTimeValidation, AddTextLengthValidatione AddCustomValidation fornecem auxiliares tipados

Formatação condicional

AddConditionalFormat, AddConditionalFormatExpression, AddConditionalFormatContainsText, AddConditionalFormatNotContainsText, AddConditionalFormatBeginsWith, AddConditionalFormatEndsWith, AddConditionalFormatTop10, AddConditionalFormatAboveAverage, AddConditionalFormatDuplicateValues, AddConditionalFormatUniqueValues, AddConditionalFormatContainsBlanks, AddConditionalFormatNotContainsBlanks, AddConditionalFormatContainsErrorse AddConditionalFormatNotContainsErrors adicionam regras escalares

AddConditionalFormatDataBar, AddConditionalFormatColorScale2, AddConditionalFormatColorScale3e AddConditionalFormatIconSet adicionam regras visuais; ClearConditionalFormats remove as regras pendentes da planilha atual

AutoFiltro e tabelas

AddAutoFilterValue, AddAutoFilterDateGroupe AddAutoFilterSortCondition configuram o filtro da planilha

AddTable cria uma parte de tabela, e AddTableFilterValue, AddTableFilterDateGroupe AddTableSortCondition configuram seu estado de filtro e classificação

Proteção e quebras de página

ProtectSheet, UnprotectSheet, AddProtectedRangee ClearProtectedRanges configuram a proteção da planilha; ProtectWorkbook e UnprotectWorkbook configuram a estrutura da pasta de trabalho e os bloqueios de janela

AddHorizontalPageBreak e AddVerticalPageBreak emitem quebras de página manuais para a planilha atual

Diagnósticos de armazenamento do leitor direto

TXLSDirectReader.SharedStringMemoryLimit limita a memória de strings compartilhadas decodificadas, SharedStringsOnDisk informa a migração para armazenamento indexado temporário, SharedStringCount informa a contagem de entradas carregadas e ParallelDiag expõe diagnósticos limitados do analisador paralelo

Projeção do leitor e estado de fórmulas

FirstRow, LastRow, IncludeColumne ClearColumnProjection empurram a seleção de linhas e colunas (base 1) para o parser da planilha antes da alocação de valores, fórmulas ou rich text

IncludeFormulaText tem padrão true; desativá-lo mantém valores em cache, coordenadas, estilos e HasFormula , enquanto FormulaTextAvailable passa a ser false e Formula permanece vazio

Cursor de linha

TXLSRowCursor.Open aceita arquivos ou streams XLS, XLSX, XLSM, ODS, CSV e TSV; a detecção automática de ZIP distingue pacotes ODS de pastas de trabalho Open XML antes que uma planilha seja aberta

SelectSheet e SelectSheetByName escolhem uma planilha; SheetCount, SheetNames, SheetIndex, RowIndexe Eof expõem o estado da travessia, enquanto SharedStringMemoryLimit aplica a mesma política limitada de strings compartilhadas do leitor direto

FirstRow, LastRow, IncludeColumne ClearColumnProjection usam os mesmos filtros de base 1 em todos os formatos de cursor; opções de passagem não podem mudar entre FindFirst e EOF, mas voltam a ser mutáveis após EOF, seleção de planilha ou fechamento

Cada TXLSRowCursorCell informa HasFormula de forma independente de FormulaTextAvailable; o XLS clássico expõe presença de fórmula e resultados em cache sem alegar texto de tokens indisponível, enquanto IncludeFormulaText pode suprimir o texto de fórmulas de XLSX e ODS antes do acúmulo

A travessia de ODS mantém um template de linha física, recorta blocos de linhas repetidas para o intervalo solicitado, salta diretamente entre colunas selecionadas dentro de spans repetidos, avança pelas células cobertas sem retorná-las como valores, e informa contagens de repetição inválidas ou limitadas pela grade por meio de OnSkippedRecord

State distingue xrcsClosed, xrcsBeforeFirst, xrcsActive, xrcsEof, xrcsCancellede xrcsFaulted; Cancel é idempotente, invalida a linha atual e libera o stream da planilha ativa mantendo a origem, de modo que uma seleção explícita de planilha possa iniciar uma nova passada

O overload de stream tem padrão xsoBorrowed, restaura a posição inicial do chamador no fechamento, e aceita xsoOwned para transferir a propriedade após uma abertura bem-sucedida; aberturas que falham nunca consomem a propriedade do chamador

CurrentRowView empresta o array da linha atual sem copiá-lo e verifica uma geração antes de cada acesso; avançar, selecionar, cancelar, fechar ou destruir o cursor invalida a view e lança EXLSRowCursorViewInvalidated em acessos posteriores

PeakRowBufferedBytes é uma estimativa monotônica desde o Open mais recente dos records de células, payloads gerenciados, rich text e dados do backend de formato retidos para uma linha lógica; ele se destina a diagnósticos de regressão de memória limitada, não à contabilidade exata do heap

SheetPassesStarted conta as inicializações bem-sucedidas de backend de planilha; inspecionar nomes de planilhas ou pular uma planilha pela facade de callback não abre a parte da planilha

Adaptador de callback forward

TXLSForwardReader delega a decodificação de XLS, XLSX, ODS, CSV e TSV para o TXLSRowCursor, converte cada célula da linha atual em um callback OnCell , e preserva os mesmos contratos de limites de linha, projeção de colunas, estado de fórmulas, rich text, senha, records ignorados, posição de stream e buffer limitado

PeakRowBufferedBytes e SheetPassesStarted expõem os diagnósticos compartilhados do cursor na superfície de callback, enquanto o XLS clássico retém adicionalmente ClassicBytesRead e ClassicPeakBufferedBytes

Eventos do leitor e tipos de record

O leitor e o cursor de linha expõem callbacks opcionais e records simples, todos declarados em lxDirectRead. Todo callback segue a mesma forma: o record descreve um item em streaming, e definir Abort interrompe a varredura (eventos de planilha também aceitam SkipSheet)

Tipos de parâmetro e estilo do gravador

Os helpers tipados do gravador (lxDirectWrite) aceitam records e enums para que as chamadas fiquem livres de alocação: WriteRichString recebe um TXLSDirectRichText; AddCellStyle constrói um estilo no nível do pacote a partir de um TXLSDirectCellStyle cujo alinhamento (TXLSDirectHorizontalAlignment, TXLSDirectVerticalAlignment), sublinhado (TXLSDirectUnderline), padrão de preenchimento (TXLSDirectFillPattern) e lados de borda (TXLSDirectStyleBorder com TXLSDirectBorderSide) espelham o modelo de estilos do OOXML. Formatos condicionais passam um TXLSDirectConditionalFormat com TXLSDirectCfKind / TXLSDirectCfOperator / TXLSDirectCfValue / TXLSDirectCfValueKind e TXLSDirectIconSetType, validação de dados um TXLSDirectDataValidation, tabelas um TXLSDirectTable, hyperlinks um TXLSDirectHyperlink, nomes definidos um TXLSDirectDefinedName, estilos diferenciais um TXLSDirectDxfStyle, comentários um TXLSDirectComment, imagens um TXLSDirectImage com TXLSDirectImageFormat, gráficos um TXLSDirectChart com TXLSDirectChartSeries e TXLSDirectChartType, mesclagens um TXLSDirectMergeRange, intervalos protegidos um TXLSDirectProtectedRange, proteção de planilha um conjunto TXLSDirectSheetProtectionOptions de TXLSDirectSheetProtectionOption, estado de ordenação do AutoFiltro um TXLSDirectSortState, opções de coluna um TXLSDirectColumnOption, e geometria de página um record 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 puxa linhas da aplicação: o fornecedor grava as células da linha diretamente pelo gravador e deixa Eof = False, ou declara esgotamento com Eof = True para interromper o loop. Os helpers convertem entre coordenadas e primitivas de proteção: XLSDirectColName renderiza uma coluna de base 0 como suas letras A1, XLSDirectParseRef analisa uma referência de célula A1, e XLSDirectPasswordHash calcula o hash de senha legado que os records de proteção de planilha armazenam

Veja também

• Streaming de planilhas grandes
• TXLSForwardReader