Documentação HotXLS

TXLSXRange class

Unidade: lxHandleX
Representa a rectangular XLSX worksheet range returned by TXLSXWorksheet.Range, RCRange, UsedRange, EntireRow, or EntireColumn. A range is a lightweight view over its worksheet; it does not own cell data

Declaration

TXLSXBuiltinCellStyle = (
  xbsNormal, xbsGood, xbsBad, xbsNeutral,
  xbsCalculation, xbsCheckCell, xbsExplanatoryText, xbsInput,
  xbsLinkedCell, xbsNote, xbsOutput, xbsWarningText,
  xbsHeading1, xbsHeading2, xbsHeading3, xbsHeading4, xbsTitle, xbsTotal,
  xbsAccent1, xbsAccent2, xbsAccent3, xbsAccent4, xbsAccent5, xbsAccent6);

TXLSXRange = class
  constructor Create(ASheet: TXLSXWorksheet; ARow1, ACol1, ARow2, ACol2: Integer);
  function RefA1: WideString;
  function SaveAsHTML(const FileName: WideString): Integer; overload;
  function SaveAsHTML(const FileName: WideString; Options: TXLSXHtmlExportOptions): Integer; overload;
  function SaveAsHTML(Stream: TStream): Integer; overload;
  function SaveAsHTML(Stream: TStream; Options: TXLSXHtmlExportOptions): Integer; overload;

  property Sheet: TXLSXWorksheet;
  property Row1, Col1, Row2, Col2: Integer;
  property RowCount, ColCount: Integer;

  procedure SetValue(const V: Variant);
  procedure SetFormula(const F: WideString);
  function SetArrayFormula(const F: WideString): Integer;
  procedure ClearValues;
  procedure Clear;
  procedure ClearAll;

  procedure SetFontIndex(AIdx: Integer);
  procedure SetFillIndex(AIdx: Integer);
  procedure SetBorderIndex(AIdx: Integer);
  procedure SetNumberFormatIndex(AIdx: Integer);
  procedure SetAlignmentIndex(AIdx: Integer);
  procedure SetNumberFormat(const Fmt: WideString);
  procedure SetBorders(Kind: TXLSXBorderEdgeKind; Style: TXLSXBorderStyle); overload;
  procedure SetBorders(Kind: TXLSXBorderEdgeKind; Style: TXLSXBorderStyle; Color: LongWord); overload;
  procedure SetLocked(ALocked: Boolean);
  procedure SetFormulaHidden(AHidden: Boolean);

  procedure AutoFitColumns(AMinWidth: Double = 0; AMaxWidth: Double = 0);
  procedure AutoFitRows(AMinHeight: Double = 0; AMaxHeight: Double = 0);
  procedure Merge; overload;
  procedure Merge(Across: OleVariant); overload;
  procedure Unmerge;
  function Offset(DRow, DCol: Integer): TXLSXRange;
  function Resize(NewRowCount, NewColCount: Integer): TXLSXRange;
  procedure Sort(AKeyColumn: Integer; ADescending: Boolean = False); overload;
  procedure Sort(const AKeyColumns: array of Integer; const ADescending: array of Boolean); overload;
  procedure ApplyBuiltinStyle(AStyle: TXLSXBuiltinCellStyle);
  procedure CopyTo(ADestRow, ADestCol: Integer);
  procedure MoveTo(ADestRow, ADestCol: Integer);
  procedure InsertRows;
  procedure DeleteRows;
  procedure InsertCols;
  procedure DeleteCols;
  procedure ApplyFormatPatch(ASource: TXLSXRange; AParts: TXLSXFormatParts);
  function CopyToClipboard: Boolean;
  function SaveAsPDF(const FileName: WideString): Integer; overload;
  function SaveAsPDF(Stream: TStream): Integer; overload;
  function SetDynamicArrayFormula(const F: WideString): Integer;
end;

Members

Member Description
Create(ASheet, ARow1, ACol1, ARow2, ACol2) Builds a new worksheet-owned range and normalizes reversed corners so Row1/Col1 are always the upper-left coordinate
RefA1 Devolve the range reference as A1 text. Single-cell ranges return a single cell reference such as B2
SaveAsHTML Options overloads accept TXLSXHtmlExportOptions for Title, WriteDocument, IncludeStyles, IncludeBOM, and TableClass. Set WriteDocument to False for a table fragment; set IncludeBOM to False ao incorporar o resultado numa resposta UTF-8 já existente. As mesmas opções estão disponíveis para a exportação HTML do intervalo selecionado. O resultado exportado preserva as hiperligações de células como <a> anchors and anchored images as inline data: URIs de imagem quando caem dentro do retângulo selecionado. Os comentários de célula dentro do retângulo selecionado também são emitidos com escape como <td> title attributes. When IncludeStyles is enabled, explicit ColWidth values are emitted as <col> widths and explicit RowHeight values as <tr> height styles. Rich-text cell runs are emitted as escaped <span> elements with inline font, color, emphasis, and underline styles when IncludeStyles is enabled. Cell borders are emitted as CSS border-left, border-right, border-top, and border-bottom rules when IncludeStyles is enabled. Hidden rows and columns marked by RowHidden / ColHidden, plus explicit zero-width columns, are skipped in the generated table and <colgroup>. Vertical alignment settings are emitted as CSS vertical-align rules when IncludeStyles is enabled
SetValue / SetFormula Escreve o mesmo valor ou texto de fórmula em todas as células do intervalo através da coleção de células da folha de cálculo
SetArrayFormula Define uma fórmula de matriz CSE de múltiplas células sobre o intervalo. A célula do canto superior esquerdo guarda o texto da fórmula e ancora o intervalo de spill, enquanto as restantes células apontam para essa raiz, de modo a que cada célula avalie o seu próprio elemento do resultado matricial. Indique o texto da fórmula sem as chavetas envolventes
ClearValues / Clear / ClearAll ClearValues and Clear remove values and formulas while preserving style indexes. ClearAll also clears style indexes
SetFontIndex / SetFillIndex / SetBorderIndex / SetNumberFormatIndex / SetAlignmentIndex Aplica índices de base 1 da paleta do livro a cada célula do intervalo. Passe 0 para limpar o índice por célula correspondente
SetNumberFormat Localiza ou acrescenta uma cadeia de formato numérico na paleta do livro e depois aplica ao intervalo o índice de base 1 resultante. Um formato vazio limpa o índice por célula
SetBorders Composes border edges over the range. TXLSXBorderEdgeKind accepts xlsxEdgeAll, xlsxEdgeOutline, xlsxEdgeInside, xlsxEdgeInsideHorizontal, xlsxEdgeInsideVertical, xlsxEdgeTop, xlsxEdgeBottom, xlsxEdgeLeft, xlsxEdgeRight, xlsxEdgeDiagonalUp, and xlsxEdgeDiagonalDown. Use os seletores de limite exterior e interior para construir limites de tabela sem substituir as configurações de limite não relacionadas
SetLocked / SetFormulaHidden Aplica sinalizadores de proteção de célula a todas as células do intervalo, reutilizando o pool de estilos de proteção do livro
AutoFitColumns / AutoFitRows Reencaminha para os auxiliares de ajuste automático da folha de cálculo, sobre os limites de coluna ou de linha do intervalo. Os limites opcionais de largura e altura são transmitidos para manter os esquemas de relatório dentro dos limites de conceção
Merge / Unmerge Merge and Merge(False) create one merged rectangle. Merge(True) creates one merged range per row, matching Excel's merge-across behavior. Unmerge removes an exact merged-range match
Offset / Resize Devolve another worksheet-owned range shifted from the current bounds or resized to the requested row and column count
Sort Ordena as linhas dentro deste intervalo por uma coluna-chave ou por várias colunas-chave, por ordem de prioridade. ADescending seleciona a ordem ascendente ou descendente por chave; as entradas omitidas assumem por predefinição a ordem ascendente. Os valores vazios ficam no fim da ordenação
ApplyBuiltinStyle Aplica a aparência visível de um estilo de célula incorporado do Excel a todas as células do intervalo. O auxiliar escreve formatação direta ao acrescentar o tipo de letra e o preenchimento correspondentes aos pools do livro e ao atribuir às células os índices resultantes
CopyTo / MoveTo Copia ou move o intervalo inteiro para uma célula de destino no canto superior esquerdo. Valores, fórmulas, payloads de rich text, índices de estilo, comentários, hiperligações e âncoras de desenho são reencaminhados através dos auxiliares de cópia e de movimento de intervalos da folha de cálculo
InsertRows / DeleteRows / InsertCols / DeleteCols Executa inserção e eliminação de linhas inteiras ou de colunas inteiras sobre os limites do intervalo. Estes auxiliares reencaminham para as operações de deslocamento de linhas/colunas da folha de cálculo, de modo a que fórmulas, referências, filtros, intervalos de configuração de página, intervalos de gráficos, nomes, imagens e âncoras de gráficos se mantenham alinhados com a grelha editada
ApplyFormatPatch Aplica estilos de formatação seletivos de outro intervalo de origem a este intervalo, usando sinalizadores TXLSXFormatParts
CopyToClipboard Copies the range values and styles to the Windows clipboard
SaveAsPDF Exporta o intervalo de células como ficheiro ou fluxo PDF usando o motor de renderização PDF no próprio processo
SetDynamicArrayFormula Define uma fórmula de matriz dinâmica sobre o intervalo, suportando o comportamento de spill dinâmico do Excel

Ownership and bounds

Os intervalos pertencem à folha de cálculo que os criou e são libertados com essa folha de cálculo O código da aplicação não deve chamar Free on a TXLSXRange e não deve manter uma referência de intervalo depois de a folha de cálculo ou o livro ser destruídos
As coordenadas numéricas são de base 1. A criação de intervalos normaliza cantos invertidos e ajusta as fronteiras aos limites da folha de cálculo XLSX

Exemplo

var
  Wb: TXLSXWorkbook;
  Ws: TXLSXWorksheet;
  Body: TXLSXRange;
begin
  Wb := TXLSXWorkbook.Create;
  try
    Ws := Wb.Sheets.Add('Report');
    Body := Ws.Range['B2:D20'];
    Body.SetNumberFormat('#,##0.00');
    Body.SetBorders(xlsxEdgeOutline, xlsxBorderThin, $FF808080);
    Body.Sort(2);
    Body.ApplyBuiltinStyle(xbsAccent1);
    Ws.Range['F2:G3'].SetArrayFormula('MMULT(A2:B3,D2:E3)');
    Body.AutoFitColumns;
    Body.SaveAsHTML('report-fragment.html');
  finally
    Wb.Free;
  end;
end;

Consulte também