Trabalhar com etiquetas de dados em gráficos com a API JavaScript do Excel

Adicione etiquetas de dados a gráficos do Excel para proporcionar uma melhor experiência de visualização sobre aspetos importantes do gráfico. Para saber mais sobre etiquetas de dados, consulte Adicionar ou remover etiquetas de dados num gráfico.

O exemplo de código seguinte configura os dados de exemplo e o gráfico de Produção de Peças de Bicicleta utilizado neste artigo.

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 imagem mostra como o gráfico deve ser apresentado depois de executar o código de exemplo.

Adicionar etiquetas de dados

Para adicionar etiquetas de dados a um gráfico, obtenha a série de pontos de dados que pretende alterar e defina a hasDataLabels propriedade como 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();
  });
}

Formatar o tamanho, a forma e o texto da etiqueta de dados

Pode alterar atributos em etiquetas de dados com as seguintes APIs.

• Altere as formas da etiqueta de dados ao definir a propriedade geometricShapeType .
• Altere a altura e a largura com os métodos setWidth e setHeight .
• Altere o texto com a propriedade text .
• Altere a formatação do texto com a propriedade format . Pode alterar as propriedades do limite, preenchimento e tipo de letra .

O seguinte exemplo de código mostra como definir o tipo de forma, a altura e a largura e a formatação do tipo de letra para as etiquetas de dados.

 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();
});

Na captura de ecrã seguinte, o gráfico inclui agora a contagem de etiquetas de dados para os dados spokes , com texto personalizado no terceiro ponto de dados.

Também pode alterar a formatação do texto numa etiqueta de dados. O seguinte exemplo de código mostra como utilizar o método getSubstring para obter parte do texto da etiqueta de dados e aplicar formatação de tipo de letra.

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();
 });

Formatar linhas de preenchimento

As linhas de preenchimento ligam as etiquetas de dados aos respetivos pontos de dados e facilitam a visualização do que se referem no gráfico. Ative as linhas de preenchimento utilizando a propriedade showLeaderLines . Pode definir o formato das linhas de preenchimento com a propriedade 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;
});

Criar notas de aviso

Uma nota de aviso é uma etiqueta de dados que se liga ao ponto de dados com um ponteiro em forma de bolha. Uma nota de aviso tem uma âncora que pode ser movida do ponto de dados para outras localizações no gráfico.

O seguinte exemplo de código mostra como alterar etiquetas de dados numa série para utilizar Excel.GeometricShapeType.wedgeRectCallout. Tenha em atenção que as linhas de preenchimento estão desativadas para evitar mostrar dois indicadores à mesma etiqueta de dados.

 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();
});

O seguinte exemplo de código mostra como alterar a localização de âncora de uma etiqueta de dados.

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;
});

Esta captura de ecrã demonstra como a âncora da terceira etiqueta de dados é ajustada pelo exemplo de código anterior.

Confira também

• Modelo de objeto JavaScript do Excel em Suplementos do Office
• Trabalhar com gráficos usando a API JavaScript do Excel