Devolver vários resultados da sua função personalizada

Pode devolver vários resultados da função personalizada que serão devolvidos às células vizinhas. Este comportamento chama-se transposição. Quando a função personalizada devolve uma matriz de resultados, é conhecida como uma fórmula de matriz dinâmica. Para obter mais informações sobre fórmulas de matriz dinâmica no Excel, veja Dynamic arrays and spilled array behavior (Matrizes dinâmicas e comportamento de matriz transposta).

A imagem seguinte mostra como a SORT função transpõe para as células vizinhas. A função personalizada também pode devolver vários resultados como este.

Para criar uma função personalizada que seja uma fórmula de matriz dinâmica, tem de devolver uma matriz bidimensional de valores. Se os resultados forem transbordos para células vizinhas que já têm valores, a fórmula apresentará um #SPILL! erro.

Exemplos de código

O primeiro exemplo mostra como devolver uma matriz dinâmica que é transposta para baixo.

/**
 * Get text values that spill down.
 * @customfunction
 * @returns {string[][]} A dynamic array with multiple results.
 */
function spillDown() {
  return [['first'], ['second'], ['third']];
}

O segundo exemplo mostra como devolver uma matriz dinâmica que transborda para a direita.

/**
 * Get text values that spill to the right.
 * @customfunction
 * @returns {string[][]} A dynamic array with multiple results.
 */
function spillRight() {
  return [['first', 'second', 'third']];
}

O terceiro exemplo mostra como devolver uma matriz dinâmica que transborda tanto para baixo como para a direita.

/**
 * 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']
  ];
}

O quarto exemplo mostra como devolver uma matriz de transposição dinâmica de uma função de transmissão em fluxo. Os resultados são transbordados, como o primeiro exemplo, e incrementam uma vez por segundo com base no amount parâmetro . Para saber mais sobre as funções de transmissão em fluxo, veja Criar uma função de transmissão em fluxo.

/**
 * 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);
  };
}

Confira também

• Matrizes dinâmicas e comportamento de matriz transposta
• Opções para funções personalizadas do Excel