Adiciona programaticamente uma
aba de gráfico BIFF8 à pasta de trabalho, retornando a nova aba
TXLSWorksheet. Anteriormente, as abas de gráfico só podiam ser preservadas de forma opaca em um round-trip de carga-salvamento via
TXLSCustomChart; este método grava um subfluxo de gráfico completo diretamente em
SaveAs(xlExcel97). O Excel abre o resultado como uma aba de gráfico do tipo solicitado. Disponível desde v2.41.0 (Roadmap #10 Fase 1); a sobrecarga com array de séries segue na v2.42.0
Enumeração TXLSChartType
Seleciona o tipo de gráfico. Reexportado de lxHandle para que o código do usuário não precise importar a unidade de construção de gráficos diretamente
type
TXLSChartType = (
xlsChartTypeColumn,
xlsChartTypeBar,
xlsChartTypeLine,
xlsChartTypePie);
Registro TXLSChartSeriesInfo
Carrega uma única declaração de série para a sobrecarga de 6 parâmetros. Categories e Values são strings de intervalo A1 (ex.: 'Sheet1!$B$2:$B$5')
type
TXLSChartSeriesInfo = record
Name : WideString;
Categories : WideString;
Values : WideString;
end;
Sintaxe
Cinco sobrecargas cobrem definições de aba de gráfico progressivamente mais ricas
// 1) v2.41.0 — name only; default column chart, no titles, no series.
function AddChartSheet(const Name: WideString): TXLSWorksheet;
// 2) v2.41.0 — name + chart type.
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType): TXLSWorksheet;
// 3) v2.41.0 — + chart title.
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType;
const Title: WideString): TXLSWorksheet;
// 4) v2.41.0 — + category-axis title + value-axis title.
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType;
const Title : WideString;
const CatAxisTitle: WideString;
const ValAxisTitle: WideString): TXLSWorksheet;
// 5) v2.42.0 — + array of series (Name + Categories range + Values range).
function AddChartSheet(
const Name : WideString;
ChartType : TXLSChartType;
const Title : WideString;
const CatAxisTitle: WideString;
const ValAxisTitle: WideString;
const Series : array of TXLSChartSeriesInfo): TXLSWorksheet;
Observações
O subfluxo de gráfico emitido cobre o enquadramento BIFF8 que a especificação exige — BOF (dt=$0020), Chart / PlotGrowth / Frame / Series / SheetProperties / AxesUsed / AxisParent (POS + eixo de categoria + eixo de valor + PlotArea + Frame + ChartFormat + registro de tipo de gráfico + ChartFormatLink + Legend), EOF. O round-trip de aba de gráfico existente via TXLSCustomChart permanece inalterado
Vinculação de nome de série (v2.42.0): cada Series[i].Name não vazio é gravado no subfluxo de gráfico como um rótulo de série literal via um token PTG tStr no BRAI de nome de série (id=2). O Excel usa esse rótulo na legenda e no seletor de séries, para que gráficos com várias séries mostrem legendas adequadas em vez dos espaços reservados padrão "Series1 / Series2"
Vinculação de intervalo de série (v2.47.0): a partir da v2.47.0, as strings de intervalo A1 de Categories e Values são compiladas em referências reais de intervalo de células tArea3D dentro do BRAI, passando pelo compilador de fórmulas e pela tabela de referências EXTERNSHEET da pasta de trabalho. Antes da v2.47.0, esses dois campos eram aceitos na API, mas emitidos como espaços reservados cce=0, de modo que o gráfico renderizado ficava vazio. Os chamadores existentes da v2.42.0 que deixaram Categories / Values vazios não são afetados
O TXLSWorksheet retornado aparece na coleção Sheets e recebe uma entrada de boundsheet de aba de gráfico gravada no salvamento. Métodos no nível de célula no resultado não são suportados — a planilha hospedeira é um contêiner de gráfico, não uma planilha de dados
Exemplo
Este exemplo cria uma pasta de trabalho com uma planilha de dados e um gráfico de colunas vinculado a duas colunas dessa planilha de dados
var
Series: array of TXLSChartSeriesInfo;
begin
// Populate cells on Sheet1.
Workbook.Sheets[1].Name := 'Data';
// ... fill A1:B5 with categories + values ...
SetLength(Series, 1);
Series[0].Name := 'Quarterly Revenue';
Series[0].Categories := 'Data!$A$2:$A$5';
Series[0].Values := 'Data!$B$2:$B$5';
Workbook.Sheets.AddChartSheet(
'Revenue',
xlsChartTypeColumn,
'Quarterly Revenue',
'Quarter',
'USD',
Series);
Workbook.SaveAs('Revenue.xls', xlExcel97);
end;
Limitações
Os detalhes de formatação por tipo de gráfico (largura do intervalo, sobreposição de barras, tamanho do orifício da pizza, estilo do marcador) ainda são emitidos com os padrões do construtor de gráficos — ainda não expostos na API. Salvar e reabrir com o Excel preserva a presença da aba de gráfico, tipo, título, títulos de eixos, legendas de séries e (a partir da v2.47.0) a vinculação de dados de série
Veja também