Introdução

Este guia mostra como criar gráficos nativos do Word com Aspose.Words FOSS para .NET — os mesmos objetos de desenho que o próprio Word cria ao usar Inserir > Gráfico — inteiramente a partir de código. Um gráfico adicionado dessa forma não é uma imagem; é um objeto Chart incorporado no pacote OOXML do documento, com um modelo de série de dados, eixos, uma legenda e uma tabela de dados que o Word ainda pode abrir e editar após o arquivo ser salvo. Esta publicação é uma análise aprofundada desse Chart API: como criar um gráfico, adicionar dados de série e acessar os objetos de eixo, legenda, rótulo de dados e formatação que controlam como ele é renderizado.

A biblioteca tem licença MIT e não possui dependências nativas. Ela tem como alvo .NET Standard 2.0, portanto o código desta publicação roda inalterado no .NET Framework 4.6.2+ e no .NET 6, 8 e 10. Instale-a via NuGet, ou compile-a a partir do código-fonte — veja o Início Rápido abaixo. Tudo o que é mostrado aqui é o mesmo mecanismo de gráfico usado pelo comercial Aspose.Words para .NET; esta edição inclui o modelo completo de objetos de gráfico, mas não o layout de página ou a renderização, de modo que a posição do gráfico na página não é calculada e o documento não pode ser exportado para PDF ou imagem.


O que está incluído

Criando um Gráfico e Adicionando uma Série de Dados

DocumentBuilder.InsertChart(chartType, width, height) insere uma forma de gráfico na posição atual e retorna um Shape; sua propriedade Chart é o ponto de entrada para todo o resto. Um gráfico recém-inserido já possui uma série padrão, portanto a maioria do código a limpa primeiro e adiciona seus próprios dados através de Chart.Series, um ChartSeriesCollection.

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 });

ChartSeriesCollection.Add tem sobrecargas para pares categoria/valor (como acima), pares de valores X/Y, séries datadas e séries de bolhas com um valor de tamanho extra. Em um ChartSeries individual, Add(xValue), Add(xValue, yValue) e Add(xValue, yValue, bubbleSize) adicionam pontos únicos, Insert coloca um ponto em um índice específico, e Clear() / ClearValues() removem dados da série sem necessariamente remover o próprio objeto da série.

Tipos de Gráficos e Tipos de Séries

ChartType — o enum passado para InsertChart — tem cerca de 40 membros que cobrem as famílias padrão de gráficos do Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall e Funnel, além das variantes empilhadas, empilhadas em porcentagem e 3D de várias delas (Bar3D, ColumnStacked, Area3DPercentStacked, etc.).

Um enum relacionado, porém distinto, ChartSeriesType, aparece em ChartSeries.SeriesType e ChartSeriesGroup.SeriesType e descreve o tipo de uma série individual ou grupo de séries, em vez do gráfico como um todo. Ele contém os mesmos membros de ChartType mais dois adicionais — ParetoLine e RegionMap — que ChartType não expõe diretamente. ChartSeriesGroup é o que torna os gráficos combinados possíveis: Chart.SeriesGroups (um ChartSeriesGroupCollection) contém um grupo por tipo de série no gráfico, e cada grupo tem seu próprio par AxisX/AxisY e propriedades de layout como Overlap, GapWidth, BubbleScale e DoughnutHoleSize.

Eixos, Linhas de Grade e Escalonamento

Chart.AxisX, AxisY e AxisZ (além da coleção Axes) retornam objetos ChartAxis. Cada eixo possui um Type (ChartAxisType.Category, Series ou Value), configurações de marcações de escala (MajorTickMark, MinorTickMark — Cross, Inside, Outside ou None), flags de linhas de grade (HasMajorGridlines, HasMinorGridlines) e controle de unidades (MajorUnit, MinorUnit e seus equivalentes *IsAuto). ChartAxis.Scaling devolve um objeto AxisScaling cujo Minimum e Maximum são valores AxisBound — AxisBound.IsAuto indica se o limite é calculado automaticamente, e os construtores parametrizados (AxisBound(value), AxisBound(datetime)) definem um limite numérico ou de data explícito. Um eixo de categoria pode ser fixado a categorias de texto ou tempo através de ChartAxis.CategoryType (AxisCategoryType.Automatic, Category ou Time), e ChartAxis.Title expõe um ChartAxisTitle com seu próprio Text, Show e Font.

Legenda, Tabela de Dados e Título do Gráfico

Chart.Legend retorna um ChartLegend, cujo Position (um LegendPosition de None, Bottom, Left, Right, Top ou TopRight) controla onde ele é renderizado em relação à área de plotagem; LegendEntries é um ChartLegendEntryCollection de objetos ChartLegendEntry individuais, cada um com seu próprio Font e flag IsHidden para ocultar uma única série da legenda sem removê-la do gráfico. Chart.DataTable (um ChartDataTable) renderiza os valores das séries como uma grade abaixo do gráfico quando Show está definido, com HasLegendKeys, HasHorizontalBorder, HasVerticalBorder e HasOutlineBorder controlando sua aparência. Chart.Title é um ChartTitle com propriedades Text e Show, seguindo o mesmo padrão dos títulos dos eixos.

Rótulos de Dados, Pontos de Dados e Marcadores

ChartSeries.HasDataLabels ativa rótulos de dados para uma série, e ChartSeries.DataLabels (um ChartDataLabelCollection) ou um ChartDataLabel individual dela controla o que cada rótulo exibe: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey e ShowBubbleSize são sinalizadores independentes, e Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit e outros) posiciona o rótulo em relação ao seu ponto. ChartSeries.DataPoints fornece acesso por ponto através de ChartDataPoint, que possui seu próprio Marker (um ChartMarker com Symbol do enum MarkerSymbol e um Size), Explosion (para extrair uma fatia de pizza) e Format. Cada elemento de gráfico que pode ser preenchido ou contornado — séries, pontos de dados, a legenda, o título, a tabela de dados — expõe um ChartFormat por meio da sua propriedade Format, com propriedades Fill, Stroke e ShapeType (ChartShapeType) e um método SetDefaultFill() para redefini-lo. Um detalhe importante: as variantes vinculadas ao tema de cor de preenchimento e contorno em ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor e seus equivalentes de tonalidade/sombra) não são implementadas nesta edição — defina cores simples Fill/Stroke em vez de referências de cor de tema. Chart.Style (um ChartStyle como Muted, Saturated, Gradient, Outline ou Black) aplica um visual predefinido a todo o gráfico em um passo.


Início Rápido

Aspose.Words FOSS para .NET está disponível via NuGet:

dotnet add package Aspose.Words.FOSS

Para compilar a partir do código-fonte:

git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release

Em seguida, adicione uma referência de projeto a Aspose.Words.csproj a partir da sua aplicação. Com a referência adicionada, isso cria um gráfico de linhas com uma série e o salva em DOCX:

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");
Console.WriteLine("Saved chart.docx");

Abra chart.docx no Word e o gráfico será totalmente editável — clique com o botão direito nele e escolha “Edit Data” para ver as mesmas três categorias e valores escritos acima.


Formatos Suportados

FormatoExtensãoLerEscrever
DOCX.docx✓✓
DOCM.docm✓✓
DOTX.dotx✓✓
DOTM.dotm✓✓
Flat OPC (todas as variantes)(vários)✓✓
Markdown.md✓✓
Text.txt✓✓

Os gráficos criados com o Chart API são objetos de desenho OOXML, portanto eles mantêm a integridade ao atravessar os formatos da família DOCX acima (DOCX, DOCM, DOTX, DOTM e Flat OPC). Esta edição não pode exportar para PDF, XPS ou imagens e não pode imprimir, portanto nada renderiza um gráfico para bitmap — o gráfico permanece um objeto ao vivo, editável dentro do arquivo Word. Os conversores de formato adicionais removidos desta edição (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 e WordML) são os mesmos subsistemas excluídos em todo o resto da biblioteca, não algo específico dos gráficos.


Código Aberto e Licenciamento

Aspose.Words FOSS para .NET é lançado sob a licença MIT, gratuito para uso comercial e pessoal sem royalties ou restrições de redistribuição. O código-fonte completo, incluindo as classes de gráfico referenciadas neste post, está disponível em GitHub no Aspose.Words FOSS para o repositório .NET.


Começando

Recursos Relacionados