Trabajar con gráficos mediante la API de JavaScript de Excel

Este artículo ofrece ejemplos que muestran cómo realizar tareas comunes con gráficos mediante la API de JavaScript de Excel. Para obtener la lista completa de propiedades y métodos compatibles con los objetos y, vea Chart Object (API de Chart ChartCollection JavaScript para Excel) y Chart Collection Object (API de JavaScript para Excel).

Crear un gráfico

The following code sample creates a chart in the worksheet named Sample. The chart is a Line chart that is based upon data in the range A1:B13.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var dataRange = sheet.getRange("A1:B13");
    var chart = sheet.charts.add("Line", dataRange, "auto");

    chart.title.text = "Sales Data";
    chart.legend.position = "right"
    chart.legend.format.fill.setSolidColor("white");
    chart.dataLabels.format.font.size = 15;
    chart.dataLabels.format.font.color = "black";

    return context.sync();
}).catch(errorHandlerFunction);

Nuevo gráfico de líneas

Nuevo gráfico de líneas en Excel.

Agregar una serie de datos a un gráfico

The following code sample adds a data series to the first chart in the worksheet. The new data series corresponds to the column named 2016 and is based upon data in the range D2:D5.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");
    var chart = sheet.charts.getItemAt(0);
    var dataRange = sheet.getRange("D2:D5");

    var newSeries = chart.series.add("2016");
    newSeries.setValues(dataRange);

    return context.sync();
}).catch(errorHandlerFunction);

Gráfico antes de que se agregue la serie de datos de 2016

Gráfico en Excel antes de agregar la serie de datos de 2016.

Gráfico después de que se agregue la serie de datos de 2016

Gráfico en Excel después de agregar la serie de datos de 2016.

Establecer el título del gráfico

En el ejemplo de código siguiente se establece el título del primer gráfico en la hoja de cálculo en Datos de ventas por año.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var chart = sheet.charts.getItemAt(0);
    chart.title.text = "Sales Data by Year";

    return context.sync();
}).catch(errorHandlerFunction);

Gráfico después de que se establezca el título

Gráfico con título en Excel.

Establecer propiedades de un eje en un gráfico

Los gráficos que usan el sistema de coordenadas cartesianas, como los gráficos de dispersión, los gráficos de barras y los gráficos de columnas, contienen un eje de categoría y un eje de valores. Estos ejemplos muestran cómo establecer el título y mostrar la unidad de un eje en un gráfico.

Establecer el título del eje

El ejemplo de código siguiente establece el título del eje de categoría para el primer gráfico de la hoja de cálculo en Producto.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var chart = sheet.charts.getItemAt(0);
    chart.axes.categoryAxis.title.text = "Product";

    return context.sync();
}).catch(errorHandlerFunction);

Gráfico después de que se establezca el título del eje de categoría

Gráfico con título de eje en Excel.

Establecer la unidad de visualización del eje

El ejemplo de código siguiente establece la unidad de visualización del eje de valores para el primer gráfico de la hoja de cálculo en Cientos.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var chart = sheet.charts.getItemAt(0);
    chart.axes.valueAxis.displayUnit = "Hundreds";

    return context.sync();
}).catch(errorHandlerFunction);

Gráfico después de que se establezca la unidad de visualización del eje de valores

Gráfico con unidad de visualización de eje en Excel.

Establecer la visibilidad de las líneas de cuadrícula en un gráfico

El ejemplo de código siguiente oculta las líneas de cuadrícula principales para el eje de valores del primer gráfico de la hoja de cálculo. Puede mostrar las líneas de cuadrícula principales para el eje de valores del gráfico, estableciendo chart.axes.valueAxis.majorGridlines.visible como true .

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var chart = sheet.charts.getItemAt(0);
    chart.axes.valueAxis.majorGridlines.visible = false;

    return context.sync();
}).catch(errorHandlerFunction);

Gráfico con las líneas de cuadrícula ocultas

Gráfico con líneas de cuadrícula ocultas en Excel.

Líneas de tendencia de gráfico

Agregar una línea de tendencia

En el ejemplo de código siguiente se agrega una línea de tendencia de media móvil a la primera serie del primer gráfico en la hoja de cálculo denominada Ejemplo. La línea de tendencia muestra una media móvil de más de 5 periodos.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var chart = sheet.charts.getItemAt(0);
    var seriesCollection = chart.series;
    seriesCollection.getItemAt(0).trendlines.add("MovingAverage").movingAveragePeriod = 5;

    return context.sync();
}).catch(errorHandlerFunction);

Gráfico con línea de tendencia de media móvil

Gráfico con línea de tendencia de media móvil en Excel.

Actualizar una línea de tendencia

En el ejemplo de código siguiente se establece la línea de tendencia para escribir para la primera serie del Linear primer gráfico de la hoja de cálculo denominada Sample.

Excel.run(function (context) {
    var sheet = context.workbook.worksheets.getItem("Sample");

    var chart = sheet.charts.getItemAt(0);
    var seriesCollection = chart.series;
    var series = seriesCollection.getItemAt(0);
    series.trendlines.getItem(0).type = "Linear";

    return context.sync();
}).catch(errorHandlerFunction);

Gráfico con línea de tendencia lineal

Gráfico con línea de tendencia lineal en Excel.

Agregar y dar formato a una tabla de datos del gráfico

Puede obtener acceso al elemento de tabla de datos de un gráfico con el Chart.getDataTableOrNullObject método. Este método devuelve el ChartDataTable objeto. El ChartDataTable objeto tiene propiedades de formato booleano como , y visible showLegendKey showHorizontalBorder .

La propiedad devuelve el objeto, que permite dar más formato y ChartDataTable.format estilo a la tabla de ChartDataTableFormat datos. El ChartDataTableFormat objeto ofrece , y border fill font propiedades.

En el ejemplo de código siguiente se muestra cómo agregar una tabla de datos a un gráfico y, a continuación, dar formato a esa tabla de datos mediante ChartDataTable los objetos ChartDataTableFormat and.

// This code sample adds a data table to a chart that already exists on the worksheet, 
// and then adjusts the display and format of that data table.
Excel.run(function (context) {
    // Retrieve the chart on the "Sample" worksheet.
    var chart = context.workbook.worksheets.getItem("Sample").charts.getItemAt(0);

    // Get the chart data table object and load its properties.
    var chartDataTable = chart.getDataTableOrNullObject();
    chartDataTable.load();

    // Set the display properties of the chart data table.
    chartDataTable.visible = true;
    chartDataTable.showLegendKey = true;
    chartDataTable.showHorizontalBorder = false;
    chartDataTable.showVerticalBorder = true;
    chartDataTable.showOutlineBorder = true;

    // Retrieve the chart data table format object and set font and border properties. 
    var chartDataTableFormat = chartDataTable.format;
    chartDataTableFormat.font.color = "#B76E79";
    chartDataTableFormat.font.name = "Comic Sans";
    chartDataTableFormat.border.color = "blue";

    return context.sync();
}).catch(errorHandlerFunction);

La siguiente captura de pantalla muestra la tabla de datos que crea el ejemplo de código anterior.

Un gráfico con una tabla de datos que muestra el formato personalizado de la tabla de datos.

Exportar un gráfico como una imagen

Los gráficos se pueden representar como imágenes fuera de Excel. Chart.getImage devuelve el gráfico como una cadena con codificación base 64 que representa el gráfico como una imagen JPEG. El código siguiente muestra cómo obtener la cadena de imagen y registrarla en la consola.

Excel.run(function (ctx) {
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
    var imageAsString = chart.getImage();
    return context.sync().then(function () {
        console.log(imageAsString.value);
        // Instead of logging, your add-in may use the base64-encoded string to save the image as a file or insert it in HTML.
    });
}).catch(errorHandlerFunction);

Chart.getImage admite tres parámetros opcionales: ancho, alto y el modo de ajuste.

getImage(width?: number, height?: number, fittingMode?: Excel.ImageFittingMode): OfficeExtension.ClientResult<string>;

Estos parámetros determinan el tamaño de la imagen. Las imágenes siempre se incrementan proporcionalmente. Los parámetros de ancho y alto establecen límites superiores o inferiores en la imagen aumentada. ImageFittingMode tiene tres valores con los siguientes comportamientos.

  • Fill: El alto o ancho mínimo de la imagen es el alto o ancho especificados (lo que se alcance primero al escalar la imagen). Este es el comportamiento predeterminado cuando no se especifica el modo de ajuste.
  • Fit: El alto o ancho máximo de la imagen es el alto o ancho especificados (lo que se alcance primero al escalar la imagen).
  • FitAndCenter: El alto o ancho máximo de la imagen es el alto o ancho especificados (lo que se alcance primero al escalar la imagen). La imagen resultante se centra en relación con la otra dimensión.

Vea también