Opções de parâmetros de funções personalizadas
As funções personalizadas são configuráveis com muitas opções de parâmetros diferentes.
Importante
Observe que as funções personalizadas do Excel estão disponíveis nas plataformas a seguir.
- Office na Web
- Office no Windows
- Assinatura do Microsoft 365
- revenda perpétua do Office 2016 e posterior
- Office 2021 perpétuas licenciadas em volume e posteriores
- Office no Mac
As funções personalizadas do Excel não são atualmente suportadas no seguinte:
- Office no iPad
- versões perpétuas licenciadas em volume do Office 2019 ou anterior no Windows
Observação
O manifesto unificado do Microsoft 365 não suporta atualmente projetos de funções personalizadas. Tem de utilizar o manifesto apenas de suplemento para projetos de funções personalizadas. Para obter mais informações, veja Manifesto de Suplementos do Office.
Parâmetros opcionais
Quando um usuário invoca uma função no Excel, os parâmetros opcionais são exibidos entre colchetes. No exemplo seguinte, a função add pode opcionalmente adicionar um terceiro número. Esta função é apresentada como =CONTOSO.ADD(first, second, [third]) no 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;
}
Observação
Quando não é especificado nenhum valor para um parâmetro opcional, o Excel atribui-lhe o valor null. Isto significa que os parâmetros inicializados por predefinição no TypeScript não funcionarão como esperado. Não utilize a sintaxe function add(first:number, second:number, third=0):number porque não será inicializar third para 0. Em vez disso, utilize a sintaxe TypeScript, conforme mostrado no exemplo anterior.
Quando define uma função que contém um ou mais parâmetros opcionais, especifique o que acontece quando os parâmetros opcionais são nulos. No exemplo a seguir, zipCode e dayOfWeek são dois parâmetros opcionais da função getWeatherReport. Se o zipCode parâmetro for nulo, o valor predefinido 98052será . Se o dayOfWeek parâmetro for nulo, está definido como quarta-feira.
/**
* 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
A função personalizada pode aceitar um intervalo de dados de células como um parâmetro de entrada. Uma função também pode devolver um intervalo de dados. O Excel transmitirá um intervalo de dados de células como uma matriz bidimensional.
Por exemplo, suponha que sua função retorne o segundo maior valor de um intervalo de números armazenados no Excel. A função seguinte aceita o parâmetro valuese a sintaxe number[][] JSDOC define a propriedade do dimensionality parâmetro como matrix nos metadados JSON para esta função.
/**
* 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;
}
Parâmetros de repetição
Um parâmetro de repetição permite que um utilizador introduza uma série de argumentos opcionais numa função. Quando a função é chamada, os valores são fornecidos numa matriz para o parâmetro . Se o nome do parâmetro terminar com um número, o número de cada argumento aumentará incrementalmente, como ADD(number1, [number2], [number3],…). Isto corresponde à convenção utilizada para funções incorporadas do Excel.
A função seguinte soma o total de números, endereços de célula, bem como intervalos, se introduzidos.
/**
* 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 função é apresentada =CONTOSO.ADD([operands], [operands]...) no livro do Excel.
Parâmetro de valor único de repetição
Um parâmetro de valor único de repetição permite a passagem de vários valores únicos. Por exemplo, o utilizador pode introduzir ADD(1,B2,3). O exemplo seguinte mostra como declarar um 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
Tecnicamente, um parâmetro de intervalo único não é um parâmetro de repetição, mas é incluído aqui porque a declaração é muito semelhante aos parâmetros repetidos. Apareceria para o utilizador como ADD(A2:B3) em que um único intervalo é transmitido a partir do Excel. O exemplo seguinte mostra como declarar um único parâmetro de intervalo.
/**
* @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 repetição
Um parâmetro de intervalo de repetição permite a passagem de vários intervalos ou números. Por exemplo, o utilizador pode introduzir ADD(5;B2;C3;8;E5:E8). Os intervalos de repetição são geralmente especificados com o tipo number[][][] , uma vez que são matrizes tridimensionais. Para obter um exemplo, veja o exemplo de main listado para parâmetros de repetição.
Declarar parâmetros de repetição
Em Typescript, indique que o parâmetro é multidimensional. Por exemplo, ADD(values: number[]) indicaria uma matriz unidimensional, ADD(values:number[][]) indicaria uma matriz bidimensional e assim sucessivamente.
Em JavaScript, utilize @param values {number[]} para matrizes unidimensionais, @param <name> {number[][]} para matrizes bidimensionais e assim sucessivamente para obter mais dimensões.
Para JSON criado à mão, certifique-se de que o parâmetro está especificado como "repeating": true no ficheiro JSON, bem como marcar que os parâmetros estão marcados como "dimensionality": matrix.
Parâmetro de invocação
Cada função personalizada passa automaticamente um invocation argumento como o último parâmetro de entrada, mesmo que não seja explicitamente declarado. Este invocation parâmetro corresponde ao objeto invocação . O Invocation objeto pode ser utilizado para obter contexto adicional, como o endereço da célula que invocou a função personalizada. Para aceder ao Invocation objeto, tem de declarar invocation como o último parâmetro na sua função personalizada.
Observação
O invocation parâmetro não aparece como um argumento de função personalizada para os utilizadores no Excel.
O exemplo seguinte mostra como utilizar o invocation parâmetro para devolver o endereço da célula que invocou a função personalizada. Este exemplo utiliza a propriedade de endereço do Invocation objeto. Para aceder ao Invocation objeto, declare CustomFunctions.Invocation primeiro como um parâmetro no JSDoc. Em seguida, declare @requiresAddress no JSDoc para aceder à address propriedade do Invocation objeto. Por fim, dentro da função, obtenha e, em seguida, devolva a address propriedade .
/**
* 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;
}
No Excel, uma função personalizada que chama a address propriedade do Invocation objeto devolverá o endereço absoluto seguindo o formato SheetName!RelativeCellAddress na célula que invocou a função. Por exemplo, se o parâmetro de entrada estiver localizado numa folha denominada Preços na célula F6, o valor do endereço do parâmetro devolvido será Prices!F6.
Observação
Se um espaço em branco ou qualquer um dos seguintes carateres estiver num nome de folha de cálculo: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >, então o nome da folha de cálculo no endereço devolvido está entre plicas, pelo que o formato é 'SheetName'!RelativeCellAddress; por exemplo, 'Latest Prices'!F6. Se o caráter de plica (apóstrofo), ', estiver no nome, o endereço devolvido tem dois carateres desse tipo numa linha; por exemplo, 'Bob''s Region'!F6.
O invocation parâmetro também pode ser utilizado para enviar informações para o Excel. Consulte Criar uma função de transmissão em fluxo para saber mais.
Detetar o endereço de um parâmetro
Em combinação com o parâmetro de invocação, pode utilizar o objeto Invocação para obter o endereço de um parâmetro de entrada de função personalizada. Quando invocada, a propriedade parameterAddresses do Invocation objeto permite que uma função devolva os endereços de todos os parâmetros de entrada.
Isto é útil em cenários em que os tipos de dados de entrada podem variar. O endereço de um parâmetro de entrada pode ser utilizado para marcar o formato de número do valor de entrada. Em seguida, o formato de número pode ser ajustado antes da entrada, se necessário. O endereço de um parâmetro de entrada também pode ser utilizado para detetar se o valor de entrada tem propriedades relacionadas que possam ser relevantes para cálculos subsequentes.
Observação
Se estiver a trabalhar com metadados JSON criados manualmente para devolver endereços de parâmetros em vez do gerador Yeoman para Suplementos do Office, o options objeto tem de ter a requiresParameterAddresses propriedade definida como truee o result objeto tem de ter a dimensionality propriedade definida como matrix.
A seguinte função personalizada utiliza três parâmetros de entrada, obtém a parameterAddresses propriedade do Invocation objeto para cada parâmetro e, em seguida, devolve os endereços.
/**
* 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;
}
Quando uma função personalizada que chama a parameterAddresses propriedade é executada, o endereço do parâmetro é devolvido seguindo o formato SheetName!RelativeCellAddress na célula que invocou a função. Por exemplo, se o parâmetro de entrada estiver localizado numa folha denominada Custos na célula D8, o valor do endereço do parâmetro devolvido será Costs!D8. Se a função personalizada tiver múltiplos parâmetros e for devolvido mais do que um endereço de parâmetro, os endereços devolvidos serão transbordos por várias células, descendo verticalmente da célula que invocou a função.
Observação
Se um espaço em branco ou qualquer um dos seguintes carateres estiver num nome de folha de cálculo: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >, então o nome da folha de cálculo no endereço devolvido está entre plicas, pelo que o formato é 'SheetName'!RelativeCellAddress; por exemplo, 'Latest Prices'!F6. Se o caráter de plica (apóstrofo), ', estiver no nome, o endereço devolvido tem dois carateres desse tipo numa linha; por exemplo, 'Bob''s Region'!F6.
Próximas etapas
Saiba como utilizar valores voláteis nas suas funções personalizadas.