Поделиться через

Возврат нескольких результатов из пользовательской функции

  • Статья

Вы можете вернуть несколько результатов из пользовательской функции, которые будут возвращены в соседние ячейки. Такое поведение называется разливанием. Когда пользовательская функция возвращает массив результатов, она называется формулой динамического массива. Дополнительные сведения о формулах динамических массивов в Excel см. в разделе Динамические массивы и поведение разлитых массивов.

На следующем рисунке SORT показано, как функция перетекает в соседние ячейки. Пользовательская функция также может возвращать несколько таких результатов.

Снимок экрана: функция SORT, отображающая несколько результатов в нескольких ячейках.

Чтобы создать пользовательскую функцию, которая является формулой динамического массива, она должна вернуть двумерный массив значений. Если результаты попадают в соседние ячейки, которые уже имеют значения, формула отобразит ошибку #SPILL! .

Примеры кода

В первом примере показано, как вернуть динамический массив, который разливается вниз.

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

Во втором примере показано, как вернуть динамический массив, который разливается вправо.

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

В третьем примере показано, как вернуть динамический массив, который разливается как вниз, так и вправо.

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

В четвертом примере показано, как вернуть динамический массив разлива из функции потоковой передачи. Результаты стекают вниз, как в первом примере, и увеличиваются один раз в секунду amount на основе параметра . Дополнительные сведения о функциях потоковой передачи см. в статье Создание функции потоковой передачи.

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

См. также