Hinzufügen von Eigenschaften zu grundlegenden Zellwerten

Fügen Sie eigenschaften zu grundlegenden Zellwerten in Excel hinzu, um den Werten zusätzliche Informationen zuzuordnen. Ähnlich wie bei Entitätswerten können Sie eigenschaften zu den grundlegenden Typen string, double und boolean hinzufügen. Jede Eigenschaft ist ein Schlüssel-Wert-Paar. Das folgende Beispiel zeigt die Zahl 14,67 (ein Double), die eine Rechnung mit hinzugefügten Feldern namens Getränke, Essen, Steuern und Trinkgeld darstellt.

Wenn der Benutzer den Datentyp Karte anzeigen möchte, werden die Werte für die Felder angezeigt.

Zellenwerteigenschaften können auch in Formeln verwendet werden.

Erstellen eines Zellwerts mit Eigenschaften

Um einen Zellwert zu erstellen und ihm Eigenschaften hinzuzufügen, verwenden Sie Range.valuesAsJson , um Eigenschaften zuzuweisen. Im folgenden Codebeispiel wird gezeigt, wie Eine neue Zahl in Zelle A1 erstellt wird. Es fügt die Eigenschaften Essen, Getränke und zusätzliche Eigenschaften hinzu, die eine Rechnung in einem Restaurant beschreiben. Es weist eine JSON-Beschreibung der Eigenschaften zu valuesAsJson.

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

Hinweis

Einige Zellwerte ändern sich basierend auf dem Gebietsschema eines Benutzers. Die valuesAsJsonLocal-Eigenschaft bietet Lokalisierungsunterstützung und ist für alle Objekte verfügbar, wie auch valuesAsJson.

Hinzufügen von Eigenschaften zu einem vorhandenen Wert

Um einem vorhandenen Wert Eigenschaften hinzuzufügen, rufen Sie zuerst den Wert aus der Zelle mit valuesAsJsonab, und fügen Sie dann ein JSON-Objekt für Eigenschaften hinzu. Das folgende Beispiel zeigt, wie Sie den Zahlenwert aus Zelle A1 abrufen und ihr eine Eigenschaft mit dem Namen Precision zuweisen. Beachten Sie, dass Sie den Typ des Werts überprüfen sollten, um sicherzustellen, dass es sich um einen Zeichenfolgen-, Double- oder booleschen Basistyp handelt.

async function addPropertyToNumber() {
    await Excel.run(async (context) => {
        let sheet = context.workbook.worksheets.getActiveWorksheet();
        let range = sheet.getRange("A1");
        range.load("valuesAsJson");
        await context.sync();
        let cellValue = range.valuesAsJson[0][0] as any;

        // Only apply this property to a double.
        if (cellValue.basicType === "Double") {
            cellValue.properties = {
                Precision: {
                    type: Excel.CellValueType.double,
                    basicValue: 4
                }
            };
            range.valuesAsJson = [[cellValue]];
            await context.sync();
        }
    });
}

Unterschiede zu Entitätswerten

Das Hinzufügen von Eigenschaften zu grundlegenden Typen vom Typ string, Boolean und double ähnelt dem Hinzufügen von Eigenschaften zu Entitätswerten. Es gibt jedoch Unterschiede.

• Basistypen weisen einen Fallback ohne Fehler auf, sodass Berechnungen mit ihnen ausgeführt werden können. Betrachten Sie beispielsweise die Formel =SUMME(A1:A3), wobei A11, A22 und A33 ist. A1 ist ein Double mit Eigenschaften, während A2 und A3 keine Eigenschaften haben. Die Summe gibt das richtige Ergebnis von 6 zurück. Die Formel würde nicht funktionieren, wenn A1 ein Entitätswert wäre.
• Wenn der Wert eines Basistyps in einer Berechnung verwendet wird, werden die Eigenschaften im Ergebnis ausgeschlossen. Im vorherigen Beispiel von =SUMME(A1:A3), bei dem A1 ein Double mit Eigenschaften ist, hat das Ergebnis von 6 keine Eigenschaften.
• Wenn für einen Basistyp kein Symbol angegeben ist, wird in der Zelle kein Symbol angezeigt. Wenn ein Entitätswert jedoch kein Symbol angibt, wird im Zellwert ein Standardsymbol angezeigt.

Formatierte Zahlenwerte

Sie können Zahlenformatierung auf Werte vom Typ CellValueType.doubleanwenden. Verwenden Sie die numberFormat -Eigenschaft im JSON-Schema, um ein Zahlenformat anzugeben. Das folgende Codebeispiel zeigt das vollständige Schema eines Zahlenwerts, der als Währung formatiert ist. Der formatierte Zahlenwert im Codebeispiel wird auf der Excel-Benutzeroberfläche als $24,00 angezeigt.

// This is an example of the complete JSON of a formatted number value with a property.
// In this case, the number is formatted as currency.
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: "dollar"
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

Die Zahlenformatierung gilt als Standardformat. Wenn der Benutzer oder ein anderer Code eine Formatierung auf eine Zelle anwendet, die eine formatierte Zahl enthält, setzt das angewendete Format das Format der Zahl außer Kraft.

Kartenlayout

Zellwerte mit Eigenschaften weisen einen Standarddatentyp Karte auf, den der Benutzer anzeigen kann. Sie können ein benutzerdefiniertes Karte-Layout bereitstellen, das anstelle des Standardlayouts Karte verwendet werden soll, um die Benutzererfahrung beim Anzeigen von Eigenschaften zu verbessern. Fügen Sie dazu der JSON-Beschreibung die Layouts-Eigenschaft hinzu.

Weitere Informationen finden Sie unter Verwenden von Karten mit Zellwert-Datentypen.

Geschachtelte Datentypen

Sie können Datentypen in einem Zellwert schachteln, z. B. zusätzliche Entitätswerte, sowie Zeichenfolgen, Doubles und Boolesche Werte. Im folgenden Codebeispiel wird gezeigt, wie Sie einen Zellwert erstellen, der die Ladung status eines Computerakkus darstellt. Er enthält einen geschachtelten Entitätswert, der die Computereigenschaften für den Stromverbrauch und das Laden status beschreibt. Der Wert der Computerentität enthält auch einen geschachtelten Zeichenfolgenwert, der den Energiesparplan des Computers 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 Zahlenwert 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 wie erwartet 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.

Siehe auch

• Kernkonzepte der Excel-JavaScript-API-Datentypen