Verwenden von Datentypen mit benutzerdefinierten Funktionen in Excel

  • Artikel

Datentypen erweitern die Excel-JavaScript-API, um Datentypen zu unterstützen, die über die ursprünglichen vier Zellwerttypen (Zeichenfolge, Zahl, boolescher Wert und Fehler) hinausgehen. Datentypen umfassen Unterstützung für Webbilder, formatierte Zahlenwerte, Entitäten und Arrays innerhalb von Entitäten.

Diese Datentypen verstärken die Leistungsfähigkeit benutzerdefinierter Funktionen, da benutzerdefinierte Funktionen Datentypen sowohl als Eingabe- als auch als Ausgabewerte akzeptieren. Sie können Datentypen über benutzerdefinierte Funktionen generieren oder vorhandene Datentypen als Funktionsargumente in Berechnungen übernehmen. Sobald das JSON-Schema eines Datentyps festgelegt ist, wird dieses Schema während den Berechnungen beibehalten.

Weitere Informationen zur Verwendung von Datentypen mit einem Excel-Add-In finden Sie unter Überblick der Datentypen in Excel-Add-Ins.

Behandeln von Datentypen durch benutzerdefinierte Funktionen

Benutzerdefinierte Funktionen können Datentypen erkennen und sie als Parameterwerte akzeptieren. Eine benutzerdefinierte Funktion kann einen neuen Datentyp für einen Rückgabewert erstellen. Benutzerdefinierte Funktionen verwenden das gleiche JSON-Schema für Datentypen wie die Excel-JavaScript-API, und dieses JSON-Schema wird beibehalten, während benutzerdefinierte Funktionen berechnen und auswerten.

Hinweis

Benutzerdefinierte Funktionen unterstützen nicht die vollständige Funktionalität der erweiterten Fehlerobjekte, die von Datentypen angeboten werden. Eine benutzerdefinierte Funktion kann ein Fehlerobjekt für Datentypen akzeptieren, aber es wird nicht während der gesamten Berechnung beibehalten. Derzeit unterstützen benutzerdefinierte Funktionen nur die Fehler, die im CustomFunctions.Error-Objekt beinhaltet sind.

Aktivieren von Datentypen für benutzerdefinierte Funktionen

Projekte für benutzerdefinierte Funktionen enthalten eine JSON-Metadatendatei. Diese JSON-Metadatendatei unterscheidet sich vom JSON-Schema, das von Datentypen-APIs verwendet wird. Um die Integration von Datentypen mit benutzerdefinierten Funktionen zu verwenden, muss die JSON-Metadatendatei für benutzerdefinierte Funktionen manuell aktualisiert werden, um die Eigenschaft allowCustomDataForDataTypeAny einzuschließen. Legen Sie diese Eigenschaft auf true fest.

Eine vollständige Beschreibung des manuellen Json-Metadatenerstellungsprozesses finden Sie unter Manuelles Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen. Weitere Informationen zu dieser Eigenschaft finden Sie unter allowCustomDataForDataTypeAny.

Ausgeben eines formatierten Zahlenwerts

Das folgende Codebeispiel zeigt, wie Sie einen FormattedNumberCellValue-Datentyp mit einer benutzerdefinierten Funktion erstellen. Die Funktion verwendet eine einfache Zahl und eine Formateinstellung als die Eingabeparameter und gibt einen formatierten Zahlenwertdatentyp als Ausgabe zurück.

/**
 * Take a number as the input value and return a formatted number value as the output.
 * @customfunction
 * @param {number} value
 * @param {string} format (e.g. "0.00%")
 * @returns A formatted number value.
 */
function createFormattedNumber(value, format) {
    return {
        type: "FormattedNumber",
        basicValue: value,
        numberFormat: format
    }
}

Eingeben eines Entitätswerts

Das folgende Codebeispiel zeigt eine benutzerdefinierte Funktion, die einen EntityCellValue-Datentyp als Eingabe akzeptiert. Wenn der attribute-Parameter auf text festgelegt ist, dann gibt die Funktion die text-Eigenschaft des Entitätswerts zurück. Andernfalls gibt die Funktion die basicValue-Eigenschaft des Entitätswerts zurück.

/**
 * Accept an entity value data type as a function input.
 * @customfunction
 * @param {any} value
 * @param {string} attribute
 * @returns {any} The text value of the entity.
 */
function getEntityAttribute(value, attribute) {
    if (value.type == "Entity") {
        if (attribute == "text") {
            return value.text;
        } else {
            return value.properties[attribute].basicValue;
        }
    } else {
        return JSON.stringify(value);
    }
}

Nächste Schritte

Um mit benutzerdefinierten Funktionen und Datentypen zu experimentieren, installieren Sie Script Lab in Excel, und probieren Sie den Codeausschnitt Datentypen: Benutzerdefinierte Funktionen in unserer Beispielbibliothek aus.

Weitere Informationen