Devolver varios resultados de la función personalizada
Puede devolver varios resultados de la función personalizada que se devolverán a las celdas vecinas. Este comportamiento se denomina desbordamiento. Cuando la función personalizada devuelve una matriz de resultados, se conoce como fórmula de matriz dinámica. Para obtener más información sobre las fórmulas de matriz dinámica en Excel, vea Matrices dinámicas y comportamiento de matriz derramada.
En la imagen siguiente se muestra cómo la SORT función se derrama en celdas vecinas. La función personalizada también puede devolver varios resultados como este.
Para crear una función personalizada que sea una fórmula de matriz dinámica, debe devolver una matriz bidimensional de valores. Si los resultados se derraman en celdas vecinas que ya tienen valores, la fórmula mostrará un #SPILL! error.
Ejemplos de código
En el primer ejemplo se muestra cómo devolver una matriz dinámica que se derrama hacia abajo.
/**
* Get text values that spill down.
* @customfunction
* @returns {string[][]} A dynamic array with multiple results.
*/
function spillDown() {
return [['first'], ['second'], ['third']];
}
En el segundo ejemplo se muestra cómo devolver una matriz dinámica que se desborda correctamente.
/**
* Get text values that spill to the right.
* @customfunction
* @returns {string[][]} A dynamic array with multiple results.
*/
function spillRight() {
return [['first', 'second', 'third']];
}
En el tercer ejemplo se muestra cómo devolver una matriz dinámica que se derrama hacia abajo y hacia la derecha.
/**
* 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']
];
}
En el cuarto ejemplo se muestra cómo devolver una matriz de desbordamiento dinámico de una función de streaming. Los resultados se derraman, como en el primer ejemplo, y se incrementan una vez por segundo en función del amount parámetro . Para más información sobre las funciones de streaming, consulte Creación de una función de streaming.
/**
* 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);
};
}