Introducción

Esta guía muestra cómo crear gráficos nativos de Word con Aspose.Words FOSS para .NET — los mismos objetos de dibujo que Word crea al usar Insertar > Gráfico — completamente mediante código. Un gráfico añadido de esta manera no es una imagen; es un objeto Chart incrustado en el paquete OOXML del documento, con un modelo de series de datos, ejes, una leyenda y una tabla de datos que Word aún puede abrir y editar después de guardar el archivo. Esta publicación es una inmersión profunda en ese API de Gráfico: cómo crear un gráfico, añadir datos de serie y acceder a los objetos de eje, leyenda, etiqueta de datos y formato que controlan cómo se renderiza.

La biblioteca tiene licencia MIT y no tiene dependencias nativas. Apunta a .NET Standard 2.0, por lo que el código de esta publicación se ejecuta sin cambios en .NET Framework 4.6.2+ y .NET 6, 8 y 10. Instálala vía NuGet, o compílala desde el código fuente — consulta Inicio rápido a continuación. Todo lo mostrado aquí es el mismo motor de gráficos usado por el comercial Aspose.Words para .NET; esta edición incluye el modelo completo de objetos de gráficos pero no el diseño de página ni el renderizado, por lo que la posición del gráfico en la página no se calcula y el documento no puede exportarse a PDF o a una imagen.

Qué incluye

Crear un gráfico y añadir una serie de datos

DocumentBuilder.InsertChart(chartType, width, height) inserta una forma de gráfico en la posición actual y devuelve un Shape; su propiedad Chart es el punto de entrada para todo lo demás. Un gráfico recién insertado ya tiene una serie predeterminada, por lo que la mayoría del código la elimina primero y añade sus propios datos a través de Chart.Series, un 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 tiene sobrecargas para pares categoría/valor (como arriba), pares X/Y, series con fechas y series de burbujas con un valor de tamaño adicional. En un ChartSeries individual, Add(xValue), Add(xValue, yValue) y Add(xValue, yValue, bubbleSize) añaden puntos únicos, Insert coloca un punto en un índice dado, y Clear() / ClearValues() eliminan datos de la serie sin necesariamente eliminar el propio objeto de serie.

Tipos de gráficos y tipos de series

ChartType — el enumerado pasado a InsertChart — tiene alrededor de 40 miembros que cubren las familias estándar de gráficos de Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall, y Funnel, más variantes apiladas, apiladas en porcentaje y 3D de varios de ellos (Bar3D, ColumnStacked, Area3DPercentStacked, etc.).

Un enumerado relacionado pero distinto, ChartSeriesType, aparece en ChartSeries.SeriesType y ChartSeriesGroup.SeriesType y describe el tipo de una serie individual o de un grupo de series en lugar del gráfico completo. Lleva los mismos miembros que ChartType más dos adicionales — ParetoLine y RegionMap — que ChartType no expone directamente. ChartSeriesGroup es lo que hace posibles los gráficos combinados: Chart.SeriesGroups (un ChartSeriesGroupCollection) contiene un grupo por tipo de serie en el gráfico, y cada grupo tiene su propio par AxisX/AxisY y propiedades de diseño como Overlap, GapWidth, BubbleScale y DoughnutHoleSize.

Ejes, líneas de cuadrícula y escalado

Chart.AxisX, AxisY y AxisZ (más la colección Axes) devuelven objetos ChartAxis. Cada eje tiene un Type (ChartAxisType.Category, Series o Value), ajustes de marcas de graduación (MajorTickMark, MinorTickMark — Cross, Inside, Outside o None), indicadores de líneas de cuadrícula (HasMajorGridlines, HasMinorGridlines) y control de unidades (MajorUnit, MinorUnit y sus contrapartes *IsAuto). ChartAxis.Scaling devuelve un objeto AxisScaling cuyo Minimum y Maximum son valores AxisBound — AxisBound.IsAuto indica si el límite se calcula automáticamente, y los constructores parametrizados (AxisBound(value), AxisBound(datetime)) establecen un límite numérico o de fecha explícito. Un eje de categoría puede fijarse a categorías de texto o tiempo mediante ChartAxis.CategoryType (AxisCategoryType.Automatic, Category o Time), y ChartAxis.Title expone un ChartAxisTitle con su propio Text, Show y Font.

Leyenda, tabla de datos y título del gráfico

Chart.Legend devuelve un ChartLegend, cuyo Position (una LegendPosition de None, Bottom, Left, Right, Top o TopRight) controla dónde se renderiza respecto al área del gráfico; LegendEntries es un ChartLegendEntryCollection de objetos ChartLegendEntry individuales, cada uno con su propio Font y bandera IsHidden para ocultar una sola serie de la leyenda sin eliminarla del gráfico. Chart.DataTable (un ChartDataTable) muestra los valores de la serie como una cuadrícula bajo el gráfico cuando Show está activado, con HasLegendKeys, HasHorizontalBorder, HasVerticalBorder y HasOutlineBorder controlando su apariencia. Chart.Title es un ChartTitle con propiedades Text y Show, siguiendo el mismo patrón que los títulos de los ejes.

Etiquetas de datos, puntos de datos y marcadores

ChartSeries.HasDataLabels activa las etiquetas de datos para una serie, y ChartSeries.DataLabels (un ChartDataLabelCollection) o un ChartDataLabel individual de ella controla lo que muestra cada etiqueta: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey y ShowBubbleSize son banderas independientes, y Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit y otros) posiciona la etiqueta respecto a su punto. ChartSeries.DataPoints brinda acceso por punto a través de ChartDataPoint, que lleva su propio Marker (un ChartMarker con Symbol del enum MarkerSymbol y un Size), Explosion (para extraer una porción de pastel), y Format. Cada elemento del gráfico que pueda rellenarse o delinearse — series, puntos de datos, la leyenda, el título, la tabla de datos — expone un ChartFormat a través de su propiedad Format, con propiedades Fill, Stroke y ShapeType (ChartShapeType) y un método SetDefaultFill() para restablecerlo. Un detalle a tener en cuenta: las variantes vinculadas al tema de color de relleno y trazo en ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor y sus contrapartes de matiz/sombra) no están implementadas en esta edición — establezca colores simples Fill/Stroke en lugar de referencias a colores de tema. Chart.Style (un ChartStyle como Muted, Saturated, Gradient, Outline o Black) aplica un aspecto predefinido a todo el gráfico en un solo paso.

Inicio rápido

Aspose.Words FOSS para .NET está disponible a través de NuGet:

dotnet add package Aspose.Words.FOSS

Para compilar desde el código fuente en su lugar:

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

A continuación, añada una referencia de proyecto a Aspose.Words.csproj desde su aplicación. Con la referencia en su lugar, esto crea un gráfico de líneas con una serie y lo guarda en 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 en Word y el gráfico es totalmente editable — haga clic derecho sobre él y elija “Edit Data” para ver las mismas tres categorías y valores escritos arriba.

Formatos compatibles

FormatoExtensiónLeerEscribir
DOCX.docx✓✓
DOCM.docm✓✓
DOTX.dotx✓✓
DOTM.dotm✓✓
Flat OPC (todas las variantes)(varios)✓✓
Markdown.md✓✓
Text.txt✓✓

Los gráficos creados con el Chart API son objetos de dibujo OOXML, por lo que pueden circular entre los formatos de la familia DOCX mencionados (DOCX, DOCM, DOTX, DOTM y Flat OPC). Esta edición no puede exportar a PDF, XPS o imágenes y no puede imprimir, de modo que nada renderiza un gráfico a un mapa de bits — el gráfico permanece como un objeto vivo y editable dentro del archivo de Word. Los convertidores de formato adicionales eliminados de esta edición (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 y WordML) son los mismos subsistemas excluidos en todas partes de la biblioteca, no algo específico de los gráficos.

Código abierto y licencias

Aspose.Words FOSS para .NET se publica bajo la licencia MIT, libre para uso comercial y personal sin royalties ni restricciones de redistribución. El código fuente completo, incluidas las clases de gráficos referenciadas en esta publicación, está disponible en GitHub en el Aspose.Words FOSS para .NET repositorio.

Primeros pasos

Recursos Relacionados