Teilen über

Kernkonzepte für Excel-Datentypen

In diesem Artikel wird beschrieben, wie Sie die Excel-JavaScript-API für die Arbeit mit Datentypen verwenden. Es werden Kernkonzepte vorgestellt, die für die Entwicklung von Datentypen von grundlegender Bedeutung sind.

Die valuesAsJson-Eigenschaft

Die valuesAsJson -Eigenschaft (oder der Singular valueAsJson für NamedItem) ist integraler Bestandteil der Erstellung von Datentypen in Excel. Diese Eigenschaft ist eine Erweiterung der values-Eigenschaften, z. B. Range.values. Sowohl die values-Eigenschaft als auch die valuesAsJson-Eigenschaft werden verwendet, um auf den Wert in einer Zelle zuzugreifen, aber die values-Eigenschaft gibt nur einen der vier grundlegenden Typen zurück: Zeichenfolge, Zahl, boolescher Wert oder Fehler (als Zeichenfolge). Im Gegensatz dazu gibt valuesAsJson erweiterte Informationen zu den vier grundlegenden Typen zurück, und diese Eigenschaft kann Datentypen wie formatierte Zahlenwerte, Entitäten und Webbilder zurückgeben.

Die folgenden Objekte bieten die valuesAsJson-Eigenschaft.

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.

Zellwerte

Die valuesAsJson Eigenschaft gibt einen CellValue-Typalias zurück, bei dem es sich um eine Vereinigung der folgenden Datentypen handelt.

Der Typalias CellValue gibt auch das CellValueExtraProperties-Objekt zurück, das eine Schnittmenge mit dem Rest der *CellValue-Typen ist. Es ist selbst kein Datentyp. Die Eigenschaften des CellValueExtraProperties-Objekts werden mit allen Datentypen verwendet, um Details im Zusammenhang mit dem Überschreiben von Zellwerten anzugeben.

JSON-Schema

Jeder von valuesAsJson zurückgegebene Zellwerttyp verwendet ein JSON-Metadatenschema, das für diesen Typ entworfen wurde. Zusammen mit zusätzlichen Eigenschaften, die für jeden Datentyp eindeutig sind, haben alle diese JSON-Metadatenschemas die Eigenschaften type, basicType und basicValue gemeinsam.

Die type definiert die CellValueType der Daten. ist basicType immer schreibgeschützt und wird als Fallback verwendet, wenn der Datentyp nicht unterstützt oder falsch formatiert ist. Die basicValue entspricht dem Wert, der von der values-Eigenschaft zurückgegeben wird. Die basicValue wird als Fallback verwendet, wenn Berechnungen auf inkompatible Szenarien stoßen, z. B. eine ältere Version von Excel, die das Datentypfeature nicht unterstützt. Ist basicValue schreibgeschützt für ArrayCellValuedie Datentypen , EntityCellValue, LinkedEntityCellValueund WebImageCellValue .

Zusätzlich zu den drei Feldern, die von allen Datentypen gemeinsam verwendet werden, verfügt das JSON-Metadatenschema für jedes *CellValue über Eigenschaften, die entsprechend diesem Typ verfügbar sind. Beispielsweise enthält der WebImageCellValue-Typ die Eigenschaften altText und attribution, während der EntityCellValue-Typ die Felder properties und text anbietet.

In den folgenden Abschnitten werden JSON-Codebeispiele für den formatierten Zahlenwert, den Entitätswert, und die Webbilddatentypen gezeigt.

Formatierte Zahlenwerte

Mit dem DoubleCellValue-Objekt können Excel-Add-Ins eine numberFormat Eigenschaft für einen Wert definieren. Einmal zugewiesen, durchläuft dieses Zahlenformat Berechnungen mit dem Wert und kann von Funktionen zurückgegeben werden.

Das folgende JSON-Codebeispiel zeigt das vollständige Schema eines formatierten Zahlenwerts. Der formatierte Zahlenwert myDate im Codebeispiel wird in der Excel-Benutzeroberfläche als 16.01.1990 angezeigt. Wenn die Mindestkompatibilitätsanforderungen für das Datentypenfeature nicht erfüllt sind, verwenden Berechnungen den basicValue anstelle der formatierten Zahl.

// This is an example of the complete JSON of a formatted number value.
// In this case, the number is formatted as a date.
const myDate: Excel.DoubleCellValue = {
    type: Excel.CellValueType.double,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

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.

Beginnen Sie mit dem Experimentieren mit formatierten Zahlenwerten, indem Sie Script Lab öffnen und sich den Codeausschnitt Datentypen: Formatierte Zahlen in unserer Bibliothek Beispiele ansehen.

Basiszellenwerte

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 104,67 (ein Double), die eine Rechnung mit hinzugefügten Feldern namens Getränke, Lebensmittel, Steuern und Trinkgeld darstellt.

Screenshot der Felder für Getränke, Lebensmittel, Steuern und Trinkgeld, die für den ausgewählten Zellwert angezeigt werden

Weitere Informationen finden Sie unter Hinzufügen von Eigenschaften zu grundlegenden Zellwerten.

Entitätswerte

Ein Entitätswert ist ein Container für Datentypen, ähnlich wie ein Objekt in der objektorientierten Programmierung. Entitäten unterstützen Arrays auch als Eigenschaften eines Entitätswerts. Mit dem EntityCellValue-Objekt können Add-Ins Eigenschaften wie type, text und properties definieren. Die properties-Eigenschaft ermöglicht es dem Entitätswert, zusätzliche Datentypen zu definieren und zu enthalten.

Die basicType- und basicValue-Eigenschaften definieren, wie Berechnungen diesen Entitätsdatentyp lesen, wenn die Mindestkompatibilitätsanforderungen für die Verwendung von Datentypen nicht erfüllt sind. In diesem Szenario wird dieser Entitätsdatentyp auf der Excel-Benutzeroberfläche als #VALUE! -Fehler angezeigt.

Das folgende JSON-Codebeispiel zeigt das vollständige Schema eines Entitätswerts, der Text, ein Bild, ein Datum und einen zusätzlichen Textwert enthält.

// This is an example of the complete JSON for an entity value.
// The entity contains text and properties which contain an image, a date, and another text value.
const myEntity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: "A llama",
    properties: {
        image: myImage,
        "start date": myDate,
        "quote": {
            type: Excel.CellValueType.string,
            basicValue: "I love llamas."
        }
    }, 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Um Entitätsdatentypen zu untersuchen, wechseln Sie zunächst zu Script Lab in Excel, und öffnen Sie die Option Datentypen: Erstellen von Entitätskarten aus Daten in einem Tabellenausschnitt in unserer Beispielbibliothek. Die Codeausschnitte Datentypen: Entitätswerte mit Verweisen und Datentypen: Entitätswertzuordnungseigenschaften bieten einen tieferen Einblick in Entitätsfeatures.

Zellenwerte für verknüpfte Entitäten

Verknüpfte Entitätszellenwerte oder LinkedEntityCellValue-Objekte sind integrierte Datentypen aus externen Datenquellen und können die Daten als Entität Karte anzeigen. Sie ermöglichen es Ihnen, Ihre Datentypen so zu skalieren, dass sie große Datasets darstellen, ohne alle Daten in die Arbeitsmappe herunterzuladen. Die über die Excel-Benutzeroberfläche verfügbaren Datendomänen "Aktien" und "Geografie" stellen verknüpfte Entitätszellenwerte bereit.

Verknüpfte Entitätszellenwerte sind mit einer externen Datenquelle verknüpft. Sie bieten die folgenden Vorteile gegenüber regulären Entitätswerten:

  • Zellenwerte für verknüpfte Entitäten können geschachtelt werden, und geschachtelte Zellenwerte für verknüpfte Entitäten werden erst abgerufen, wenn vom Benutzer oder vom Arbeitsblatt referenziert wird. Dies trägt dazu bei, die Dateigröße zu reduzieren und die Arbeitsmappenleistung zu verbessern.
  • Excel verwendet einen Cache, damit verschiedene Zellen nahtlos auf denselben Wert der verknüpften Entitätszelle verweisen können. Dies verbessert auch die Leistung von Arbeitsmappen.

Weitere Informationen finden Sie unter Erstellen verknüpfter Entitätszellenwerte.

Webbildwerte

Das WebImageCellValue -Objekt erstellt die Möglichkeit, ein Bild als Teil einer Entität oder als unabhängigen Wert in einem Bereich zu speichern. Dieses Objekt bietet viele Eigenschaften, einschließlich address, altText, und relatedImagesAddress.

Die basicType- und basicValue-Eigenschaften definieren, wie Berechnungen den Webbilddatentyp lesen, wenn die Mindestkompatibilitätsanforderungen für die Verwendung des Datentypenfeatures nicht erfüllt sind. In diesem Szenario wird dieser Webbilddatentyp als #VALUE!- Fehler auf der Excel-Benutzeroberfläche angezeigt.

Das folgende JSON-Codebeispiel zeigt das vollständige Schema eines Webbilds.

// This is an example of the complete JSON for a web image.
const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw", 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Testen Sie Webbilddatentypen, indem Sie Script Lab öffnen und den Ausschnitt Datentypen: Webbilder in unserer Bibliothek Beispiele auswählen.

Verbesserte Fehlerunterstützung

Die Datentyp-APIs machen vorhandene Excel-Benutzeroberflächenfehler als Objekte verfügbar. Da auf diese Fehler als Objekte zugegriffen werden kann, können Add-Ins Eigenschaften wie type, errorType, und errorSubType abrufen.

Im Folgenden finden Sie eine Liste aller Fehlerobjekte mit erweiterter Unterstützung durch Datentypen.

Jedes der Fehlerobjekte kann über die errorSubType-Eigenschaft auf eine Enumeration zugreifen, und diese Enumeration enthält zusätzliche Daten zum Fehler. Beispielsweise kann das BlockedErrorCellValue-Fehlerobjekt auf die BlockedErrorCellValueSubType-Enumeration zugreifen. Die BlockedErrorCellValueSubType-Enumeration enthält zusätzliche Daten darüber, was den Fehler verursacht hat.

Weitere Informationen zu den Datentypfehlerobjekten finden Sie im Codeausschnitt Datentypen: Fehlerwerte festlegen in unserer Script LabSamples-Bibliothek.

Nächste Schritte

Erfahren Sie im Artikel Verwenden von Karten mit Entitätswert-Datentypen , wie Sie das Potenzial von Excel-Add-Ins über ein zweidimensionales Raster hinaus erweitern.

Verwenden Sie das Beispiel Erstellen und Untersuchen von Datentypen in Excel in unserem OfficeDev/Office-Add-in-samples-Repository , um tiefer mit Datentypen zu experimentieren, indem Sie ein Add-In erstellen und querladen, das Datentypen in einer Arbeitsmappe erstellt und bearbeitet.

Weitere Informationen

  • Last updated on