Opciones de parámetros de funciones personalizadas
Las funciones personalizadas se pueden configurar con muchas opciones de parámetro diferentes.
Importante
Tenga en cuenta que las funciones personalizadas están disponibles en Excel en las siguientes plataformas.
- Office en Windows
- Suscripción a Microsoft 365
- Retail perpetual Office 2016 y versiones posteriores
- Office en Mac
- Office en la Web
Las funciones personalizadas de Excel no se admiten actualmente en lo siguiente:
- Office en iPad
- versiones perpetuas con licencia por volumen de Office 2019 o versiones anteriores
Parámetros opcionales
Cuando un usuario invoca una función en Excel, los parámetros opcionales aparecen entre corchetes. En el ejemplo siguiente, la función add puede agregar opcionalmente un tercer número. Esta función aparece como =CONTOSO.ADD(first, second, [third]) en Excel.
/**
* 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;
}
Nota:
Cuando no se especifica ningún valor para un parámetro opcional, Excel le asigna el valor null. Esto significa que los parámetros inicializados de forma predeterminada en TypeScript no funcionarán según lo esperado. No use la sintaxis function add(first:number, second:number, third=0):number porque no se inicializará third en 0. En su lugar, use la sintaxis de TypeScript como se muestra en el ejemplo anterior.
Al definir una función que contiene uno o varios parámetros opcionales, especifique lo que ocurre cuando los parámetros opcionales son NULL. En el ejemplo siguiente, zipCode y dayOfWeek son dos parámetros opcionales de la función getWeatherReport. Si el zipCode parámetro es null, el valor predeterminado se establece en 98052. Si el dayOfWeek parámetro es null, se establece en Miércoles.
/**
* 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.
// ...
}
Parámetros de intervalo
La función personalizada puede aceptar un intervalo de datos de celda como parámetro de entrada. Una función también puede devolver un intervalo de datos. Excel pasará un rango de datos de celda como una matriz bidimensional.
Por ejemplo, imagine que la función devuelve el segundo valor más alto de un rango de números almacenados en Excel. La siguiente función acepta el parámetro valuesy la sintaxis number[][] JSDOC establece la propiedad matrix del dimensionality parámetro en en los metadatos JSON de esta función.
/**
* 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;
}
Repetición de parámetros
Un parámetro de repetición permite a un usuario escribir una serie de argumentos opcionales en una función. Cuando se llama a la función, los valores se proporcionan en una matriz para el parámetro . Si el nombre del parámetro termina con un número, el número de cada argumento aumentará incrementalmente, como ADD(number1, [number2], [number3],…). Esto coincide con la convención que se usa para las funciones integradas de Excel.
La siguiente función suma el total de números, direcciones de celda, así como rangos, si se escribe.
/**
* 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;
}
Esta función se muestra =CONTOSO.ADD([operands], [operands]...) en el libro de Excel.
Repetición del parámetro de valor único
Un parámetro de valor único repetición permite pasar varios valores únicos. Por ejemplo, el usuario podría escribir ADD(1,B2,3). En el ejemplo siguiente se muestra cómo declarar un parámetro de valor único.
/**
* @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;
}
Parámetro de intervalo único
Un parámetro de intervalo único no es técnicamente un parámetro repetido, pero se incluye aquí porque la declaración es muy similar a los parámetros de repetición. Parecería al usuario como ADD(A2:B3) donde se pasa un solo rango desde Excel. En el ejemplo siguiente se muestra cómo declarar un parámetro de intervalo único.
/**
* @customfunction
* @param {number[][]} singleRange
*/
function addSingleRange(singleRange) {
let total = 0;
singleRange.forEach(setOfSingleValues => {
setOfSingleValues.forEach(value => {
total += value;
})
})
return total;
}
Parámetro de intervalo de repetición
Un parámetro de intervalo de repetición permite pasar varios intervalos o números. Por ejemplo, el usuario podría escribir ADD(5,B2,C3,8,E5:E8). Normalmente, los intervalos de repetición se especifican con el tipo number[][][] , ya que son matrices tridimensionales. Para obtener un ejemplo, consulte el ejemplo principal que aparece para los parámetros de repetición.
Declaración de parámetros repetidos
En Typescript, indique que el parámetro es multidimensional. Por ejemplo, ADD(values: number[]) indicaría una matriz unidimensional, ADD(values:number[][]) indicaría una matriz bidimensional, etc.
En JavaScript, use @param values {number[]} para matrices unidimensionales, @param <name> {number[][]} para matrices bidimensionales, etc. para más dimensiones.
En el caso de JSON creado manualmente, asegúrese de que el parámetro se especifica como "repeating": true en el archivo JSON, así como de comprobar que los parámetros están marcados como "dimensionality": matrix.
Parámetro Invocation
Cada función personalizada se pasa automáticamente un invocation argumento como último parámetro de entrada, incluso si no se declara explícitamente. Este invocation parámetro corresponde al objeto Invocation . El Invocation objeto se puede usar para recuperar contexto adicional, como la dirección de la celda que invocó la función personalizada. Para tener acceso al Invocation objeto, debe declarar invocation como el último parámetro de la función personalizada.
Nota:
El invocation parámetro no aparece como argumento de función personalizada para los usuarios de Excel.
En el ejemplo siguiente se muestra cómo usar el invocation parámetro para devolver la dirección de la celda que invocó la función personalizada. En este ejemplo se usa la propiedad address del Invocation objeto . Para obtener acceso al Invocation objeto, declare CustomFunctions.Invocation primero como parámetro en el JSDoc. A continuación, declare @requiresAddress en jsdoc para tener acceso a la address propiedad del Invocation objeto . Por último, en la función , recupere y, a continuación, devuelva la address propiedad .
/**
* 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;
}
En Excel, una función personalizada que llame a la address propiedad del Invocation objeto devolverá la dirección absoluta siguiendo el formato SheetName!RelativeCellAddress de la celda que invocó la función. Por ejemplo, si el parámetro de entrada se encuentra en una hoja denominada Precios en la celda F6, el valor de dirección del parámetro devuelto será Prices!F6.
Nota:
Si un espacio en blanco o cualquiera de los caracteres siguientes está en un nombre de hoja de cálculo: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >, el nombre de la hoja de cálculo de la dirección devuelta se incluye entre comillas simples, por lo que el formato es 'SheetName'!RelativeCellAddress; por ejemplo, 'Latest Prices'!F6. Si el carácter de comillas simples (apóstrofo), ', está en el nombre, la dirección devuelta tiene dos caracteres de este tipo en una fila; por ejemplo, 'Bob''s Region'!F6.
El invocation parámetro también se puede usar para enviar información a Excel. Consulte Creación de una función de streaming para obtener más información.
Detección de la dirección de un parámetro
En combinación con el parámetro de invocación, puede usar el objeto Invocation para recuperar la dirección de un parámetro de entrada de función personalizada. Cuando se invoca, la propiedad parameterAddresses del Invocation objeto permite que una función devuelva las direcciones de todos los parámetros de entrada.
Esto resulta útil en escenarios en los que los tipos de datos de entrada pueden variar. La dirección de un parámetro de entrada se puede usar para comprobar el formato numérico del valor de entrada. El formato de número se puede ajustar antes de la entrada, si es necesario. La dirección de un parámetro de entrada también se puede usar para detectar si el valor de entrada tiene propiedades relacionadas que puedan ser pertinentes para los cálculos posteriores.
Nota:
Si trabaja con metadatos JSON creados manualmente para devolver direcciones de parámetro en lugar del generador de Yeoman para complementos de Office, el options objeto debe tener la requiresParameterAddresses propiedad establecida trueen y el result objeto debe tener la dimensionality propiedad establecida matrixen .
La siguiente función personalizada toma tres parámetros de entrada, recupera la parameterAddresses propiedad del Invocation objeto para cada parámetro y, a continuación, devuelve las direcciones.
/**
* 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;
}
Cuando se ejecuta una función personalizada que llama a la parameterAddresses propiedad , la dirección del parámetro se devuelve siguiendo el formato SheetName!RelativeCellAddress de la celda que invocó la función. Por ejemplo, si el parámetro de entrada se encuentra en una hoja denominada Costos en la celda D8, el valor de dirección del parámetro devuelto será Costs!D8. Si la función personalizada tiene varios parámetros y se devuelve más de una dirección de parámetro, las direcciones devueltas se derramarán entre varias celdas, descendiendo verticalmente desde la celda que invocó la función.
Nota:
Si un espacio en blanco o cualquiera de los caracteres siguientes está en un nombre de hoja de cálculo: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >, el nombre de la hoja de cálculo de la dirección devuelta se incluye entre comillas simples, por lo que el formato es 'SheetName'!RelativeCellAddress; por ejemplo, 'Latest Prices'!F6. Si el carácter de comillas simples (apóstrofo), ', está en el nombre, la dirección devuelta tiene dos caracteres de este tipo en una fila; por ejemplo, 'Bob''s Region'!F6.
Pasos siguientes
Obtenga información sobre cómo usar valores volátiles en las funciones personalizadas.
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de