Verwenden von Datentypen in Excel-Add-Ins

Wenn Ihr Add-In mehr als Zeichenfolgen, Zahlen und boolesche Werte benötigt, verwenden Sie Excel-Datentypen. Mit Datentypen können Sie erweiterte Werte zurückgeben, z. B. formatierte Datumsangaben, Entitätskarten, verknüpfte Datensätze und Webbilder, während Sie weiterhin Arbeitsblattberechnungen unterstützen.

In diesem Artikel wird die valuesAsJson API erläutert, die Datentypen unterstützt, und zeigt, wann die Wichtigsten Zellwerttypen verwendet werden sollen. Eine Funktionsübersicht finden Sie unter Übersicht über Datentypen in Excel-Add-Ins.

Um diese Konzepte sofort auszuprobieren, öffnen Sie Script Lab in Excel, und durchsuchen Sie die Datentypbeispiele in der Bibliothek Beispiele.

Die valuesAsJson-Eigenschaft

Die valuesAsJson -Eigenschaft ist die Haupt-API zum Lesen und Schreiben von Excel-Datentypen. Die singular-Eigenschaft valueAsJson für NamedItem dient demselben Zweck für ein einzelnes benanntes Element.

valuesAsJson erweitert eigenschaften wie Range.values. Die values -Eigenschaft gibt nur einen der vier grundlegenden Zellwerttypen zurück: Zeichenfolge, Zahl, boolescher Wert oder Fehler. Im Gegensatz dazu valuesAsJson gibt eine erweiterte JSON-Struktur für diese grundlegenden Typen und für Datentypen wie formatierte Zahlen, Entitäten und Webbilder zurück.

Die folgenden Objekte machen verfügbar valuesAsJson.

Hinweis

Einige Zellwerte ändern sich basierend auf dem Gebietsschema eines Benutzers. Verwenden Sie valuesAsJsonLocal , wenn Sie lokalisierte Werte benötigen. Sie ist für die gleichen Objekte wie valuesAsJsonverfügbar.

Zellwerte

valuesAsJson gibt den CellValue-Typalias zurück. CellValue ist eine Vereinigung mehrerer Zellwerttypen.

Die meisten Add-Ins verwenden folgende Typen:

Die vollständige CellValue Union umfasst die folgenden Typen.

CellValue ist eine Schnittmenge mit CellValueExtraProperties. CellValueExtraProperties ist selbst kein Datentyp. Es fügt Eigenschaften hinzu, mit denen Sie steuern können, wie Zellwerte überschrieben werden.

JSON-Schema

Jeder Wert, der zurückgibt, valuesAsJson verwendet ein JSON-Metadatenschema, das für diesen Zellwerttyp entwickelt wurde. Obwohl jeder Typ über eigene Eigenschaften verfügt, teilen typesich alle Schemas , basicTypeund basicValue.

type definiert cellValueType. basicType ist schreibgeschützt und stellt den Fallbacktyp bereit, wenn der Datentyp nicht unterstützt oder falsch formatiert ist. basicValue entspricht dem von der values -Eigenschaft zurückgegebenen Wert und fungiert als Fallback, wenn Bei Berechnungen inkompatible Szenarien auftreten, z. B. eine ältere Version von Excel, die keine Datentypen unterstützt. basicValue ist schreibgeschützt für ArrayCellValue, EntityCellValue, LinkedEntityCellValueund WebImageCellValue.

Über diese freigegebenen Felder hinaus verfügt jeder *CellValue Typ über ein eigenes Schema. WebImageCellValue enthält altText beispielsweise und attribution, während EntityCellValue und enthältproperties.text

Die nächsten Abschnitte zeigen allgemeine Muster für formatierte Zahlen, Basiswerte mit zusätzlichen Eigenschaften, Entitätswerte, verknüpfte Entitäten, Webbilder und erweiterte Fehler.

Formatierte Zahlenwerte

Verwenden Sie DoubleCellValue , wenn der zugrunde liegende numerische Wert wichtig ist, aber Sie möchten auch, dass Excel ein bestimmtes Anzeigeformat mit diesem Wert behält. Ein häufiges Szenario ist die Rückgabe eines seriellen Datumswerts und das Anzeigen als Datum im Arbeitsblatt.

Das folgende Beispiel zeigt das vollständige JSON-Schema für eine formatierte Zahl. In diesem Beispiel myDate wird auf der Excel-Benutzeroberfläche als 16.01.1990 angezeigt. Wenn die Mindestkompatibilitätsanforderungen für Datentypen nicht erfüllt sind, verwenden basicValueBerechnungen .

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

Das Zahlenformat in einem DoubleCellValue ist das Standardformat. Wenn ein Benutzer oder ein anderer Teil des Add-Ins später Formatierungen auf die Zelle anwendet, setzt dieses angewendete Format das Format des Werts außer Kraft.

Um mit formatierten Zahlenwerten zu experimentieren, öffnen Sie Script Lab, und führen Sie das Beispiel Datentypen: Formatierte Zahlen aus.

Basiszellenwerte

Sie können Eigenschaften zu Excel-Basiswerten hinzufügen, um ihnen zusätzliche Informationen zuzuordnen. Dieses Muster funktioniert mit den grundlegenden Typen string, double und boolean . Verwenden Sie sie, wenn ein einfacher Zellwert verwandte Felder tragen soll, ohne den Wert in eine vollständige Entität zu verwandeln.

Beispielsweise kann eine Rechnungssumme verwandte Felder wie Getränke, Lebensmittel, Steuern und Trinkgeld enthalten.

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

Die vollständige exemplarische Vorgehensweise finden Sie unter Hinzufügen von Eigenschaften zu Excel-Basiszellenwerten.

Entitätswerte

Ein EntityCellValue kann Text, geschachtelte Datentypen und Arrays speichern, und Excel kann diese Daten in einer Entität Karte anzeigen.

Das folgende Beispiel zeigt das vollständige JSON-Schema für einen Entitätswert, der eine Rechnung darstellt. Die Entität enthält Anzeigetext plus Eigenschaften für ein Bild, ein Fälligkeitsdatum und einen status Wert.

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

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

Wichtig

Ein Entitätswert kann ein referencedValues Array definieren, das zusätzliche Zellwerte speichert. Auf diese Werte wird vom Index innerhalb der Entität propertiesverwiesen.

  • Das referencedValues Array wird nur für die Entität auf Stammebene in einer Zellwertstruktur unterstützt.
  • Geschachtelte Entitäten, bei denen es sich um Entitäten handelt, die als Eigenschaftswerte innerhalb einer anderen Entität verwendet werden, dürfen keine eigenen referencedValuesdefinieren.
  • Wenn eine geschachtelte Entität ein referencedValues Array enthält, löst die JavaScript-Excel-API einen GeneralException Fehler im Add-In- oder Skriptcode aus, oder Excel zeigt einen #VALUE! -Fehler an, wenn eine benutzerdefinierte Funktion den Wert erzeugt.

Um auf Werte aus einer geschachtelten Entität zu verweisen, verwenden Sie ReferenceCellValue-Indizes , die auf das Array der Stammentität referencedValues verweisen.

Öffnen Sie zum Untersuchen von Entitätsdatentypen Script Lab, und führen Sie Datentypen: Erstellen von Entitätskarten aus Daten in einer Tabelle aus. Ausführlichere Beispiele finden Sie unter Datentypen: Entitätswerte mit Verweisen und Datentypen: Entitätswertzuordnungseigenschaften.

Zellenwerte für verknüpfte Entitäten

LinkedEntityCellValue stellt eine Entität dar, die mit einer externen Datenquelle verbunden ist. Verwenden Sie verknüpfte Entitäten, wenn Sie Karten für große oder häufig aktualisierte Datasets benötigen und nicht alle Details gleichzeitig in die Arbeitsmappe laden möchten.

Die auf der Excel-Benutzeroberfläche verfügbaren Datendomänen "Aktien" und "Geografie" sind Beispiele für Verknüpfte Entitätszellenwerte.

Zellenwerte für verknüpfte Entitäten bieten die folgenden Vorteile gegenüber regulären Entitätswerten.

  • Verknüpfte Entitätszellenwerte können geschachtelt werden, und Excel ruft erst dann geschachtelte verknüpfte Entitäten ab, wenn der Benutzer oder das Arbeitsblatt darauf verweist. Dieses Verhalten trägt dazu bei, die Dateigröße zu reduzieren und die Arbeitsmappenleistung zu verbessern.
  • Excel verwendet einen Cache, damit verschiedene Zellen auf denselben Wert der verknüpften Entitätszelle verweisen können. Dies trägt auch zur Leistung von Arbeitsmappen bei.

Details zur Implementierung finden Sie unter Erstellen von Datentypen verknüpfter Entitäten in Excel-Add-Ins.

Webbildwerte

Verwenden Sie WebImageCellValue , wenn Ihr Add-In ein Bild in einem Bereich oder als Teil eines Entitätswerts speichern muss. Dieser Typ umfasst Eigenschaften wie address, altTextund relatedImagesAddress.

Die basicType Eigenschaften und basicValue definieren, wie Berechnungen ein Webbild lesen, wenn die Mindestkompatibilitätsanforderungen für Datentypen nicht erfüllt sind. In diesem Fall wird das Webbild als #VALUE!- Fehler auf der Excel-Benutzeroberfläche angezeigt.

Das folgende Beispiel zeigt das vollständige JSON-Schema für ein Webbild.

const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw",
    basicType: Excel.RangeValueType.error,
    basicValue: "#VALUE!"
};

Öffnen Sie zum Testen von Webimagedatentypen Script Lab, und führen Sie Datentypen aus: Webimages.

Verbesserte Fehlerunterstützung

Datentyp-APIs machen vorhandene Excel-UI-Fehler als Objekte verfügbar. Mit diesem Ansatz können Sie Eigenschaften wie type, errorTypeund errorSubTypedefinieren oder abrufen.

Die folgenden Fehlerobjekte verfügen über eine erweiterte Unterstützung durch Datentypen.

Jedes Fehlerobjekt kann über errorSubTypeauf eine Enumeration zugreifen. Diese Enumeration enthält weitere Details zum spezifischen Fehler. BlockedErrorCellValueSubType stellt beispielsweise zusätzliche Informationen darüber bereit, warum ein BlockedErrorCellValue aufgetreten ist.

Um mehr zu erfahren, öffnen Sie Script Lab, und führen Sie Datentypen: Fehlerwerte festlegen aus.

Nächste Schritte

Weitere Informationen

  • Last updated on