Trabalhando com Gráficos

Trabalhando com Gráficos

Aspose.Words FOSS para .NET pode inserir gráficos nativos do Word — os mesmos gráficos DrawingML que o próprio Word cria — como uma forma na camada de desenho. DocumentBuilder.InsertChart cria a forma e a devolve; a propriedade Chart da forma expõe séries, eixos, legenda e formatação. Este guia aborda a criação de um gráfico, a escolha do tipo de gráfico, o trabalho com séries e pontos de dados, eixos e linhas de grade, e a formatação dos elementos do gráfico.

Criando um Gráfico

Chame DocumentBuilder.InsertChart(chartType, width, height) para inserir uma forma de gráfico no cursor e obter de volta o Shape que a contém. Sua propriedade Chart é o objeto Chart que você configura. Um gráfico recém-inserido vem com séries de demonstração de espaço reservado, portanto limpe Chart.Series antes de adicionar dados reais com ChartSeriesCollection.Add(seriesName, categories, values):

using Aspose.Words;
using Aspose.Words.Drawing.Charts;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

string[] categories = new string[] { "AW Category 1", "AW Category 2", "AW Category 3" };
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });

doc.Save("chart.docx");

Este exemplo cria um Document, usa DocumentBuilder.InsertChart(ChartType.Line, 432, 252) para inserir uma forma de gráfico de linhas, lê shape.Chart para obter o objeto Chart, chama chart.Series.Clear() para remover a série de espaço reservado, adiciona uma série real com chart.Series.Add(seriesName, categories, values) e grava o resultado com Document.Save.

Tipos de Gráficos

ChartType abrange as famílias padrão de gráficos do Word — Line, Bar, Column (além de suas variantes Stacked, PercentStacked e 3D), Pie, PieOfPie, Doughnut, Area, Scatter, Bubble, Radar, Stock, Surface, e os tipos de gráficos mais recentes do Word 2016 Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker e Waterfall. Passe o valor desejado como argumento chartType para InsertChart; não há como mudar o tipo de um gráfico existente após a inserção, exceto substituindo a forma.

Séries e Pontos de Dados

Chart.Series é um ChartSeriesCollection de objetos ChartSeries. Além da sobrecarga Add(seriesName, categories, values) usada acima, ChartSeriesCollection também possui sobrecargas para pares de valores X/Y, datas e tamanhos de bolha, além de Insert, Remove(index) e Clear(). Cada ChartSeries expõe DataPoints (um ChartDataPointCollection) para formatação por ponto — Format, Marker, Explosion e InvertIfNegative — e HasDataLabels / DataLabels para ativar e configurar um ChartDataLabelCollection (ShowValue, ShowCategoryName, ShowPercentage, Position).

Eixos e Linhas de Grade

Chart.AxisX, AxisY e AxisZ são objetos ChartAxis (com Chart.Axes como um ChartAxisCollection para iterar todos eles). Cada eixo possui HasMajorGridlines / HasMinorGridlines, MajorUnit / MinorUnit (com bandeiras *IsAuto correspondentes), Crosses / CrossesAt, CategoryType e um objeto TickLabels (AxisTickLabels) para fonte e orientação do rótulo. ChartAxis.Title (ChartAxisTitle) define o texto da legenda do eixo através de suas propriedades Text e Show.

Legenda, Título e Tabela de Dados

Chart.Title (ChartTitle) define a legenda geral do gráfico — Text, Show e Font. Chart.Legend (ChartLegend) controla se e onde a legenda aparece via Position (um valor LegendPosition como Bottom, Right ou Top) e expõe LegendEntries individuais. Chart.DataTable (ChartDataTable) pode exibir os valores das séries subjacentes como uma tabela abaixo da área do plot, com Show, HasLegendKeys e alternâncias de borda.

Formatando Elementos do Gráfico

A maioria dos elementos do gráfico — séries, pontos de dados, eixos, o título e a legenda — expõe uma propriedade Format do tipo ChartFormat, que por sua vez expõe Fill e Stroke para as cores desse elemento, além de um ShapeType (ChartShapeType) para formas de marcadores de ponto de dados. ChartFormat.SetDefaultFill() redefine um elemento para sua aparência padrão baseada no tema.

Dicas e Melhores Práticas

• Sempre limpe ou substitua a série de espaço reservado (chart.Series.Clear()) antes de adicionar dados reais — um gráfico recém-inserido vem com dados de exemplo já incluídos.
• Use as sobrecargas de ChartSeriesCollection.Add que correspondam ao formato dos seus dados (categorias, pares X/Y, datas ou tamanhos de bolhas) em vez de forçar tudo através de pares categoria/valor.
• Defina HasDataLabels = true em uma série antes de configurar sua coleção de DataLabels — as propriedades de exibição da coleção não têm efeito visível enquanto os rótulos estão desativados.
• Leia Chart.ChartSpace ou verifique o ChartType específico antes de confiar no comportamento de linhas de grade ou eixos que difere entre gráficos clássicos e no estilo Word-2016.
• Prefira ChartFormat.SetDefaultFill() a limpar manualmente cada propriedade de preenchimento quando quiser redefinir a aparência de um elemento.

Problemas Comuns

FAQ

Como inserir um gráfico em um documento?

Chame DocumentBuilder.InsertChart(chartType, width, height). Ele retorna o Shape que o contém; leia a propriedade Chart para configurar o gráfico.

Como adicionar dados a um gráfico?

Limpe a série placeholder com chart.Series.Clear(), então chame chart.Series.Add(seriesName, categories, values) (ou uma das outras sobrecargas Add para dados X/Y, de data ou de bolha).

Quais tipos de gráfico estão disponíveis?

ChartType inclui as famílias clássicas (Line, Bar, Column, Pie, Area, Scatter, Bubble, Radar, Stock, Surface, além de suas variantes empilhadas e 3D) e os tipos de gráfico do Word 2016 (Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall).

Como alterar onde a legenda aparece?

Defina Chart.Legend.Position para um valor LegendPosition, como LegendPosition.Bottom ou LegendPosition.Right.

Posso formatar um ponto de dados individual de maneira diferente do restante da sua série?

Sim — indexe em ChartSeries.DataPoints (um ChartDataPointCollection) e configure o Format, Marker ou Explosion desse ChartDataPoint de forma independente da formatação ao nível da série.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation