Trabajar con etiquetas de datos en gráficos mediante la API de JavaScript de Excel

Agregue etiquetas de datos a gráficos de Excel para proporcionar una mejor experiencia de visualización sobre aspectos importantes del gráfico. Para obtener más información sobre las etiquetas de datos, consulte Agregar o quitar etiquetas de datos en un gráfico.

En el ejemplo de código siguiente se configuran los datos de ejemplo y el gráfico de producción de piezas de bicicleta que se usan en este artículo.

async function setup() {
  await Excel.run(async (context) => {
    context.workbook.worksheets.getItemOrNullObject("Sample").delete();
    const sheet = context.workbook.worksheets.add("Sample");

    let salesTable = sheet.tables.add("A1:E1", true);
    salesTable.name = "SalesTable";

    salesTable.getHeaderRowRange().values = [["Product", "Qtr1", "Qtr2", "Qtr3", "Qtr4"]];

    salesTable.rows.add(null, [
      ["Frames", 5000, 7000, 6544, 5377],
      ["Saddles", 400, 323, 276, 1451],
      ["Brake levers", 9000, 8766, 8456, 9812],
      ["Chains", 1550, 1088, 692, 2553],
      ["Mirrors", 225, 600, 923, 344],
      ["Spokes", 6005, 7634, 4589, 8765]
    ]);

    sheet.activate();
    createChart(context);
  });
}

async function createChart(context: Excel.RequestContext) {
  const worksheet = context.workbook.worksheets.getActiveWorksheet();
  const chart = worksheet.charts.add(
    Excel.ChartType.lineMarkers,
    worksheet.getRange("A1:E7"),
    Excel.ChartSeriesBy.rows
  );
  chart.axes.categoryAxis.setCategoryNames(worksheet.getRange("B1:E1"));
  chart.name = "PartChart";

  // Place the chart below sample data.
  chart.top = 125;
  chart.left = 5;
  chart.height = 300;
  chart.width = 450;

  chart.title.text = "Bicycle Part Production";
  chart.legend.position = "Bottom";

  await context.sync();
}

Esta imagen muestra cómo se debe mostrar el gráfico después de ejecutar el código de ejemplo.

Agregar etiquetas de datos

Para agregar etiquetas de datos a un gráfico, obtenga la serie de puntos de datos que desea cambiar y establezca la hasDataLabels propiedad en true.

async function addDataLabels() {
  await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    const chart = worksheet.charts.getItem("PartChart");
    await context.sync();

    // Get spokes data series.
    const series = chart.series.getItemAt(5);

    // Turn on data labels and set location.
    series.hasDataLabels = true;
    series.dataLabels.position = Excel.ChartDataLabelPosition.top;
    await context.sync();
  });
}

Formato del tamaño, la forma y el texto de la etiqueta de datos

Puede cambiar los atributos en las etiquetas de datos mediante las siguientes API.

• Cambie las formas de etiqueta de datos estableciendo la propiedad geometricShapeType .
• Cambie el alto y el ancho mediante los métodos setWidth y setHeight .
• Cambie el texto mediante la propiedad text .
• Cambie el formato de texto mediante la propiedad format . Puede cambiar las propiedades de borde, relleno y fuente .

En el ejemplo de código siguiente se muestra cómo establecer el tipo de forma, el alto y el ancho, y el formato de fuente para las etiquetas de datos.

 await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    const chart = worksheet.charts.getItem("PartChart");
    const series = chart.series.getItemAt(5);

    // Set geometric shape of data labels to cubes.
    series.dataLabels.geometricShapeType = Excel.GeometricShapeType.cube;
    series.points.load("count");
    await context.sync();
    let pointsLoaded = series.points.count;

    // Change height, width, and font size of all data labels.
    for (let j = 0; j < pointsLoaded; j++) {
      series.points.getItemAt(j).dataLabel.setWidth(60);
      series.points.getItemAt(j).dataLabel.setHeight(30);
      series.points.getItemAt(j).dataLabel.format.font.size = 12;
    }

    // Set text of a data label.
    series.points.getItemAt(2).dataLabel.setWidth(80);
    series.points.getItemAt(2).dataLabel.setHeight(50);
    series.points.getItemAt(2).dataLabel.text = "Spokes Qtr3: 4589 ↓";

    await context.sync();
});

En la captura de pantalla siguiente, el gráfico ahora incluye etiquetas de datos de recuento para los datos spokes , con texto personalizado en el tercer punto de datos.

También puede cambiar el formato del texto en una etiqueta de datos. En el ejemplo de código siguiente se muestra cómo usar el método getSubstring para obtener parte del texto de la etiqueta de datos y aplicar el formato de fuente.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    const chart = worksheet.charts.getItem("PartChart");
    const series = chart.series.getItemAt(5);

    // Get the "Spokes" data label.
    let label = series.points.getItemAt(2).dataLabel;
    label.load();
    await context.sync();

    // Change border weight of this label.
    label.format.border.weight = 2;
    // Format "Qtr3" as bold and italicized. 
    label.getSubstring(7, 4).font.bold = true;
    label.getSubstring(7, 4).font.italic = true;
    // Format "Spokes" as green.
    label.getSubstring(0, 6).font.color = "green";
    // Format "4589" as red.
    label.getSubstring(12).font.color = "red";
    // Move label up by 15 points.
    label.top = label.top - 15;

    await context.sync();
 });

Dar formato a las líneas de directriz

Las líneas de directriz conectan las etiquetas de datos a sus respectivos puntos de datos y facilitan la visualización de lo que hacen referencia en el gráfico. Active las líneas de directriz mediante la propiedad showLeaderLines . Puede establecer el formato de las líneas de directriz con la propiedad leaderLines.format .

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    const chart = worksheet.charts.getItem("PartChart");
    const series = chart.series.getItemAt(5);
    
    // Show leader lines.
    series.showLeaderLines = true;
    await context.sync();
    
    // Format leader lines as dotted orange lines with weight 2.
    series.dataLabels.leaderLines.format.line.lineStyle = Excel.ChartLineStyle.dot;
    series.dataLabels.leaderLines.format.line.color = "orange";
    series.dataLabels.leaderLines.format.line.weight = 2;
});

Creación de llamadas

Una llamada es una etiqueta de datos que se conecta al punto de datos mediante un puntero con forma de burbuja. Una llamada tiene un delimitador que se puede mover desde el punto de datos a otras ubicaciones del gráfico.

En el ejemplo de código siguiente se muestra cómo cambiar las etiquetas de datos de una serie para usar Excel.GeometricShapeType.wedgeRectCallout. Tenga en cuenta que las líneas de directriz están desactivadas para evitar mostrar dos indicadores en la misma etiqueta de datos.

 await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    const chart = worksheet.charts.getItem("PartChart");
    const series = chart.series.getItemAt(5);

    // Change to a wedge rectangle style callout.
    series.dataLabels.geometricShapeType = Excel.GeometricShapeType.wedgeRectCallout;
    series.showLeaderLines = false;
    await context.sync();
});

En el ejemplo de código siguiente se muestra cómo cambiar la ubicación del delimitador de una etiqueta de datos.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    const chart = worksheet.charts.getItem("PartChart");
    const series = chart.series.getItemAt(5);

    let label = series.points.getItemAt(2).dataLabel;
    let point = series.points.getItemAt(2);
    label.load();
    await context.sync();

    let anchor = label.getTailAnchor();
    anchor.load();
    await context.sync();

    anchor.top = anchor.top - 10;
    anchor.left = 40;
});

En esta captura de pantalla se muestra cómo se ajusta el delimitador de la tercera etiqueta de datos mediante el ejemplo de código anterior.

Vea también

• Modelo de objetos de JavaScript en Excel para Complementos de Office
• Trabajar con gráficos mediante la API de JavaScript de Excel