Documentação do HotXLS

Classe TXLSXWorkbook

Contentor de nível superior para um livro Excel 2007+ (.xlsx). Declarado em lxHandleX. Contém uma colecção TXLSXSheets e disponibiliza pontos de entrada SaveAs / Open para livros OOXML, importação CSV / TSV e fluxos de trabalho de leitura/escrita 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 folha de cálculo 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. Consulte 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. Consulte TXLSXNumberFormat / TXLSXNumberFormats
DefinedNames pasta de trabalho-level named intervalos (pasta de trabalho-scoped ou folha de cálculo-scoped). See TXLSXDefinedName / TXLSXDefinedNames
Calculate Compila e avalia uma string de fórmula do Excel na folha de cálculo ativa, e um = inicial é aceito. Referências de células, intervalos, fórmulas armazenadas em células referenciadas, referências entre folhas de cálculo, 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) Lê xl/workbook.xml e acrescenta os nomes das folhas de cálculo a AList na ordem do workbook, sem carregar o XML da folha de cálculo. 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 palavra-passe 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 folha de cálculo marcada como IsChartSheet = True e inicializa Charts[0] com uma âncora padrão de página inteira. SaveAs grava essas folhas de cálculo em xl/chartsheets/sheetN.xml. Consulte TXLSXChart
StreamingWrite Quando True, SaveAs usa WriteWorksheetXmlStreaming por folha de cálculo - nenhum cache de sheetXmls é mantido, e sharedStrings.xml é emitido por último depois que cada folha de cálculo preenche o SST. Com o TXLSWideStringBuilder por linha, isso mantém o uso de memória linear em folhas de cálculo 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 palavras-passe 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 palavra-passe usada para salvá-la. CanReadEncrypted detecta os bytes mágicos OLE2; OpenEncrypted faz fallback transparente para Open comum para ficheiros 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 ficheiro fornecido. Retorna 1 em caso de sucesso, negativo em caso de falha. Se o workbook não tiver folhas de cálculo, 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 ficheiro 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 ficheiro 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 — palavra-passe é ignored
Open(Stream) Lê um ficheiro 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. Consulte OpenCSV method
OpenODS(FileName) / OpenODS(Stream) Importa um pacote OpenDocument Spreadsheet (.ods) de um ficheiro 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 folhas de cálculo, 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/folhas de cálculo 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 folhas de cálculo, 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 folha de cálculo. 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 folha de cálculo 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 folha de cálculo, 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 folha de cálculo 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 ficheiro ou fluxo de importação precisar dos nomes das folhas de cálculo antes de carregar o workbook
SaveAsCSV overloads Quatro sobrecargas (FileName ou Stream × folha de cálculo ativa padrão / SheetIndex explícito + Delimiter). Grava a folha de cálculo 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 × folha de cálculo ativa padrão / SheetIndex explícito). Grava a folha de cálculo 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 folha de cálculo 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 folha de cálculo 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 folhas de cálculo, 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 folha de cálculo baseado em 0 e é limitada a uma folha de cálculo 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 ficheiro é 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

Escrita e reabertura de um livro:
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;
    

Ver também