Arbeiten mit Datenbeschriftungen in Diagrammen mithilfe der Excel-JavaScript-API

Fügen Sie Excel-Diagrammen Datenbeschriftungen hinzu, um eine bessere Visualisierung wichtiger Aspekte des Diagramms zu ermöglichen. Weitere Informationen zu Datenbeschriftungen finden Sie unter Hinzufügen oder Entfernen von Datenbeschriftungen in einem Diagramm.

Im folgenden Codebeispiel werden die In diesem Artikel verwendeten Beispieldaten und das Fahrradteilproduktionsdiagramm eingerichtet.

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

Diese Abbildung zeigt, wie das Diagramm nach dem Ausführen des Beispielcodes angezeigt werden soll.

Hinzufügen von Datenbeschriftungen

Um einem Diagramm Datenbeschriftungen hinzuzufügen, rufen Sie die Reihe von Datenpunkten ab, die Sie ändern möchten, und legen Sie die hasDataLabels -Eigenschaft auf fest 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();
  });
}

Formatieren von Datenbezeichnungsgröße, -form und -text

Sie können Attribute für Datenbeschriftungen mithilfe der folgenden APIs ändern.

• Ändern Sie Datenbeschriftungs-Shapes, indem Sie die eigenschaft geometricShapeType festlegen.
• Ändern Sie die Höhe und Breite mithilfe der Methoden setWidth und setHeight .
• Ändern Sie den Text mithilfe der text-Eigenschaft .
• Ändern Sie die Textformatierung mithilfe der format-Eigenschaft . Sie können die Eigenschaften rahmen, Füllung und Schriftart ändern.

Im folgenden Codebeispiel wird gezeigt, wie Sie den Formtyp, die Höhe und Breite sowie die Schriftartformatierung für die Datenbeschriftungen festlegen.

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

Im folgenden Screenshot enthält das Diagramm jetzt Count Data Labels für die Spokes-Daten mit benutzerdefiniertem Text am dritten Datenpunkt.

Sie können auch die Formatierung von Text in einer Datenbezeichnung ändern. Im folgenden Codebeispiel wird gezeigt, wie sie die getSubstring-Methode verwenden, um einen Teil des Datenbeschriftungstexts abzurufen und Schriftartformatierungen anzuwenden.

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

Formatieren von Führungslinien

Führungslinien verbinden Datenbeschriftungen mit ihren jeweiligen Datenpunkten und machen es einfacher, zu erkennen, worauf sie sich im Diagramm beziehen. Aktivieren Sie Führungslinien mithilfe der showLeaderLines-Eigenschaft . Sie können das Format von Führungslinien mit der leaderLines.format-Eigenschaft festlegen.

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

Erstellen von Legenden

Eine Legende ist eine Datenbeschriftung, die mithilfe eines blasenförmigen Zeigers eine Verbindung mit dem Datenpunkt herstellt. Eine Legende verfügt über einen Anker, der vom Datenpunkt an andere Stellen im Diagramm verschoben werden kann.

Im folgenden Codebeispiel wird gezeigt, wie Sie Datenbeschriftungen in einer Reihe ändern, um Excel.GeometricShapeType.wedgeRectCallout zu verwenden. Beachten Sie, dass Führungslinien deaktiviert sind, um zu vermeiden, dass zwei Indikatoren für dieselbe Datenbezeichnung angezeigt werden.

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

Im folgenden Codebeispiel wird gezeigt, wie Sie die Ankerposition einer Datenbeschriftung ändern.

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

Dieser Screenshot zeigt, wie der Anker der dritten Datenbeschriftung durch das vorangehende Codebeispiel angepasst wird.

Siehe auch

• JavaScript-Objektmodell für Excel in Office-Add-Ins
• Arbeiten mit Diagrammen mithilfe der Excel-JavaScript-API