Hinzufügen von Eigenschaften zu Excel-Basiszellenwerten

Verwenden Sie Eigenschaften für einen basislichen Zellwert, wenn Sie möchten, dass eine Zelle ihren ursprünglichen string, doubleoder Boolean -Wert beibehalten und auch zusätzliche Details verfügbar machen soll. Beispielsweise kann eine Restaurantrechnung eine Zahl für Berechnungen beibehalten, während auch , Drinks, Taxund Tip im Datentyp Karte und in Formeln angezeigt Foodwird.

In diesem Artikel wird gezeigt, wie Sie einen Basiswert mit Eigenschaften erstellen, einen vorhandenen Wert aktualisieren, Zahlenwerte formatieren und geschachtelte Datentypen hinzufügen.

• Beginnen Sie mit Übersicht über Datentypen in Excel-Add-Ins , wenn Sie noch nicht mit Excel-Datentypen vertraut sind.
• Überprüfen Sie das JSON-Schema unter Verwenden von Datentypen in Excel-Add-Ins.
• Verwenden Sie Verknüpfte Entitätsdatentypen erstellen in Excel-Add-Ins , wenn Ihre Daten aus einer externen Quelle stammen und unabhängig aktualisiert werden sollen.

Das folgende Beispiel zeigt die Zahl 14.67 mit hinzugefügten Feldern namens Drinks, Food, Taxund Tip.

Wenn Benutzer den Datentyp Karte öffnen, können sie die zusätzlichen Felder sehen.

Auf Grundwerte mit Eigenschaften kann auch in Formeln mit Punktnotation verwiesen werden.

Erstellen eines Zellwerts mit Eigenschaften

Verwenden Sie Range.valuesAsJson , um einen Wert zu erstellen und dessen Eigenschaften in einer Zuweisung zu definieren. Im folgenden Beispiel wird eine Zahl in A1 geschrieben und Rechnungsdetails als Eigenschaften hinzugefügt.

async function createNumberProperties() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          basicValue: 14.67,
          properties: {
            Food: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Sandwich and fries"
            },
            Drinks: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Soda"
            },
            Tax: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 5.5
            },
            Tip: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 21
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

Hinzufügen von Eigenschaften zu einem vorhandenen Wert

Verwenden Sie dieses Muster, wenn eine Zelle bereits einen Basiswert enthält und Sie sie anreichern möchten, ohne ihren zugrunde liegenden Typ zu ändern. Lesen Sie zunächst den Wert mithilfe valuesAsJsonvon . Überprüfen Sie dann, ob der Wert , stringoder Boolean ist, doublebevor Sie Eigenschaften hinzufügen.

Im folgenden Beispiel wird die Zahl in A1abgerufen, alle vorhandenen Eigenschaften beibehalten und eine Precision -Eigenschaft hinzugefügt.

async function addPropertyToNumber() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.load("valuesAsJson");
    await context.sync();

    const cellValue = range.valuesAsJson[0][0] as any;

    // Only apply this property to a double.
    if (cellValue.basicType === Excel.RangeValueType.double) {
      cellValue.properties = {
        ...(cellValue.properties ?? {}),
        Precision: {
          type: Excel.CellValueType.double,
          basicValue: 4
        }
      };

      range.valuesAsJson = [[cellValue]];
      await context.sync();
    }
  });
}

Auswählen eines Basiswerts oder eines Entitätswerts

Das Hinzufügen von Eigenschaften zu stringgrundlegenden Typen , Booleanund double ähnelt dem Hinzufügen von Eigenschaften zu Entitätswerten, aber das Verhalten unterscheidet sich in einigen wichtigen Punkten.

• Verwenden Sie einen Basiswert mit Eigenschaften, wenn Formeln die Zelle weiterhin als ihren zugrunde liegenden Wert behandeln sollen. Grundlegende Typen haben keine Fehlerfallbacks, sodass Berechnungen immer fortgesetzt werden können. Gibt beispielsweise immer noch zurück6, =SUM(A1:A3) wenn A1 ein Double mit Eigenschaften und A2 und Standardnummern A3 ist.
• Wenn eine Berechnung einen Basiswert verwendet, enthält das Ergebnis nur den zugrunde liegenden Wert. Das Ergebnis behält die Quelleigenschaften nicht bei.
• Wenn Sie kein Symbol für einen Basiswert angeben, wird in der Zelle kein Symbol angezeigt. Entitätswerte zeigen ein Standardsymbol an, wenn kein Symbol angegeben ist.

Formatierte Zahlenwerte

Mithilfe der -Eigenschaft können Sie Zahlenformatierung auf Werte des Typs CellValueType.doublenumberFormat anwenden. Im folgenden Beispiel wird ein Währungswert erstellt und eine beschreibende Eigenschaft hinzugefügt.

async function createCurrencyValue() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          basicValue: 24,
          numberFormat: "$0.00",
          properties: {
            Name: {
              type: Excel.CellValueType.string,
              basicValue: "Price"
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

Dieses Zahlenformat ist das Standardformat für den Wert. Wenn der Benutzer oder ein anderer Code ein anderes Format auf die Zelle anwendet, überschreibt dieses Format die des Werts numberFormat.

Anpassen des Karte-Layouts

Basiswerte mit Eigenschaften verwenden einen Standarddatentyp Karte. Um Eigenschaften auf hilfreichere Weise anzuzeigen, fügen Sie die layouts Eigenschaft der JSON-Beschreibung hinzu, und definieren Sie ein benutzerdefiniertes Karte Layout.

Layoutoptionen und Beispiele finden Sie unter Verwenden von Karten mit Zellwert-Datentypen.

Geschachtelte Datentypen

Sie können andere Datentypen in einem Basiswert schachteln, einschließlich Entitätswerten und zusätzlichen stringWerten, doubleund Boolean . Im folgenden Beispiel wird ein Computerakkuladewert in A1geschrieben. Anschließend wird eine geschachtelte Entität hinzugefügt, die den Computer und seine Energieeinstellungen beschreibt.

async function createNumberWithNestedEntity() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          layouts: {
            compact: {
              icon: "Battery10"
            }
          },
          basicValue: 0.7,
          numberFormat: "00%",
          properties: {
            Computer: {
              type: Excel.CellValueType.entity,
              text: "Laptop",
              properties: {
                "Power Consumption": {
                  type: Excel.CellValueType.double,
                  basicType: Excel.RangeValueType.double,
                  basicValue: 0.25,
                  numberFormat: "00%",
                  layouts: {
                    compact: {
                      icon: "Power"
                    }
                  },
                  properties: {
                    Plan: {
                      type: Excel.CellValueType.string,
                      basicType: Excel.RangeValueType.string,
                      basicValue: "Balanced"
                    }
                  }
                },
                Charging: {
                  type: Excel.CellValueType.boolean,
                  basicType: Excel.RangeValueType.boolean,
                  basicValue: true
                }
              }
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

Die folgende Abbildung zeigt den Wert und den Datentyp Karte für die geschachtelte Laptopentität.

Kompatibilität

In früheren Versionen von Excel, die das Datentypfeature nicht unterstützen, wird Benutzern die Warnung Nicht verfügbarer Datentyp angezeigt. Der Wert wird weiterhin in der Zelle angezeigt und funktioniert weiterhin mit Formeln und anderen Excel-Features. Wenn es sich bei dem Wert um eine formatierte Zahl handelt, wird bei Berechnungen anstelle basicValue der formatierten Zahl verwendet.

In Excel-Versionen, die älter als Office 2016 sind, wird der Wert in der Zelle ohne Fehler angezeigt und ist nicht von einem Basiswert zu unterscheiden.

Weitere Informationen

• Übersicht über Datentypen in Excel-Add-Ins
• Verwenden von Datentypen in Excel-Add-Ins
• Verwenden von Karten mit Zellwertdatentypen
• Erstellen von Datentypen für verknüpfte Entitäten in Excel-Add-Ins