Retourner plusieurs résultats à partir de votre fonction personnalisée
Vous pouvez retourner plusieurs résultats à partir de votre fonction personnalisée, qui seront retournés aux cellules voisines. Ce comportement est appelé débordement. Lorsque votre fonction personnalisée retourne un tableau de résultats, elle est appelée formule de tableau dynamique. Pour plus d’informations sur les formules de tableau dynamique dans Excel, consultez Tableaux dynamiques et comportement des tableaux renversés.
L’image suivante montre comment la SORT fonction se déverse dans les cellules voisines. Votre fonction personnalisée peut également retourner plusieurs résultats de ce type.
Pour créer une fonction personnalisée qui est une formule de tableau dynamique, elle doit retourner un tableau à deux dimensions de valeurs. Si les résultats se répandent dans les cellules voisines qui ont déjà des valeurs, la formule affiche une #SPILL! erreur.
Exemples de code
Le premier exemple montre comment retourner un tableau dynamique qui se déverse vers le bas.
/**
* Get text values that spill down.
* @customfunction
* @returns {string[][]} A dynamic array with multiple results.
*/
function spillDown() {
return [['first'], ['second'], ['third']];
}
Le deuxième exemple montre comment retourner un tableau dynamique qui déborde vers la droite.
/**
* Get text values that spill to the right.
* @customfunction
* @returns {string[][]} A dynamic array with multiple results.
*/
function spillRight() {
return [['first', 'second', 'third']];
}
Le troisième exemple montre comment retourner un tableau dynamique qui déborde à la fois vers le bas et vers la droite.
/**
* Get text values that spill both right and down.
* @customfunction
* @returns {string[][]} A dynamic array with multiple results.
*/
function spillRectangle() {
return [
['apples', 1, 'pounds'],
['oranges', 3, 'pounds'],
['pears', 5, 'crates']
];
}
Le quatrième exemple montre comment retourner un tableau de déversement dynamique à partir d’une fonction de diffusion en continu. Les résultats se déversent, comme dans le premier exemple, et s’incrémentent une fois par seconde en fonction du amount paramètre . Pour en savoir plus sur les fonctions de diffusion en continu, consultez Créer une fonction de diffusion en continu.
/**
* Increment the cells with a given amount every second. Creates a dynamic spilled array with multiple results
* @customfunction
* @param {number} amount The amount to add to the cell value on each increment.
* @param {CustomFunctions.StreamingInvocation<number[][]>} invocation Parameter to send results to Excel or respond to the user canceling the function. A dynamic array.
*/
function increment(amount: number, invocation: CustomFunctions.StreamingInvocation<number[][]>): void {
let firstResult = 0;
let secondResult = 1;
let thirdResult = 2;
const timer = setInterval(() => {
firstResult += amount;
secondResult += amount;
thirdResult += amount;
invocation.setResult([[firstResult], [secondResult], [thirdResult]]);
}, 1000);
invocation.onCanceled = () => {
clearInterval(timer);
};
}