Freigeben über

Zurückgeben mehrerer Ergebnisse aus Ihrer benutzerdefinierten Funktion

Ihre benutzerdefinierte Funktion kann mehrere Ergebnisse zurückgeben, die benachbarte Zellen füllen. Dieses Verhalten wird als "Überlauf" bezeichnet. Wenn eine benutzerdefinierte Funktion ein Array von Ergebnissen zurückgibt, wird dies als dynamische Arrayformel bezeichnet. Dadurch können Ihre benutzerdefinierten Funktionen wie die integrierten dynamischen Arrayfunktionen von Excel wie SORT, FILTERund UNIQUEfunktionieren. Weitere Informationen zu formeln dynamischen Arrays in Excel finden Sie unter Dynamische Arrays und Verhalten von übergelaufenen Arrays.

Die folgende Abbildung zeigt, wie die SORT Funktion in benachbarte Zellen überläuft. Ihre benutzerdefinierte Funktion kann auch mehrere Ergebnisse wie dieses zurückgeben.

Screenshot der Funktion

Wichtige Punkte

  • Gibt ein zweidimensionales Array zurück, um eine benutzerdefinierte Funktion zu erstellen, die Ergebnisse verschüttet.
  • Ergebnisse werden automatisch in benachbarte Zellen überlaufen.
  • Wenn benachbarte Zellen Daten enthalten, zeigt die Formel einen #SPILL! Fehler an.
  • Arrays werden durch Hinzufügen von Zeilen, rechts durch Hinzufügen von Spalten oder beides für rechteckige Bereiche überschüttet.
  • Dynamische Arrays funktionieren mit Streamingfunktionen, die Ergebnisse im Laufe der Zeit aktualisieren.

Codebeispiele

Um eine benutzerdefinierte Funktion zu erstellen, die dynamische Arrays zurückgibt, geben Sie ein zweidimensionales Array von Werten zurück. Die Arraystruktur bestimmt die Richtung des Überlaufs: Zeilen erstellen vertikale Überläufe, Spalten erstellen horizontale Überläufe, und beide erstellen rechteckige Bereiche.

Überlauf nach unten

Im folgenden Beispiel wird ein dynamisches Array zurückgegeben, das überläuft. Jedes innere Array stellt eine Zeile dar.

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

Überlauf nach rechts

Im folgenden Beispiel wird ein dynamisches Array zurückgegeben, das nach rechts ausläuft. Das einzelne innere Array enthält mehrere Werte.

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

Verschütten in beide Richtungen

Im folgenden Beispiel wird ein dynamisches Array zurückgegeben, das sowohl nach unten als auch nach rechts überläuft und einen rechteckigen Bereich erstellt.

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

Streaming dynamischer Arrays

Kombinieren Sie dynamische Arrays mit Streamingfunktionen, um Ergebnisse zu erstellen, die im Laufe der Zeit aktualisiert werden. Im folgenden Beispiel werden Werte zurückgegeben, die basierend auf dem amount Parameter einmal pro Sekunde überlaufen und inkrementiert werden. Weitere Informationen zu Streamingfunktionen finden Sie unter Erstellen einer Streamingfunktion.

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

Verarbeiten von Daten mit dynamischen Arrays

Dynamische Arrays sind nützlich für die Verarbeitung und Transformation von Eingabedaten. Im folgenden Beispiel wird ein Array von Zahlen verwendet und sowohl die Werte als auch ihre Quadrate zurückgegeben.

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

Siehe auch

  • Last updated on