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.FOSSPara 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
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| 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.
