Utiliser des types de données avec des fonctions personnalisées dans Excel
Les types de données développent l’API JavaScript Excel pour prendre en charge les types de données au-delà des quatre types de valeurs de cellule d’origine (chaîne, nombre, booléen et erreur). Les types de données incluent la prise en charge des images web, des valeurs numériques mises en forme, des entités et des tableaux au sein des entités.
Ces types de données amplifient la puissance des fonctions personnalisées, car les fonctions personnalisées acceptent les types de données comme valeurs d'entrée et de sortie. Vous pouvez générer des types de données via des fonctions personnalisées ou utiliser des types de données existants comme arguments de fonction dans les calculs. Une fois que le schéma JSON d’un type de données est définie, ce schéma est conservé tout au long des calculs.
Pour en savoir plus sur l’utilisation des types de données avec un complément Excel, consultez Vue d’ensemble des types de données dans des compléments Excel.
Comment les fonctions personnalisées gèrent les types de données
Les fonctions personnalisées peuvent reconnaître les types de données et les accepter comme valeurs de paramètre. Une fonction personnalisée peut créer un nouveau type de données pour une valeur de retour. Les fonctions personnalisées utilisent le même schéma JSON pour les types de données que l’API JavaScript Excel, et ce schéma JSON est conservé à mesure que les fonctions personnalisées calculent et évaluent.
Remarque
Les fonctions personnalisées ne prennent pas en charge toutes les fonctionnalités des objets d’erreur améliorés offerts par les types de données. Une fonction personnalisée peut accepter un objet d’erreur de types de données, mais elle ne sera pas conservée tout au long du calcul. Pour l’instant, les fonctions personnalisées ne peuvent que supporter les erreurs incluses dans l’objet CustomFunctions.Error.
Activer les types de données pour les fonctions personnalisées
Les projets de fonctions personnalisées incluent un fichier de métadonnées JSON. Ce fichier de métadonnées JSON diffère du schéma JSON utilisé par les API de types de données. Pour utiliser l’intégration des types de données avec des fonctions personnalisées, le fichier de métadonnées JSON des fonctions personnalisées doit être mis à jour manuellement pour inclure la propriété allowCustomDataForDataTypeAny. Définissez cette propriété sur true.
Pour obtenir une description complète du processus manuel de création de métadonnées JSON, consultez Créer manuellement des métadonnées JSON pour les fonctions personnalisées. Pour plus d’informations sur cette propriété, consultezallowCustomDataForDataTypeAny.
Sortie d’une valeur numérique formattée
L’exemple de code suivant montre comment créer un type de données FormattedNumberCellValue avec une fonction personnalisée. La fonction prend un nombre de base et un paramètre de format comme paramètres d’entrée et renvoie un type de données de valeur numérique formattée en tant que sortie.
/**
* 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
}
}
Saisie d’une valeur d’entité
L’exemple de code suivant montre une fonction personnalisée qui prend un type de données EntityCellValue comme entrée. Si le attribute paramètre est définie surtext,puis la fonction renvoie la textpropriété de la valeur d’entité. Sinon, la fonction renvoie la basicValue propriété de la valeur d’entité.
/**
* 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);
}
}
Étapes suivantes
Pour tester des fonctions et des types de données personnalisés, installez Script Lab dans Excel et essayez l’extrait de code Types de données : Fonctions personnalisées dans notre bibliothèque d’exemples.