Documentação do HotXLS

Classe TXLSXWorkbook

Contêiner de nível superior para uma pasta de trabalho Excel 2007+ (.xlsx). Declarado em lxHandleX. Contém uma coleção TXLSXSheets e fornece pontos de entrada SaveAs / Open para pastas de trabalho OOXML, importação CSV/TSV e fluxos de trabalho de leitura/gravação de OpenDocument Spreadsheet (.ods)

Declaração

type
  TXLSXFileFormat = (xlsxOpenXMLWorkbook, xlsxOpenDocumentSpreadsheet);

  TODSExportOptions = class
    constructor Create;
    property Generator: WideString;
    property IncludeCharts: Boolean;
    property IncludeImages: Boolean;
  end;

  TXLSXWorkbook = class
    constructor Create;
    destructor Destroy; override;
    function SaveAs(const FileName: WideString): Integer; overload;
    function SaveAs(const FileName: WideString; FileFormat: TXLSXFileFormat): Integer; overload;
    function SaveAs(Stream: TStream): Integer; overload;
    function SaveAs(Stream: TStream; FileFormat: TXLSXFileFormat): Integer; overload;
    function Open(const FileName: WideString): Integer; overload;
    function Open(const FileName: WideString; const Password: WideString): Integer; overload;
    function Open(Stream: TStream): Integer; overload;
    function OpenCSV(const FileName: WideString): Integer; overload;
    function OpenCSV(const FileName: WideString; ASeparator: WideChar;
      ADetectTypes: Boolean): Integer; overload;
    function OpenCSV(Stream: TStream): Integer; overload;
    function OpenCSV(Stream: TStream; ASeparator: WideChar;
      ADetectTypes: Boolean): Integer; overload;
    function OpenODS(const FileName: WideString): Integer; overload;
    function OpenODS(Stream: TStream): Integer; overload;
    function SaveAsODS(const FileName: WideString): Integer; overload;
    function SaveAsODS(Stream: TStream): Integer; overload;
    function SaveAsODS(const FileName: WideString; Options: TODSExportOptions): Integer; overload;
    function SaveAsODS(Stream: TStream; Options: TODSExportOptions): Integer; overload;
    function GetODSSheetNames(const FileName: WideString; AList: TStrings): Integer; overload;
    function GetODSSheetNames(Stream: TStream; AList: TStrings): Integer; overload;
    function GetSheetNames(const FileName: WideString; AList: TStrings): Integer; overload;
    function GetSheetNames(Stream: TStream; AList: TStrings): Integer; overload;
    function SaveAsCSV(const FileName: WideString): Integer; overload;
    function SaveAsCSV(const FileName: WideString; SheetIndex: Integer; Delimiter: WideChar): Integer; overload;
    function SaveAsCSV(Stream: TStream): Integer; overload;
    function SaveAsCSV(Stream: TStream; SheetIndex: Integer; Delimiter: WideChar): Integer; overload;
    function SaveAsHTML(const FileName: WideString): Integer; overload;
    function SaveAsHTML(const FileName: WideString; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsHTML(const FileName: WideString; SheetIndex: Integer): Integer; overload;
    function SaveAsHTML(const FileName: WideString; SheetIndex: Integer; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsHTML(Stream: TStream): Integer; overload;
    function SaveAsHTML(Stream: TStream; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsHTML(Stream: TStream; SheetIndex: Integer): Integer; overload;
    function SaveAsHTML(Stream: TStream; SheetIndex: Integer; Options: TXLSXHtmlExportOptions): Integer; overload;
    function SaveAsRTF(const FileName: WideString): Integer; overload;
    function SaveAsRTF(const FileName: WideString; SheetIndex: Integer): Integer; overload;
    function SaveAsRTF(Stream: TStream): Integer; overload;
    function SaveAsRTF(Stream: TStream; SheetIndex: Integer): Integer; overload;
    // AES encryption (ECMA-376 Standard Encryption) write path.
    // OpenEncrypted still raises for encrypted packages.
    function SaveAsEncrypted(const FileName, APassword: WideString): Integer;
    function OpenEncrypted(const FileName, APassword: WideString): Integer;
    function CanReadEncrypted(const FileName: WideString): Boolean;
    function Calculate(const Formula: WideString): Variant;
    property OnUserFunction: TXLSUserFunctionEvent;
    property OnUserFunctionEx: TXLSUserFunctionExEvent;
    // Document properties (docProps/core.xml + docProps/app.xml).
    property Title, Author, Subject, Keywords, Description,
             Category, LastModifiedBy, Company,
             Application, AppVersion: WideString;
    property Created, Modified: TDateTime;
    // Workbook protection (16-bit legacy hash).
    procedure ProtectWorkbook; overload;
    procedure ProtectWorkbook(const APassword: WideString); overload;
    procedure ProtectWorkbook(const APassword: WideString; ALockStructure, ALockWindows: Boolean); overload;
    procedure UnProtectWorkbook;
    property IsWorkbookProtected: Boolean;
    property LockStructure, LockWindows: Boolean;
    // VBA project payload (round-trips byte-for-byte). Workbook is saved
    // with macro-enabled content type when HasVbaProject is True.
    procedure LoadVbaProjectFromFile(const AFileName: WideString);
    procedure ClearVbaProject;
    function HasVbaProject: Boolean;
    property VbaProjectDefined: Boolean;
    property VbaProject: AnsiString;
    property ParsedVBAProject: TXLSVBAProject;
    // Chart sheet helper — creates a sheet flagged IsChartSheet and
    // seeds Charts[0] with a default full-page anchor.
    function AddChartSheet(const AName: WideString;
      AChartType: TXLSXChartType; const ATitle: WideString): TXLSXWorksheet;
    // Streaming SaveAs path (TXLSWideStringBuilder + one sheet at a time).
    property StreamingWrite: Boolean;
    // Workbook-level collections.
    property ActiveSheet: Integer;
    property Minimized: Boolean;
    property WindowHidden: Boolean;
    property ShowHorizontalScroll: Boolean;
    property ShowVerticalScroll: Boolean;
    property ShowSheetTabs: Boolean;
    property XWindow: Integer;
    property YWindow: Integer;
    property WindowWidth: Integer;
    property WindowHeight: Integer;
    property TabRatio: Integer;
    property FirstSheet: Integer;
    property AutoFilterDateGrouping: Boolean;
    property Date1904: Boolean;
    property SourceFormat: TXLSXFileFormat;
    property IndexedColor[Index: Integer]: LongWord;
    function  HasCustomIndexedColor(Index: Integer): Boolean;
    function  CustomIndexedColorCount: Integer;
    procedure ResetIndexedColors;
    property Sheets: TXLSXSheets;
    property Fonts: TXLSXFonts;
    property Fills: TXLSXFills;
    property Borders: TXLSXBorders;
    property NumberFormats: TXLSXNumberFormats;
    property Alignments: TXLSXAlignments;
    property DefinedNames: TXLSXDefinedNames;
    property ExternalLinks: TXLSXExternalLinks;
  end;
      

Membros

Sheets planilha coleção. See TXLSXSheets
Fonts pasta de trabalho-level fonte palette. células pick fonte por setting TXLSXCell.FontIndex para 1-baseado índice em este coleção. See TXLSXFont / TXLSXFonts
Fills Paleta de preenchimentos no nível da pasta de trabalho. As células escolhem um preenchimento ao definir TXLSXCell.FillIndex para um índice de base 1 nesta coleção. Veja TXLSXFill / TXLSXFills
Borders pasta de trabalho-level borda palette. células pick borda por setting TXLSXCell.BorderIndex para 1-baseado índice em este coleção. See TXLSXBorder / TXLSXBorders
NumberFormats Paleta personalizada de formatos numéricos no nível da pasta de trabalho. As células escolhem um formato ao definir TXLSXCell.NumberFormatIndex para um índice de base 1 nesta coleção. Veja TXLSXNumberFormat / TXLSXNumberFormats
DefinedNames pasta de trabalho-level named intervalos (pasta de trabalho-scoped ou planilha-scoped). See TXLSXDefinedName / TXLSXDefinedNames
Calculate Compila e avalia uma string de fórmula do Excel na planilha ativa, e um = inicial é aceito. Referências de células, intervalos, fórmulas armazenadas em células referenciadas, referências entre planilhas, intervalos nomeados e funções suportadas de texto, data, dia útil, engenharia/conversão de base, bit a bit, estatística, agregação e matemática são avaliadas pelo mecanismo de fórmulas compartilhado do HotXLS. Consulte OnUserFunction para tratar funções personalizadas ou não suportadas
OnUserFunction, OnUserFunctionEx Callback usado por Calculate quando fórmula calls custom ou unsupported função. See OnUserFunction / OnUserFunctionEx callback
GetSheetNames(FileName, AList), GetSheetNames(Stream, AList) xl/workbook.xml e acrescenta os nomes das planilhas a AList na ordem do workbook, sem carregar o XML da planilha. A sobrecarga de stream espera um fluxo completo de pacote XLSX. Retorna o número de nomes lidos, ou -1 quando o pacote não pode ser aberto
Alignments pasta de trabalho-level célula-alignment palette. células pick entrada por setting TXLSXCell.AlignmentIndex para 1-baseado índice em este coleção. See TXLSXAlignment
Document properties Título, Autor, Assunto, Palavras-chave, Descrição, Categoria, LastModifiedBy, Empresa, Application, AppVersion, Created, Modified. Definir qualquer uma delas preenche docProps/core.xml + docProps/app.xml em SaveAs, caso contrário o workbook mantém o conjunto mínimo de partes
ProtectWorkbook / UnProtectWorkbook pasta de trabalho protection toggle com optional 16-bit legacy senha hash e LockStructure / LockWindows flags. Reflected as <workbookProtection> em xl/pasta de trabalho.xml
LoadVbaProjectFromFile / VbaProject / HasVbaProject / VbaProjectDefined LoadVbaProjectFromFile importa um payload bruto vbaProject.bin; VbaProject expõe os bytes; HasVbaProject e o somente leitura VbaProjectDefined informam se há um payload presente. Salve com a extensão .xlsm quando os macros precisarem ser habilitados pelo Excel
ParsedVBAProject Visualização analisada somente leitura do payload atual vbaProject.bin. Quando o payload é um armazenamento OLE VBA válido, retorna um TXLSVBAProject que expõe nomes de módulos e texto-fonte; caso contrário, retorna nil. O payload bruto VbaProject continua sendo os bytes autoritativos usados no round-trip SaveAs/Open
AddChartSheet(Name, Type, Title) Cria uma planilha marcada como IsChartSheet = True e inicializa Charts[0] com uma âncora padrão de página inteira. SaveAs grava essas planilhas em xl/chartsheets/sheetN.xml. Veja TXLSXChart
StreamingWrite Quando True, SaveAs usa WriteWorksheetXmlStreaming por planilha - nenhum cache de sheetXmls é mantido, e sharedStrings.xml é emitido por último depois que cada planilha preenche o SST. Com o TXLSWideStringBuilder por linha, isso mantém o uso de memória linear em planilhas grandes. O padrão é False (comportamento existente)
SaveAsEncrypted / OpenEncrypted / CanReadEncrypted Suporte de gravação para ECMA-376 Standard Encryption. SaveAsEncrypted grava um contêiner OLE Compound File protegido por AES-128 conforme a norma para senhas não vazias, usando aceleração AES-NI quando disponível e, caso contrário, um fallback de software portátil. A saída criptografada abre no Excel 2007 e posterior com a senha usada para salvá-la. CanReadEncrypted detecta os bytes mágicos OLE2; OpenEncrypted faz fallback transparente para Open comum para arquivos sem criptografia e ainda lança EXlsxEncryptionNotImplemented para pacotes criptografados até que o suporte a descriptografia esteja disponível
SaveAs(FileName) Grava o workbook no arquivo fornecido. Retorna 1 em caso de sucesso, negativo em caso de falha. Se o workbook não tiver planilhas, uma Sheet1 padrão é adicionada antes da gravação
SaveAs(FileName, FileFormat) Aceita xlsxOpenXMLWorkbook para saída OOXML ou xlsxOpenDocumentSpreadsheet para um pacote OpenDocument Spreadsheet (.ods) direto. SaveAsODS é o atalho nomeado para o caminho ODS e oferece a mesma saída de formato de arquivo mais o controle opcional de TODSExportOptions
SaveAs(Stream) / SaveAs(Stream, FileFormat) Grava o workbook diretamente em qualquer TStream. A sobrecarga FileFormat aceita xlsxOpenXMLWorkbook ou xlsxOpenDocumentSpreadsheet, tornando-a adequada para geração XLSX ou ODS em memória e caminhos de armazenamento BLOB. Retorna 1 em caso de sucesso
Open(FileName) Lê um arquivo OOXML .xlsx e substitui a coleção Sheets pelo conteúdo dele. Retorna 1 em caso de sucesso
Open(FileName, Password) Reserved para future encrypted XLSX suporte. Behaves like Open(FileName) today — senha é ignored
Open(Stream) Lê um arquivo OOXML .xlsx a partir de um TStream. Retorna 1 em caso de sucesso
OpenCSV(FileName) / OpenCSV(Stream) Importa texto CSV ou TSV para o workbook com detecção automática de separador (,, ;, tabulação ou pipe), detecção de codificação UTF-8 / UTF-16 baseada em BOM, campos entre aspas no estilo RFC 4180 e inferência opcional do tipo de valor pelas sobrecargas ADetectTypes. Chamar Open(FileName) em .csv ou .tsv encaminha automaticamente para este importador. Veja OpenCSV method
OpenODS(FileName) / OpenODS(Stream) Importa um pacote OpenDocument Spreadsheet (.ods) de um arquivo ou fluxo. O leitor carrega content.xml, informações de estilo compartilhado de styles.xml e configurações de exibição quando presentes, preservando nomes de planilhas, valores escalares, resultados de fórmulas em cache, conversão básica de referências de fórmulas, linhas/colunas/células repetidas, intervalos mesclados, rich text, hyperlinks, comentários, imagens incorporadas, gráficos incorporados, linhas/colunas/planilhas ocultas, alturas de linhas, larguras de colunas, estilos herdados/padrão, formatos numéricos/de data/hora/moeda/científico/fração, estado de proteção de células e planilhas, intervalos nomeados, áreas de impressão, quebras de página manuais, painéis congelados, intervalos AutoFilter, grupos de estrutura de linhas/colunas, cabeçalhos/rodapés, validações de dados incluindo prompts, formatos condicionais incluindo fórmulas/escalas de cor/barras de dados e a cor da guia da planilha. Semântica completa de OpenFormula, chaves de proteção ODS, geometria de comentários, formatação avançada de comentários e recursos de pacote fora do conteúdo da planilha não são convertidos
SaveAsODS(FileName) / SaveAsODS(Stream) Salva o workbook como um pacote OpenDocument Spreadsheet válido. Escreve diretamente o mimetype ODF, manifesto, metadados, estilos e conteúdo da planilha, preservando valores tipados, fórmulas, estilos, rich text, dimensões, mesclagens, hyperlinks, imagens, gráficos, intervalos nomeados, intervalos AutoFilter, formatos condicionais, validações de dados, painéis congelados, configuração de página, cabeçalhos/rodapés, intervalos de impressão, quebras de página manuais, grupos de estrutura, cor da guia e visibilidade da planilha quando esses recursos são representados no modelo de workbook do HotXLS
TODSExportOptions Controla a exportação ODS. Generator substitui o valor meta:generator em meta.xml; um valor vazio usa a string de gerador interna do HotXLS. IncludeCharts e IncludeImages têm padrão True e, quando False, removem juntos os frames de desenho, partes do pacote e entradas do manifesto correspondentes, para que a saída não tenha referências órfãs de gráficos ou imagens. A instância de opções pertence ao chamador e deve ser liberada
GetODSSheetNames(FileName, AList), GetODSSheetNames(Stream, AList) Lê apenas os nomes das tabelas ODS de content.xml para AList sem redefinir ou preencher o workbook. Use isso quando um seletor de arquivo ou fluxo de importação precisar dos nomes das planilhas antes de carregar o workbook
SaveAsCSV overloads Quatro sobrecargas (FileName ou Stream × planilha ativa padrão / SheetIndex explícito + Delimiter). Grava a planilha escolhida como um CSV em UTF-8 com BOM. Valores de data são renderizados como yyyy-mm-dd hh:nn:ss; células com fórmula são calculadas antes da exportação, e o texto da fórmula é usado apenas quando o cálculo não está disponível. Retorna 0 em caso de sucesso
SaveAsHTML overloads As sobrecargas com opções aceitam TXLSXHtmlExportOptions para Title, WriteDocument, IncludeStyles, IncludeBOM e TableClass. Defina WriteDocument como False para um fragmento de tabela; defina IncludeBOM como False ao incorporar a saída em uma resposta UTF-8 existente. A saída exportada preserva hyperlinks de células como âncoras <a> e imagens ancoradas como URIs de imagem data: embutidos; a exportação no nível do workbook inclui âncoras fora das células preenchidas. Comentários de célula também são emitidos como atributos title escapados em <td>, e a exportação no nível do workbook inclui âncoras apenas de comentário. Quando IncludeStyles está habilitado, valores explícitos de ColWidth são emitidos como larguras <col> e valores explícitos de RowHeight como estilos de altura <tr>. Execuções de rich text nas células são emitidas como elementos <span> escapados com estilos inline de fonte, cor, ênfase e sublinhado quando IncludeStyles está habilitado. Bordas de célula são emitidas como regras CSS border-left, border-right, border-top e border-bottom quando IncludeStyles está habilitado. Linhas e colunas ocultas marcadas por RowHidden / ColHidden, além de colunas com largura zero explícita, são ignoradas na tabela gerada e em <colgroup>. Configurações de alinhamento vertical são emitidas como regras CSS vertical-align quando IncludeStyles está habilitado
SaveAsRTF overloads Quatro sobrecargas (FileName ou Stream × planilha ativa padrão / SheetIndex explícito). Grava a planilha escolhida como um documento RTF 1.6 com uma tabela simples. As larguras de coluna são derivadas dos dados de ColWidth (1 unidade de caractere ≈ 96 twips; padrão 809 twips). Negrito / itálico / tamanho de fonte por célula são aplicados; caracteres não ASCII são codificados como escapes Unicode RTF \uN? de 16 bits com sinal. Células mescladas não são abrangidas. Retorna 0 em caso de sucesso
ActiveSheet Índice 1-based da planilha ativa (selecionada) (0 quando nenhuma), correspondendo ao ActiveSheetIndex do mecanismo clássico de XLS. SaveAs grava activeTab="N" em <workbookView> (o próprio atributo OOXML activeTab continua baseado em 0) quando as opções de visualização do workbook precisam ser emitidas, e marca a planilha correspondente com tabSelected="1"
Minimized / WindowHidden / ShowHorizontalScroll / ShowVerticalScroll Sinalizadores de aparência da janela do workbook gravados em <workbookView>. Minimized grava minimized="1", WindowHidden grava visibility="hidden", e ShowHorizontalScroll / ShowVerticalScroll ocultam ou exibem as barras de rolagem do workbook. Open faz round-trip dos quatro valores
XWindow / YWindow / WindowWidth / WindowHeight Geometria da janela do workbook gravada em <workbookView>. XWindow e YWindow armazenam a origem da janela, enquanto WindowWidth e WindowHeight armazenam seu tamanho. Os valores são limitados a 0..65535 e fazem round-trip ao carregar
ShowSheetTabs / TabRatio / FirstSheet / AutoFilterDateGrouping Opções de visualização da janela do workbook gravadas em <workbookView>. ShowSheetTabs oculta ou mostra a barra de guias das planilhas, TabRatio controla a divisão de largura entre a barra de guias e a barra de rolagem e é limitada a 0..1000, FirstSheet seleciona a primeira guia visível como um índice de planilha baseado em 0 e é limitada a uma planilha existente, e AutoFilterDateGrouping controla o agrupamento de datas do Excel nas listas suspensas do AutoFilter. Open faz round-trip dos quatro valores
Date1904 Base de datas do workbook. False (padrão) = época Windows 1900; True = época Mac 1904 (desloca cada serial de data em 1462 dias). Defina isso antes de atribuir valores de célula TDateTime para que o Excel exiba a mesma data de calendário
SourceFormat Reports package family loaded por most recent successful Open ou OpenODS call. It retorna xlsxOpenXMLWorkbook para XLSX e xlsxOpenDocumentSpreadsheet para ODS; newly created pasta de trabalho reports xlsxOpenXMLWorkbook until arquivo é opened
IndexedColor[Index] Valor ARGB para a posição dada da paleta OOXML de cores indexadas (0..63). A leitura retorna a substituição do usuário, se definida; caso contrário, retorna o padrão OOXML interno (XlsxDefaultIndexedPalette). A escrita substitui a posição N; depois SaveAs emite um bloco completo <indexedColors> com todas as 64 posições
HasCustomIndexedColor / CustomIndexedColorCount / ResetIndexedColors HasCustomIndexedColor(N) retorna True quando a posição N foi explicitamente substituída. CustomIndexedColorCount retorna o número de posições substituídas (0 = nenhum bloco <colors> emitido por SaveAs). ResetIndexedColors descarta todas as substituições e restaura a paleta padrão
ExternalLinks Coleção de referências externas de workbook. Cada entrada TXLSXExternalLink contém uma URL de destino e uma lista SheetNames. SaveAs emite o bloco <externalReferences> em xl/workbook.xml e as partes correspondentes xl/externalLinks/. Open faz round-trip do Target e de SheetNames; valores de célula em cache dentro de <sheetDataSet> não são preservados

Exemplo

Gravando e reabrindo uma pasta de trabalho
uses lxHandleX;

var
  wb: TXLSXWorkbook;
begin
  wb := TXLSXWorkbook.Create;
  try
    wb.Sheets.Add('Demo').Cells.Item[1, 1].Value := 'Hello';
    wb.SaveAs('demo.xlsx');

    wb.Open('demo.xlsx');
    ShowMessage(wb.Sheets[0].Cells.Item[1, 1].Value);
  finally
    wb.Free;
  end;
end;
    

Veja também