Retornar vários resultados da função personalizada

Sua função personalizada pode retornar vários resultados que preenchem células vizinhas. Esse comportamento é chamado de "despejo". Quando uma função personalizada retorna uma matriz de resultados, ela é conhecida como uma fórmula de matriz dinâmica. Isso permite que as funções personalizadas funcionem como as funções de matriz dinâmica internas do Excel, como SORT, FILTERe UNIQUE. Para obter mais informações sobre fórmulas de matriz dinâmica no Excel, consulte Comportamento de matrizes dinâmicas e matriz despejada.

A imagem a seguir mostra como a SORT função se espalha para células vizinhas. Sua função personalizada também pode retornar vários resultados como este.

Captura de tela da função 'SORT' exibindo vários resultados em várias células.

Principais pontos

  • Retorne uma matriz bidimensional para criar uma função personalizada que despeje resultados.
  • Os resultados são despejados automaticamente nas células vizinhas.
  • Se células vizinhas contiverem dados, a fórmula exibirá um #SPILL! erro.
  • As matrizes são despejadas adicionando linhas, à direita adicionando colunas ou ambas para intervalos retangulares.
  • As matrizes dinâmicas funcionam com funções de streaming que atualizam os resultados ao longo do tempo.

Exemplos de código

Para criar uma função personalizada que retorna matrizes dinâmicas, retorne uma matriz bidimensional de valores. A estrutura da matriz determina a direção do despejo: linhas criam despejos verticais, colunas criam despejos horizontais e ambas criam intervalos retangulares.

Despejar para baixo

O exemplo a seguir retorna uma matriz dinâmica que é despejada. Cada matriz interna representa uma linha.

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

Despejar para a direita

O exemplo a seguir retorna uma matriz dinâmica que despeja à direita. A única matriz interna contém vários valores.

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

Despejar em ambas as direções

O exemplo a seguir retorna uma matriz dinâmica que despeja para baixo e para a direita, criando um intervalo retangular.

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

Matrizes dinâmicas de streaming

Combine matrizes dinâmicas com funções de streaming para criar resultados que são atualizados ao longo do tempo. O exemplo a seguir retorna valores que são despejados amount e incrementados uma vez por segundo com base no parâmetro. Para saber mais sobre as funções de streaming, consulte Criar uma função 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);
  };
}

Processar dados com matrizes dinâmicas

As matrizes dinâmicas são úteis para processar e transformar dados de entrada. O exemplo a seguir usa uma matriz de números e retorna os valores e seus quadrados.

/**
 * Calculate squares of input numbers.
 * @customfunction
 * @param {number[]} numbers Array of numbers to process.
 * @returns {any[][]} A dynamic array showing numbers and their squares.
 */
function calculateSquares(numbers) {
  // Create header row.
  const result = [['Number', 'Square']];

  // Process each number.
  numbers.forEach(row => {
    const num = Array.isArray(row) ? row[0] : row;
    result.push([num, num * num]);
  });

  return result;
}

Confira também

  • Last updated on