Parameteroptionen für benutzerdefinierte Funktionen
Benutzerdefinierte Funktionen können mit vielen verschiedenen Parameteroptionen konfiguriert werden.
Wichtig
Beachten Sie, dass benutzerdefinierte Excel-Funktionen auf den folgenden Plattformen verfügbar sind.
- Office im Web
- Office unter Windows
- Microsoft 365-Abonnement
- retail unbefristete Office 2016 und höher
- volumenlizenzierte unbefristete Office 2021 und höher
- Office für Mac
Benutzerdefinierte Excel-Funktionen werden derzeit in den folgenden Artikeln nicht unterstützt:
- Office auf dem iPad
- Volumenlizenzierte unbefristete Versionen von Office 2019 oder früher unter Windows
Optionale Parameter
Wenn ein Benutzer eine Funktion in Excel aufruft, werden optionale Parameter in Klammern angezeigt. Im folgenden Beispiel kann die Add-Funktion optional eine dritte Zahl hinzufügen. Diese Funktion wird in Excel als =CONTOSO.ADD(first, second, [third]) angezeigt.
/**
* Calculates the sum of the specified numbers
* @customfunction
* @param {number} first First number.
* @param {number} second Second number.
* @param {number} [third] Third number to add. If omitted, third = 0.
* @returns {number} The sum of the numbers.
*/
function add(first, second, third) {
if (third === null) {
third = 0;
}
return first + second + third;
}
Hinweis
Wenn kein Wert für einen optionalen Parameter angegeben wird, weist Excel ihm den Wert nullzu. Dies bedeutet, dass standardmäßig initialisierte Parameter in TypeScript nicht wie erwartet funktionieren. Verwenden Sie nicht die Syntax function add(first:number, second:number, third=0):number , da sie nicht mit 0 initialisiert third wird. Verwenden Sie stattdessen die TypeScript-Syntax, wie im vorherigen Beispiel gezeigt.
Wenn Sie eine Funktion definieren, die einen oder mehrere optionale Parameter enthält, geben Sie an, was geschieht, wenn die optionalen Parameter NULL sind. Im folgenden Beispiel sind sowohl zipCode als auch dayOfWeek optionale Parameter für die getWeatherReport-Funktion. Wenn der zipCode Parameter NULL ist, wird der Standardwert auf 98052festgelegt. Wenn der dayOfWeek Parameter NULL ist, wird er auf Mittwoch festgelegt.
/**
* Gets a weather report for a specified zipCode and dayOfWeek
* @customfunction
* @param {number} [zipCode] Zip code. If omitted, zipCode = 98052.
* @param {string} [dayOfWeek] Day of the week. If omitted, dayOfWeek = Wednesday.
* @returns {string} Weather report for the day of the week in that zip code.
*/
function getWeatherReport(zipCode, dayOfWeek) {
if (zipCode === null) {
zipCode = 98052;
}
if (dayOfWeek === null) {
dayOfWeek = "Wednesday";
}
// Get weather report for specified zipCode and dayOfWeek.
// ...
}
Bereichsparameter
Ihre benutzerdefinierte Funktion akzeptiert möglicherweise einen Bereich von Zelldaten als Eingabeparameter. Eine Funktion kann auch einen Datenbereich zurückgeben. Excel übergibt einen Zelldatenbereich als zweidimensionales Array.
Ein Beispiel: Angenommen, Ihre Funktion gibt den zweithöchsten Wert aus einem Bereich von in Excel gespeicherten Zahlen zurück. Die folgende Funktion akzeptiert den Parameter values, und die JSDOC-Syntax number[][] legt die Eigenschaft des dimensionality Parameters in den JSON-Metadaten für diese Funktion auf matrix fest.
/**
* Returns the second highest value in a matrixed range of values.
* @customfunction
* @param {number[][]} values Multiple ranges of values.
*/
function secondHighest(values) {
let highest = values[0][0],
secondHighest = values[0][0];
for (let i = 0; i < values.length; i++) {
for (let j = 0; j < values[i].length; j++) {
if (values[i][j] >= highest) {
secondHighest = highest;
highest = values[i][j];
} else if (values[i][j] >= secondHighest) {
secondHighest = values[i][j];
}
}
}
return secondHighest;
}
Wiederholte Parameter
Ein wiederholter Parameter ermöglicht es einem Benutzer, eine Reihe optionaler Argumente für eine Funktion einzugeben. Wenn die Funktion aufgerufen wird, werden die Werte in einem Array für den Parameter bereitgestellt. Wenn der Parametername mit einer Zahl endet, wird die Zahl jedes Arguments inkrementell erhöht, z ADD(number1, [number2], [number3],…). B. . Dies entspricht der Konvention, die für integrierte Excel-Funktionen verwendet wird.
Die folgende Funktion summiert die Summe der Zahlen, Zellenadressen sowie Bereiche, sofern eingegeben.
/**
* The sum of all of the numbers.
* @customfunction
* @param operands A number (such as 1 or 3.1415), a cell address (such as A1 or $E$11), or a range of cell addresses (such as B3:F12)
*/
function ADD(operands: number[][][]): number {
let total: number = 0;
operands.forEach(range => {
range.forEach(row => {
row.forEach(num => {
total += num;
});
});
});
return total;
}
Diese Funktion wird in der Excel-Arbeitsmappe angezeigt =CONTOSO.ADD([operands], [operands]...) .
Wiederholter Einzelwertparameter
Ein sich wiederholender Einzelwertparameter ermöglicht die Übergabe mehrerer einzelner Werte. Der Benutzer könnte beispielsweise ADD(1,B2,3) eingeben. Im folgenden Beispiel wird gezeigt, wie ein einzelner Wertparameter deklariert wird.
/**
* @customfunction
* @param {number[]} singleValue An array of numbers that are repeating parameters.
*/
function addSingleValue(singleValue) {
let total = 0;
singleValue.forEach(value => {
total += value;
})
return total;
}
Einzelner Bereichsparameter
Ein einzelner Bereichsparameter ist technisch gesehen kein wiederholter Parameter, ist aber hier enthalten, da die Deklaration sich wiederholenden Parametern sehr ähnlich ist. Es würde dem Benutzer als ADD(A2:B3) erscheinen, in dem ein einzelner Bereich aus Excel übergeben wird. Im folgenden Beispiel wird gezeigt, wie ein einzelner Bereichsparameter deklariert wird.
/**
* @customfunction
* @param {number[][]} singleRange
*/
function addSingleRange(singleRange) {
let total = 0;
singleRange.forEach(setOfSingleValues => {
setOfSingleValues.forEach(value => {
total += value;
})
})
return total;
}
Wiederholter Bereichsparameter
Ein wiederholter Bereichsparameter ermöglicht die Übergabe mehrerer Bereiche oder Zahlen. Der Benutzer könnte beispielsweise ADD(5;B2;C3;8;E5:E8) eingeben. Wiederholte Bereiche werden in der Regel mit dem Typ number[][][] angegeben, da es sich um dreidimensionale Matrizen handelt. Ein Beispiel finden Sie im Standard Beispiel für wiederholte Parameter.
Deklarieren von wiederholten Parametern
Geben Sie in Typescript an, dass der Parameter mehrdimensional ist. Beispielsweise ADD(values: number[]) würde ein eindimensionales Array, ADD(values:number[][]) ein zweidimensionales Array usw. angeben.
Verwenden Sie @param values {number[]} in JavaScript für eindimensionale Arrays, @param <name> {number[][]} für zweidimensionale Arrays usw. für weitere Dimensionen.
Stellen Sie für handverfasste JSON-Dateien sicher, dass Ihr Parameter in Ihrer JSON-Datei als "repeating": true angegeben ist, und überprüfen Sie, ob Ihre Parameter als "dimensionality": matrixgekennzeichnet sind.
Aufrufparameter
Jede benutzerdefinierte Funktion wird automatisch ein invocation Argument als letzter Eingabeparameter übergeben, auch wenn sie nicht explizit deklariert ist. Dieser invocation Parameter entspricht dem Invocation-Objekt . Das Invocation -Objekt kann verwendet werden, um zusätzlichen Kontext abzurufen, z. B. die Adresse der Zelle, die Ihre benutzerdefinierte Funktion aufgerufen hat. Um auf das Invocation Objekt zuzugreifen, müssen Sie als letzter Parameter in Ihrer benutzerdefinierten Funktion deklarieren invocation .
Hinweis
Der invocation Parameter wird nicht als benutzerdefiniertes Funktionsargument für Benutzer in Excel angezeigt.
Das folgende Beispiel zeigt, wie Sie den invocation -Parameter verwenden, um die Adresse der Zelle zurückzugeben, die Ihre benutzerdefinierte Funktion aufgerufen hat. In diesem Beispiel wird die address-Eigenschaft des Invocation -Objekts verwendet. Um auf das Invocation Objekt zuzugreifen, deklarieren CustomFunctions.Invocation Sie zuerst als Parameter in Ihrem JSDoc. Deklarieren Sie @requiresAddress als Nächstes in Ihrem JSDoc, um auf die address -Eigenschaft des Invocation -Objekts zuzugreifen. Rufen Sie schließlich innerhalb der -Funktion die address -Eigenschaft ab, und geben Sie sie dann zurück.
/**
* Return the address of the cell that invoked the custom function.
* @customfunction
* @param {number} first First parameter.
* @param {number} second Second parameter.
* @param {CustomFunctions.Invocation} invocation Invocation object.
* @requiresAddress
*/
function getAddress(first, second, invocation) {
const address = invocation.address;
return address;
}
In Excel gibt eine benutzerdefinierte Funktion, die die address -Eigenschaft des Invocation -Objekts aufruft, die absolute Adresse zurück, die dem Format SheetName!RelativeCellAddress in der Zelle folgt, die die Funktion aufgerufen hat. Wenn sich der Eingabeparameter beispielsweise auf einem Blatt namens Preise in Zelle F6 befindet, lautet Prices!F6der zurückgegebene Parameteradressenwert .
Hinweis
Wenn ein Leerzeichen oder eines der folgenden Zeichen in einem Arbeitsblattnamen enthalten ist: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . , >dann wird der Arbeitsblattname in der zurückgegebenen Adresse in einfache Anführungszeichen eingeschlossen, sodass das Format lautet 'SheetName'!RelativeCellAddress, z. B 'Latest Prices'!F6. . Wenn sich das einfache Anführungszeichen (Apostroph) "" im Namen befindet, enthält die zurückgegebene Adresse zwei solche Zeichen in einer Zeile; Beispiel: 'Bob''s Region'!F6.
Der invocation Parameter kann auch verwendet werden, um Informationen an Excel zu senden. Weitere Informationen finden Sie unter Erstellen einer Streamingfunktion .
Erkennen der Adresse eines Parameters
In Kombination mit dem Aufrufparameter können Sie das Invocation-Objekt verwenden, um die Adresse eines benutzerdefinierten Funktionseingabeparameters abzurufen. Wenn die parameterAddresses-Eigenschaft des Invocation -Objekts aufgerufen wird, kann eine Funktion die Adressen aller Eingabeparameter zurückgeben.
Dies ist in Szenarien nützlich, in denen eingabedatentypen variieren können. Die Adresse eines Eingabeparameters kann verwendet werden, um das Zahlenformat des Eingabewerts zu überprüfen. Das Zahlenformat kann dann bei Bedarf vor der Eingabe angepasst werden. Die Adresse eines Eingabeparameters kann auch verwendet werden, um zu erkennen, ob der Eingabewert verwandte Eigenschaften aufweist, die für nachfolgende Berechnungen relevant sein können.
Hinweis
Wenn Sie mit manuell erstellten JSON-Metadaten arbeiten, um Parameteradressen anstelle des Yeoman-Generators für Office-Add-Ins zurückzugeben, muss für das options Objekt die requiresParameterAddresses -Eigenschaft auf truefestgelegt sein, und für das result Objekt muss die dimensionality -Eigenschaft auf matrixfestgelegt sein.
Die folgende benutzerdefinierte Funktion akzeptiert drei Eingabeparameter, ruft die parameterAddresses -Eigenschaft des Invocation -Objekts für jeden Parameter ab und gibt dann die Adressen zurück.
/**
* Return the addresses of three parameters.
* @customfunction
* @param {string} firstParameter First parameter.
* @param {string} secondParameter Second parameter.
* @param {string} thirdParameter Third parameter.
* @param {CustomFunctions.Invocation} invocation Invocation object.
* @returns {string[][]} The addresses of the parameters, as a 2-dimensional array.
* @requiresParameterAddresses
*/
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
const addresses = [
[invocation.parameterAddresses[0]],
[invocation.parameterAddresses[1]],
[invocation.parameterAddresses[2]]
];
return addresses;
}
Wenn eine benutzerdefinierte Funktion, die die parameterAddresses -Eigenschaft aufruft, ausgeführt wird, wird die Parameteradresse nach dem Format SheetName!RelativeCellAddress in der Zelle zurückgegeben, die die Funktion aufgerufen hat. Wenn sich der Eingabeparameter beispielsweise auf einem Blatt namens Kosten in Zelle D8 befindet, lautet Costs!D8der zurückgegebene Parameteradressenwert . Wenn die benutzerdefinierte Funktion über mehrere Parameter verfügt und mehr als eine Parameteradresse zurückgegeben wird, werden die zurückgegebenen Adressen über mehrere Zellen verteilt und vertikal von der Zelle absteigen, die die Funktion aufgerufen hat.
Hinweis
Wenn ein Leerzeichen oder eines der folgenden Zeichen in einem Arbeitsblattnamen enthalten ist: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . , >dann wird der Arbeitsblattname in der zurückgegebenen Adresse in einfache Anführungszeichen eingeschlossen, sodass das Format lautet 'SheetName'!RelativeCellAddress, z. B 'Latest Prices'!F6. . Wenn sich das einfache Anführungszeichen (Apostroph) "" im Namen befindet, enthält die zurückgegebene Adresse zwei solche Zeichen in einer Zeile; Beispiel: 'Bob''s Region'!F6.
Nächste Schritte
Erfahren Sie, wie Sie flüchtige Werte in Ihren benutzerdefinierten Funktionen verwenden.
Siehe auch
- Empfangen und Verarbeiten von Daten mit benutzerdefinierten Funktionen
- Automatisches Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen
- Manuelles Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen
- Erstellen von benutzerdefinierten Funktionen in Excel
- Lernprogramm: Erstellen von benutzerdefinierten Funktionen in Excel
Office Add-ins