Kernkonzepte für Excel-Datentypen

  • Artikel

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 FormattedNumberCellValue-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.FormattedNumberCellValue = {
    type: Excel.CellValueType.formattedNumber,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

Beginnen Sie mit dem Experimentieren mit formatierten Zahlenwerten, indem Sie die Skriptumgebung öffnen und den Codeausschnitt Datentypen: Formatierte Zahlen in unserer Bibliothek Beispiele anzeigen.

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

Entitätswerte bieten auch eine layouts-Eigenschaft, die eine Karte für die Entität erstellt. Die Karte wird in der Excel-Benutzeroberfläche als modales Fenster angezeigt und kann zusätzliche Informationen anzeigen, die im Entitätswert enthalten sind, über das hinaus, was in der Zelle sichtbar ist. Weitere Informationen finden Sie unter Verwenden von Karten mit Entitätswertdatentypen.

Um Entitätsdatentypen zu untersuchen, wechseln Sie zunächst zu Skript-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.

Verknüpfte Entitäten

Verknüpfte Entitätswerte oder LinkedEntityCellValue-Objekte sind ein Entitätswerttyp. Diese Objekte integrieren Daten, die von einem externen Dienst bereitgestellt werden, und können diese Daten wie normale Entitätswerte als Entitätskarte anzeigen. Die über die Excel-Benutzeroberfläche verfügbaren Datentypen „Aktien“ und „Geographie“ sind verknüpfte Entitätswerte.

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 skriptbasiertes 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 Bibliothek Skriptlabbeispiele.

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