Options des paramètres des fonctions personnalisées

Article
07/05/2023

Les fonctions personnalisées sont configurables avec de nombreuses options de paramètres différentes.

Importante

Notez que les fonctions personnalisées Excel sont disponibles sur les plateformes suivantes.

Office sur le web
Office pour Windows
- Abonnement Microsoft 365
- retail perpetual Office 2016 et versions ultérieures
- Office 2021 perpétuel sous licence en volume et versions ultérieures
Office sur Mac

Les fonctions personnalisées Excel ne sont actuellement pas prises en charge dans les éléments suivants :

Office sur iPad
versions perpétuelles avec licence en volume d’Office 2019 ou version antérieure sur Windows

Paramètres facultatifs

Lorsqu’un utilisateur appelle une fonction dans Excel, les paramètres facultatifs apparaissent entre parenthèses. Dans l’exemple suivant, la fonction add peut éventuellement ajouter un troisième nombre. Cette fonction apparaît comme =CONTOSO.ADD(first, second, [third]) dans Excel.

JavaScript
TypeScript

/**
 * Calculates the sum of the specified numbers
 * @customfunction
 * @param {number} first First number.
 * @param {number} second Second number.
 * @param {number} [third] Third number to add. If omitted, third = 0.
 * @returns {number} The sum of the numbers.
 */
function add(first, second, third) {
  if (third === null) {
    third = 0;
  }
  return first + second + third;
}

/**
 * Calculates the sum of the specified numbers
 * @customfunction
 * @param first First number.
 * @param second Second number.
 * @param [third] Third number to add. If omitted, third = 0.
 * @returns The sum of the numbers.
 */
function add(first: number, second: number, third?: number): number {
  if (third === null) {
    third = 0;
  }
  return first + second + third;
}

Remarque

Lorsqu’aucune valeur n’est spécifiée pour un paramètre facultatif, Excel lui attribue la valeur null. Cela signifie que les paramètres initialisés par défaut dans TypeScript ne fonctionneront pas comme prévu. N’utilisez pas la syntaxe function add(first:number, second:number, third=0):number , car elle ne s’initialise third pas sur 0. Utilisez plutôt la syntaxe TypeScript comme indiqué dans l’exemple précédent.

Lorsque vous définissez une fonction qui contient un ou plusieurs paramètres facultatifs, spécifiez ce qui se passe lorsque les paramètres facultatifs sont null. Dans l’exemple suivant, zipCode et dayOfWeek sont deux paramètres facultatifs pour la fonctiongetWeatherReport. Si le zipCode paramètre est null, la valeur par défaut est définie sur 98052. Si le dayOfWeek paramètre est null, il est défini sur Mercredi.

JavaScript
TypeScript

/**
 * Gets a weather report for a specified zipCode and dayOfWeek
 * @customfunction
 * @param {number} [zipCode] Zip code. If omitted, zipCode = 98052.
 * @param {string} [dayOfWeek] Day of the week. If omitted, dayOfWeek = Wednesday.
 * @returns {string} Weather report for the day of the week in that zip code.
 */
function getWeatherReport(zipCode, dayOfWeek) {
  if (zipCode === null) {
    zipCode = 98052;
  }

  if (dayOfWeek === null) {
    dayOfWeek = "Wednesday";
  }

  // Get weather report for specified zipCode and dayOfWeek.
  // ...
}

/**
 * Gets a weather report for a specified zipCode and dayOfWeek
 * @customfunction
 * @param zipCode Zip code. If omitted, zipCode = 98052.
 * @param [dayOfWeek] Day of the week. If omitted, dayOfWeek = Wednesday.
 * @returns Weather report for the day of the week in that zip code.
 */
function getWeatherReport(zipCode?: number, dayOfWeek?: string): string {
  if (zipCode === null) {
    zipCode = 98052;
  }

  if (dayOfWeek === null) {
    dayOfWeek = "Wednesday";
  }

  // Get weather report for specified zipCode and dayOfWeek.
  // ...
}

Paramètres de plage

Votre fonction personnalisée peut accepter une plage de données de cellule comme paramètre d’entrée. Une fonction peut également retourner une plage de données. Excel transmet une plage de données de cellule sous forme de tableau à deux dimensions.

Par exemple, supposons que votre fonction renvoie la seconde valeur la plus élevée à partir d’une plage de nombres stockés dans Excel. La fonction suivante accepte le paramètre values, et la syntaxe number[][] JSDOC définit la propriété matrix du dimensionality paramètre sur dans les métadonnées JSON de cette fonction.

/**
 * Returns the second highest value in a matrixed range of values.
 * @customfunction
 * @param {number[][]} values Multiple ranges of values.
 */
function secondHighest(values) {
  let highest = values[0][0],
    secondHighest = values[0][0];
  for (let i = 0; i < values.length; i++) {
    for (let j = 0; j < values[i].length; j++) {
      if (values[i][j] >= highest) {
        secondHighest = highest;
        highest = values[i][j];
      } else if (values[i][j] >= secondHighest) {
        secondHighest = values[i][j];
      }
    }
  }
  return secondHighest;
}

Paramètres répétitifs

Un paramètre répétitif permet à un utilisateur d’entrer une série d’arguments facultatifs dans une fonction. Lorsque la fonction est appelée, les valeurs sont fournies dans un tableau pour le paramètre . Si le nom du paramètre se termine par un nombre, le nombre de chaque argument augmente de façon incrémentielle, par ADD(number1, [number2], [number3],…)exemple . Cela correspond à la convention utilisée pour les fonctions Excel intégrées.

La fonction suivante additionne le total des nombres, des adresses de cellule et des plages, si elle est entrée.

/**
* The sum of all of the numbers.
* @customfunction
* @param operands A number (such as 1 or 3.1415), a cell address (such as A1 or $E$11), or a range of cell addresses (such as B3:F12)
*/

function ADD(operands: number[][][]): number {
  let total: number = 0;

  operands.forEach(range => {
    range.forEach(row => {
      row.forEach(num => {
        total += num;
      });
    });
  });

  return total;
}

Cette fonction s’affiche =CONTOSO.ADD([operands], [operands]...) dans le classeur Excel.

La fonction personnalisée ADD entrée dans la cellule d’une feuille de calcul Excel

Paramètre de valeur unique répétitif

Un paramètre de valeur unique répétitif permet de passer plusieurs valeurs uniques. Par exemple, l’utilisateur peut entrer ADD(1,B2,3). L’exemple suivant montre comment déclarer un paramètre de valeur unique.

/**
 * @customfunction
 * @param {number[]} singleValue An array of numbers that are repeating parameters.
 */
function addSingleValue(singleValue) {
  let total = 0;
  singleValue.forEach(value => {
    total += value;
  })

  return total;
}

Paramètre de plage unique

Un paramètre de plage unique n’est pas techniquement un paramètre répétitif, mais il est inclus ici, car la déclaration est très similaire aux paramètres répétitifs. Il apparaît à l’utilisateur comme ADD(A2 :B3) où une plage unique est passée à partir d’Excel. L’exemple suivant montre comment déclarer un paramètre de plage unique.

/**
 * @customfunction
 * @param {number[][]} singleRange
 */
function addSingleRange(singleRange) {
  let total = 0;
  singleRange.forEach(setOfSingleValues => {
    setOfSingleValues.forEach(value => {
      total += value;
    })
  })
  return total;
}

Paramètre de plage répétitif

Un paramètre de plage répétée permet de passer plusieurs plages ou nombres. Par exemple, l’utilisateur peut entrer ADD(5,B2,C3,8,E5 :E8). Les plages répétées sont généralement spécifiées avec le type number[][][] , car il s’agit de matrices tridimensionnelles. Pour obtenir un exemple, consultez l’exemple main listé pour les paramètres répétitifs.

Déclaration des paramètres répétitifs

Dans Typescript, indiquez que le paramètre est multidimensionnel. Par exemple, ADD(values: number[]) indique un tableau unidimensionnel, ADD(values:number[][]) un tableau à deux dimensions, etc.

En JavaScript, utilisez @param values {number[]} pour les tableaux unidimensionnels, @param <name> {number[][]} pour les tableaux à deux dimensions, et ainsi de suite pour d’autres dimensions.

Pour le code JSON créé manuellement, vérifiez que votre paramètre est spécifié comme "repeating": true dans votre fichier JSON, ainsi que case activée que vos paramètres sont marqués comme "dimensionality": matrix.

Paramètre d’appel

Chaque fonction personnalisée est automatiquement passée un invocation argument en tant que dernier paramètre d’entrée, même s’il n’est pas explicitement déclaré. Ce invocation paramètre correspond à l’objet Invocation . L’objet Invocation peut être utilisé pour récupérer un contexte supplémentaire, tel que l’adresse de la cellule qui a appelé votre fonction personnalisée. Pour accéder à l’objet Invocation , vous devez déclarer invocation comme dernier paramètre dans votre fonction personnalisée.

Remarque

Le invocation paramètre n’apparaît pas en tant qu’argument de fonction personnalisé pour les utilisateurs dans Excel.

L’exemple suivant montre comment utiliser le invocation paramètre pour retourner l’adresse de la cellule qui a appelé votre fonction personnalisée. Cet exemple utilise la propriété address de l’objet Invocation . Pour accéder à l’objet Invocation , commencez par déclarer CustomFunctions.Invocation en tant que paramètre dans votre JSDoc. Ensuite, déclarez @requiresAddress dans votre JSDoc pour accéder à la address propriété de l’objet Invocation . Enfin, dans la fonction , récupérez, puis retournez la address propriété .

/**
 * Return the address of the cell that invoked the custom function. 
 * @customfunction
 * @param {number} first First parameter.
 * @param {number} second Second parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @requiresAddress 
 */
function getAddress(first, second, invocation) {
  const address = invocation.address;
  return address;
}

Dans Excel, une fonction personnalisée appelant la address propriété de l’objet Invocation retourne l’adresse absolue suivant le format SheetName!RelativeCellAddress dans la cellule qui a appelé la fonction. Par exemple, si le paramètre d’entrée se trouve sur une feuille appelée Prices dans la cellule F6, la valeur d’adresse du paramètre retournée est Prices!F6.

Remarque

Si un espace vide ou l’un des caractères suivants se trouve dans un nom de feuille de calcul : ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , . <>, le nom de la feuille de calcul dans l’adresse retournée est placé entre guillemets simples, le format est 'SheetName'!RelativeCellAddressdonc ; par exemple, 'Latest Prices'!F6. Si le guillemet simple (apostrophe) caractère, ', est dans le nom, l’adresse retournée comporte deux caractères de ce type dans une ligne ; par exemple, 'Bob''s Region'!F6.

Le invocation paramètre peut également être utilisé pour envoyer des informations à Excel. Pour en savoir plus , consultez Créer une fonction de diffusion en continu .

Détecter l’adresse d’un paramètre

En combinaison avec le paramètre d’appel, vous pouvez utiliser l’objet Invocation pour récupérer l’adresse d’un paramètre d’entrée de fonction personnalisée. Lorsqu’elle est appelée, la propriété parameterAddresses de l’objet Invocation permet à une fonction de retourner les adresses de tous les paramètres d’entrée.

Cela est utile dans les scénarios où les types de données d’entrée peuvent varier. L’adresse d’un paramètre d’entrée peut être utilisée pour case activée le format numérique de la valeur d’entrée. Le format des nombres peut ensuite être ajusté avant l’entrée, si nécessaire. L’adresse d’un paramètre d’entrée peut également être utilisée pour détecter si la valeur d’entrée a des propriétés associées qui peuvent être pertinentes pour les calculs suivants.

Remarque

Si vous utilisez des métadonnées JSON créées manuellement pour retourner des adresses de paramètre au lieu du générateur Yeoman pour les compléments Office, la options propriété de l’objet doit avoir la requiresParameterAddresses valeur trueet result la propriété de l’objet doit avoir la dimensionality valeur matrix.

La fonction personnalisée suivante accepte trois paramètres d’entrée, récupère la parameterAddresses propriété de l’objet Invocation pour chaque paramètre, puis retourne les adresses.

/**
 * Return the addresses of three parameters. 
 * @customfunction
 * @param {string} firstParameter First parameter.
 * @param {string} secondParameter Second parameter.
 * @param {string} thirdParameter Third parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @returns {string[][]} The addresses of the parameters, as a 2-dimensional array. 
 * @requiresParameterAddresses
 */
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
  const addresses = [
    [invocation.parameterAddresses[0]],
    [invocation.parameterAddresses[1]],
    [invocation.parameterAddresses[2]]
  ];
  return addresses;
}

Lorsqu’une fonction personnalisée appelant la parameterAddresses propriété s’exécute, l’adresse du paramètre est retournée en suivant le format SheetName!RelativeCellAddress dans la cellule qui a appelé la fonction. Par exemple, si le paramètre d’entrée se trouve sur une feuille appelée Coûts dans la cellule D8, la valeur d’adresse du paramètre retournée est Costs!D8. Si la fonction personnalisée a plusieurs paramètres et que plusieurs adresses de paramètre sont retournées, les adresses retournées se répandent sur plusieurs cellules, descendant verticalement de la cellule qui a appelé la fonction.

Remarque

Prochaines étapes

Découvrez comment utiliser des valeurs volatiles dans vos fonctions personnalisées.

Partager via

Options des paramètres des fonctions personnalisées

Paramètres facultatifs

Paramètres de plage

Paramètres répétitifs

Paramètre de valeur unique répétitif

Paramètre de plage unique

Paramètre de plage répétitif

Déclaration des paramètres répétitifs

Paramètre d’appel

Détecter l’adresse d’un paramètre

Prochaines étapes

Voir aussi

Ressources supplémentaires