Documentação HotXLS

Visão Geral

HotXLS Logo
A Biblioteca de Leitura/Gravação Excel HotXLS é um componente de leitura e gravação de Excel de alto desempenho para Delphi e C++Builder Ele pode criar novas planilhas Excel e ler ou modificar pastas de trabalho XLS e XLSX existentes sem exigir que o Microsoft Excel ou o Office estejam instalados na máquina
O HotXLS é escrito inteiramente em Object Pascal. Ele lê e grava arquivos Excel diretamente no nível binário e OOXML, portanto não há sobrecarga de automação COM/OLE e nenhuma dependência da licença ou presença do Office O HotXLS oferece suporte a Delphi e C++Builder XE5 a 13 Florence
A formatação de cores XLS clássica permanece intencionalmente baseada em paleta. Consulte o Modelo de cores XLS clássico para ver a decisão sobre ThemeColor / TintAndShade

Arquitetura de Dupla Fachada

O HotXLS expõe duas unidades de fachada coexistentes para que o código XLS legado e o novo código XLSX possam coexistir sem nenhuma refatoração:
lxHandle Fachada principal para o formato Excel 97–2003 BIFF8 (.xls), além da exportação de HTML, RTF, CSV e TSV Todo o código de usuário existente continua usando esta unidade inalterada. Pontos de entrada: TXLSWorkbook, TXLSWorksheet, IXLSWorkbook, IXLSRange
lxHandleX Fachada principal para o formato Excel 2007+ OOXML (.xlsx) e leitura/gravação do OpenDocument Spreadsheet (.ods). Fornece seus próprios tipos de pastas de trabalho e planilhas, para que o comportamento específico de XLSX não seja adicionado retroativamente ao caminho do código BIFF. Pontos de entrada: TXLSXWorkbook, TXLSXWorksheet, TXLSXCell
Ambas as fachadas compartilham o mesmo mecanismo de fórmula, a mesma camada de suporte Unicode e o mesmo pipeline de exportação Consulte Visão Geral da Fachada XLSX para ver a hierarquia de classes completa exposta por lxHandleX

Início Rápido

Os trechos a seguir mostram o código mínimo para criar uma pasta de trabalho com uma planilha e gravar um valor em uma célula.

XLS Clássico (lxHandle)

uses lxHandle;

var
  Book: IXLSWorkbook;
  ws:   TXLSWorksheet;
begin
  Book := TXLSWorkbook.Create;
  // Adicionar uma planilha e dar um nome a ela
  ws := Book.Sheets.Add;
  ws.Name := 'Sheet1';

  // Gravar valores em células usando a notação A1
  ws.Range['A1'].Value := 'Hello';
  ws.Range['B1'].Value := 42;
  ws.Range['C1'].Formula := '=B1*2';

  // Aplicar formatação básica
  ws.Range['A1'].Font.Bold := True;
  ws.Range['A1'].Interior.Color := clYellow;

  Book.SaveAs('output.xls');
end;

XLSX (lxHandleX)

uses lxHandleX;

var
  Book: TXLSXWorkbook;
  ws:   TXLSXWorksheet;
  cell: TXLSXCell;
begin
  Book := TXLSXWorkbook.Create;
  try
    ws := Book.Sheets.Add('Sheet1');

    // Gravar uma string e um valor numérico
    ws.Cells[1, 1].Value := 'Product';
    ws.Cells[1, 2].Value := 'Price';
    ws.Cells[2, 1].Value := 'Widget';
    ws.Cells[2, 2].Value := 9.99;

    // Aplicar um formato de número de moeda
    cell := ws.Cells[2, 2];
    cell.NumberFormat := '$#,##0.00';

    Book.SaveAs('output.xlsx');
  finally
    Book.Free;
  end;
end;
Para um passo a passo mais amplo que abrange ambas as fachadas em um único projeto de demonstração, consulte o Tour da API (API Tour Demo)

Recursos

Suporte a E/S de Arquivo e Fluxo (Stream)

Leia arquivos Excel existentes, grave arquivos Excel novos ou existentes, manipule fluxos de trabalho clássicos de proteção de senha XLS e salvamento criptografado XLSX, e liste rapidamente nomes de planilhas de arquivos ou fluxos XLS e XLSX sem carregar a pasta de trabalho inteira. A abertura de um CSV como uma pasta de trabalho é suportada por meio de IXLSWorkbook.OpenCSV

Valores e Fórmulas de Células

Leia e grave valores de células de todos os tipos nativos do Excel: número, string, data/hora, booleano e fórmula O mecanismo de cálculo integrado avalia fórmulas em pastas de trabalho XLS clássicas e XLSX, suportando:
  • Funções de texto (LEFT, MID, TRIM, SUBSTITUTE, …)
  • Funções de data e dia útil (DATE, NETWORKDAYS, WORKDAY, …)
  • Funções de engenharia e conversão de base (BIN2DEC, HEX2DEC, …)
  • Funções bit a bit (BITAND, BITOR, BITXOR, …)
  • Funções estatísticas e de agregação (AVERAGE, SUMIF, COUNTIFS, …)
  • Funções matemáticas (ROUND, MOD, POWER, …)
Um retorno de chamada OnUserFunction permite manipular funções de planilha personalizadas ou não suportadas em tempo de execução. Consulte o Retorno de chamada OnUserFunction para a assinatura e exemplos
Exemplo de avaliação de fórmula

Formatação de Células

Acesso total aos atributos de aparência da célula:
  • Fontes — nome, tamanho, cor (RGB ou cor do tema + tonalidade), negrito, itálico, sublinhado, tachado, sobrescrito, subscrito, sombra e contorno
  • Alinhamento — alinhamento horizontal e vertical, orientação do texto (ângulo), nível de recuo, quebrar texto, reduzir para caber e ordem de leitura (RTL/LTR)
  • Bordas — todas as quatro bordas e diagonais, estilo de linha, espessura e cor RGB / do tema
  • Interior (preenchimento) — preenchimento sólido, preenchimentos de padrão, cores de primeiro e segundo plano, incluindo cor de tema com TintAndShade
  • Formatos de números — cadeias de formato internas e personalizadas para data, hora, moeda, porcentagem e notação científica
  • Comentários / anotações — adicionar, ler e estilizar comentários de células

Operações de Intervalo (Range)

IXLSRange (fachada clássica) e TXLSXRange (fachada XLSX) fornecem um rico conjunto de operações de intervalo:
  • Mesclar e desmesclar células; acessar a área mesclada de qualquer célula
  • Copiar, mover, inserir e excluir intervalos, com controle da direção de deslocamento
  • Agrupar e desagrupar linhas ou colunas para exibições de estrutura de tópicos/recolher
  • Ajuste automático (AutoFit) da altura da linha e largura da coluna ao conteúdo da célula
  • Aplicar estilos de células nomeados integrados (ApplyBuiltinStyle)
  • Seleções de áreas múltiplas (TXLSWorksheet.SelectAreas)
  • Retorno de chamada de iteração ForEachCell para processamento em lote de células

Recursos da Planilha

O controle em nível de planilha abrange:
  • Nome da planilha, cor da guia, visibilidade (oculta / muito oculta) e navegação baseada em índice
  • Proteção da planilha com granularidade por permissão; proteção no nível da pasta de trabalho
  • Congelar painéis, dividir painéis e posição de rolagem
  • Intervalos de AutoFilter com critérios; regras de validação de dados de lista
  • Formatação condicional: escalas de cores (2 e 3 cores), barras de dados e conjuntos de ícones
  • Localizar e substituir texto em toda a planilha
  • Opções de visualização: cor da linha de grade, modo de exibição de fórmula, exibição de zeros, exibição de títulos, exibição da direita para a esquerda, exibição de símbolos de estrutura de tópicos e nível de zoom
  • Tabelas estruturadas (TXLSTable / TXLSXTable): adicionar, acessar e estilizar tabelas do Excel com linhas de cabeçalho e linhas em faixas
  • Gráficos: adicionar planilhas de gráficos e gráficos incorporados por meio de TXLSWorksheetsAddChartSheet e TXLSXChart

Hiperlinks e Intervalos Nomeados

Adicione e leia hiperlinks (URL, mailto e referências de células na pasta de trabalho) por meio de IXLSHyperLinks. Defina e resolva intervalos nomeados nos níveis de pasta de trabalho e planilha por meio de IXLSNames / TXLSXDefinedNames. Intervalos nomeados podem ser usados em fórmulas e resolvidos de volta em um intervalo de células por meio de RefersToRange

Imagens e Formas

Incorpore imagens rasterizadas (BMP, JPG, PNG, GIF) em planilhas por meio de TXLSShapes.AddPicture / TXLSXWorksheet.AddImage. Crie caixas de texto independentes no XLS clássico por meio de TXLSShapes.AddTextBox. Preserve conectores OfficeArt criados no Excel e regras de solucionador em desenhos BIFF8, e exponha opções FOPT brutas de formas por meio de TXLSShape.OfficeArtOptions para fluxos de trabalho avançados de desenho

Configuração de Página e Impressão

Acesso total ao layout de impressão por meio de IXLSPageSetup:
  • Tamanho do papel (A4, Carta, Ofício e muitos outros; consulte Tamanho do papel (PaperSize))
  • Orientação (retrato / paisagem), margens, centralizar horizontal / verticalmente
  • Cadeias de cabeçalho e rodapé com códigos de formatação do Excel (negrito, itálico, número da página, data etc.; consulte Códigos de formatação de cabeçalho/rodapé)
  • Quebras de página manuais horizontais e verticais
  • Ajuste da escala para caber nas páginas; porcentagem de zoom; área de impressão; títulos de impressão (repetir linhas / colunas)
  • Qualidade de rascunho; preto e branco; imprimir linhas de grade; imprimir títulos; imprimir notas

Formatos de Exportação

Exporte pastas de trabalho inteiras, planilhas individuais ou intervalos de células arbitrários para:
  • HTML — documento completo ou fragmento de tabela embutida para fluxos de trabalho de e-mail ou visualização; controlável por meio de TXLSHTMLExport e TXLSXHtmlExportOptions
  • RTF — rich text para importação em processadores de texto
  • CSV — valores separados por vírgula com delimitador e codificação configuráveis
  • TSV — valores separados por tabulação
  • ODS — OpenDocument Spreadsheet por meio da fachada lxHandleX

Exportação de Banco de Dados e Grade (Grid)

Exporte qualquer conjunto de dados compatível com TDataSet ou um TDBGrid diretamente para Excel, HTML ou RTF usando os componentes TDataToXLS ou TGridToXLS. Ambos os componentes disparam os eventos AfterCell, AfterRow, AfterTitle e AfterGroup para um controle minucioso da saída, e suportam campos de agrupamento de vários níveis

Preservação de Projeto VBA

O HotXLS preserva o conteúdo dos projetos VBA ao ler/gravar pastas de trabalho habilitadas para macro. A inspeção somente leitura de módulos está disponível por meio de TXLSVBAProject e TXLSVBAModule. Chame IXLSWorkbook.HasVBAProject para detectar um conteúdo e LoadVBAProjectFromFile / SaveVBAProjectToFile para transferi-lo entre arquivos

Unicode e Texto Internacional

Todo o tratamento de cadeias de caracteres é nativo Unicode. O HotXLS lê e grava arquivos do Excel criados em qualquer idioma, incluindo CJK, árabe, hebraico, tailandês e outros scripts, com suporte correto para texto bidirecional e ordem de leitura
Exemplo de suporte a caracteres Unicode

Tabelas Dinâmicas (XLS Clássico)

Crie tabelas dinâmicas a partir de um intervalo de origem com TXLSWorksheet.AddPivotTable, configure a colocação de campos e formatos numéricos de campos de dados e inspecione o modelo dinâmico por meio de TXLSWorksheet.PivotTables. Consulte API de tabelas dinâmicas XLS Clássico para ver detalhes de campos e filtros

Vantagens

No Office dependency Lê e grava arquivos XLS e XLSX diretamente no nível binário. O Microsoft Excel ou Office não precisa estar instalado, licenciado ou em execução. Isso elimina a sobrecarga da automação COM/OLE, evita as restrições de threading impostas pela interoperabilidade do Office e permite que o HotXLS seja usado em contextos de servidor e serviços onde uma instalação de desktop do Office é impraticável
High performance Os analisadores BIFF8 e OOXML são gravados em Object Pascal nativo, sem alocação de DOM XML intermediária para o caminho de execução rápida. Pastas de trabalho grandes com centenas de milhares de linhas podem ser lidas e gravadas com baixo pico de memória. A desduplicação de strings compartilhadas e a compactação de fórmulas compartilhadas são aplicadas automaticamente para manter o tamanho do arquivo pequeno
OLE migration path A superfície da API da fachada clássica (pasta de trabalho, planilha, intervalo, fonte, bordas, interior, configuração de página) espelha fielmente o modelo de objeto do Excel familiar da automação OLE. Isso simplifica a migração de projetos existentes baseados em OLE: substitua as chamadas COM pelas chamadas HotXLS, remova a dependência do Office e obtenha desempenho nativo
Dual-facade design O código XLS herdado continua sendo compilado e executado sem alterações em lxHandle, enquanto o novo código XLSX usa a fachada mais rica lxHandleX. A migração de um formato de arquivo por vez é segura e incremental
Formula engine included Um mecanismo de cálculo de várias passagens integrado lida com as funções mais comuns da planilha sem exigir que o Excel recalcule ao abrir. Funções personalizadas são tratadas por meio do retorno de chamada OnUserFunction
Easy to use Componentes Delphi prontos para uso (TDataToXLS, TGridToXLS) não exigem nenhum código para tarefas comuns de exportação. A API de intervalo fluente suporta notação A1, notação R1C1 e indexação de linha/coluna baseada em zero
Thread-safe file I/O Como não há um processo compartilhado do Office, várias instâncias do TXLSXWorkbook podem ser criadas e salvas simultaneamente em threads independentes, sem sincronização, o que torna o HotXLS adequado para servidores de geração de relatórios multithread

Compatibilidade

O HotXLS é compatível com as seguintes versões do RAD Studio:
Delphi XE5, XE6, XE7, XE8, 10 Seattle, 10.1 Berlin, 10.2 Tokyo, 10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13 Florence
C++Builder XE5, XE6, XE7, XE8, 10 Seattle, 10.1 Berlin, 10.2 Tokyo, 10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13 Florence
Target platforms Windows de 32 bits e 64 bits
Excel file formats XLS (BIFF8, Excel 97–2003), XLSX (OOXML, Excel 2007+), ODS (OpenDocument 1.2)
Export-only formats HTML, RTF, CSV, TSV

Veja Também