Trabajando con Gráficos

Trabajando con gráficos

Aspose.Words FOSS para .NET puede insertar gráficos nativos de Word — los mismos gráficos DrawingML que Word crea — como una forma en la capa de dibujo. DocumentBuilder.InsertChart crea la forma y la devuelve; la propiedad Chart de la forma expone series, ejes, leyenda y formato. Esta guía cubre la creación de un gráfico, la elección del tipo de gráfico, el trabajo con series y puntos de datos, ejes y líneas de cuadrícula, y el formato de los elementos del gráfico.

Crear un gráfico

Llame a DocumentBuilder.InsertChart(chartType, width, height) para insertar una forma de gráfico en el cursor y obtener de regreso el Shape contenedor. Su propiedad Chart es el objeto Chart que configura. Un gráfico recién insertado incluye series de demostración de marcador de posición, así que limpie Chart.Series antes de añadir datos reales con 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 ejemplo construye un Document, usa DocumentBuilder.InsertChart(ChartType.Line, 432, 252) para insertar una forma de gráfico de líneas, lee shape.Chart para obtener el objeto Chart, llama a chart.Series.Clear() para eliminar la serie de marcador de posición, agrega una serie real con chart.Series.Add(seriesName, categories, values), y escribe el resultado con Document.Save.

Tipos de gráficos

ChartType cubre las familias estándar de gráficos de Word — Line, Bar, Column (más sus variantes Stacked, PercentStacked y 3D), Pie, PieOfPie, Doughnut, Area, Scatter, Bubble, Radar, Stock, Surface, y los tipos de gráficos más recientes de Word 2016 Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker y Waterfall. Pase el valor deseado como argumento chartType a InsertChart; no hay forma de cambiar el tipo de un gráfico existente después de la inserción salvo reemplazando la forma.

Series y puntos de datos

Chart.Series es un ChartSeriesCollection de objetos ChartSeries. Más allá de la sobrecarga Add(seriesName, categories, values) utilizada arriba, ChartSeriesCollection también tiene sobrecargas para pares de valores X/Y, fechas y tamaños de burbuja, además de Insert, Remove(index) y Clear(). Cada ChartSeries expone DataPoints (un ChartDataPointCollection) para el formateo por punto — Format, Marker, Explosion y InvertIfNegative — y HasDataLabels / DataLabels para activar y configurar un ChartDataLabelCollection (ShowValue, ShowCategoryName, ShowPercentage, Position).

Ejes y líneas de cuadrícula

Chart.AxisX, AxisY y AxisZ son objetos ChartAxis (con Chart.Axes como un ChartAxisCollection para iterar todos ellos). Cada eje tiene HasMajorGridlines / HasMinorGridlines, MajorUnit / MinorUnit (con banderas *IsAuto coincidentes), Crosses / CrossesAt, CategoryType, y un objeto TickLabels (AxisTickLabels) para la fuente y orientación de la etiqueta. ChartAxis.Title (ChartAxisTitle) establece el texto de la leyenda del eje a través de sus propiedades Text y Show.

Leyenda, título y tabla de datos

Chart.Title (ChartTitle) establece la leyenda general del gráfico — Text, Show y Font. Chart.Legend (ChartLegend) controla si y dónde aparece la leyenda mediante Position (un valor LegendPosition como Bottom, Right o Top) y expone LegendEntries individuales. Chart.DataTable (ChartDataTable) puede mostrar los valores subyacentes de las series como una tabla debajo del área del gráfico, con Show, HasLegendKeys y conmutadores de borde.

Formato de los elementos del gráfico

La mayoría de los elementos del gráfico — series, puntos de datos, ejes, el título y la leyenda — exponen una propiedad Format de tipo ChartFormat, que a su vez expone Fill y Stroke para los colores de ese elemento, además de un ShapeType (ChartShapeType) para las formas de los marcadores de puntos de datos. ChartFormat.SetDefaultFill() restablece un elemento a su apariencia predeterminada basada en el tema.

Consejos y mejores prácticas

• Siempre borra o reemplaza la serie de marcadores (chart.Series.Clear()) antes de añadir datos reales — un gráfico recién insertado incluye datos de muestra ya incorporados.
• Utiliza sobrecargas de ChartSeriesCollection.Add que coincidan con la forma de tus datos (categorías, pares X/Y, fechas o tamaños de burbuja) en lugar de forzar todo a través de pares categoría/valor.
• Configura HasDataLabels = true en una serie antes de configurar su colección DataLabels — las propiedades de visualización de la colección no tienen efecto visible mientras las etiquetas están desactivadas.
• Lee Chart.ChartSpace o verifica el ChartType específico antes de confiar en el comportamiento de líneas de cuadrícula o ejes que difiere entre los gráficos clásicos y los de estilo Word-2016.
• Prefiere ChartFormat.SetDefaultFill() en lugar de borrar manualmente cada propiedad de relleno cuando deseas restablecer la apariencia de un elemento.

Problemas comunes

FAQ

¿Cómo inserto un gráfico en un documento?

Llame a DocumentBuilder.InsertChart(chartType, width, height). Devuelve el Shape que lo contiene; lea su propiedad Chart para configurar el gráfico.

¿Cómo agrego datos a un gráfico?

Borre la serie de marcador de posición con chart.Series.Clear(), luego llame a chart.Series.Add(seriesName, categories, values) (o a una de las otras sobrecargas de Add para datos X/Y, de fecha o de burbuja).

¿Qué tipos de gráficos están disponibles?

ChartType incluye las familias clásicas (Line, Bar, Column, Pie, Area, Scatter, Bubble, Radar, Stock, Surface, además de sus variantes apiladas y 3D) y los tipos de gráficos de Word 2016 (Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall).

¿Cómo cambio dónde aparece la leyenda?

Establezca Chart.Legend.Position a un valor LegendPosition, como LegendPosition.Bottom o LegendPosition.Right.

¿Puedo formatear un punto de datos individual de forma diferente al resto de su serie?

Sí — indexa en ChartSeries.DataPoints (un ChartDataPointCollection) y establece el Format, Marker o Explosion de ese ChartDataPoint de forma independiente del formato a nivel de serie.

API Reference Resumen

Ver también

• Aspose.Words for .NET — Enterprise Documentation