Opções de parâmetro 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
- varejo perpétuo Office 2016 e posterior
- Office 2021 perpétuo licenciado por volume e posterior
- Office no Mac
No momento, as funções personalizadas do Excel não têm suporte no seguinte:
- Office no iPad
- versões perpétuas licenciadas por volume do Office 2019 ou anteriores no Windows
Parâmetros opcionais
Quando um usuário invoca uma função no Excel, os parâmetros opcionais são exibidos entre colchetes. No exemplo a seguir, a função de adição pode, opcionalmente, adicionar um terceiro número. Essa função aparece 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 nenhum valor é especificado para um parâmetro opcional, o Excel atribui-lhe o valor null. Isso significa que os parâmetros inicializados padrão no TypeScript não funcionarão conforme o esperado. Não use a sintaxe function add(first:number, second:number, third=0):number porque ela não será inicializada third como 0. Em vez disso, use a sintaxe TypeScript, conforme mostrado no exemplo anterior.
Quando você 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 padrão será definido como 98052. Se o dayOfWeek parâmetro for nulo, ele será 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
Sua função personalizada pode aceitar um intervalo de dados de célula como um parâmetro de entrada. Uma função também pode retornar um intervalo de dados. O Excel passará um intervalo de dados de célula 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 a seguir aceita o parâmetro valuese a sintaxe number[][] JSDOC define a propriedade do dimensionality parâmetro como matrix nos metadados JSON para essa 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;
}
Repetindo parâmetros
Um parâmetro repetido permite que um usuário insira uma série de argumentos opcionais em uma função. Quando a função é chamada, os valores são fornecidos em uma 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],…). Isso corresponde à convenção usada para funções internas do Excel.
A função a seguir soma o total de números, endereços de célula, bem como intervalos, se inseridos.
/**
* 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;
}
Essa função é exibida =CONTOSO.ADD([operands], [operands]...) na pasta de trabalho do Excel.
Repetindo parâmetro de valor único
Um parâmetro de valor único repetido permite que vários valores únicos sejam passados. Por exemplo, o usuário pode inserir ADD(1,B2,3). O exemplo a seguir mostra como declarar um único parâmetro de valor.
/**
* @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
Um parâmetro de intervalo único não é tecnicamente um parâmetro repetitivo, mas é incluído aqui porque a declaração é muito semelhante aos parâmetros repetidos. Ele aparece para o usuário como ADD(A2:B3) em que um único intervalo é passado do Excel. O exemplo a seguir 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 repetido
Um parâmetro de intervalo repetido permite que vários intervalos ou números sejam passados. Por exemplo, o usuário pode inserir ADD(5,B2,C3,8,E5:E8). Intervalos repetidos geralmente são especificados com o tipo number[][][] , pois são matrizes tridimensionais. Para obter um exemplo, consulte o exemplo main listado para parâmetros repetidos.
Declarando parâmetros repetidos
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 por diante.
No JavaScript, use @param values {number[]} para matrizes unidimensionais, @param <name> {number[][]} para matrizes bidimensionais e assim por diante para mais dimensões.
Para JSON criado à mão, verifique se seu parâmetro está especificado como "repeating": true em seu arquivo JSON, bem como marcar que seus parâmetros sejam marcados como "dimensionality": matrix.
Parâmetro de invocação
Cada função personalizada é automaticamente passada um invocation argumento como o último parâmetro de entrada, mesmo que não seja explicitamente declarado. Esse invocation parâmetro corresponde ao objeto Invocação . O Invocation objeto pode ser usado para recuperar contexto adicional, como o endereço da célula que invocou sua função personalizada. Para acessar o Invocation objeto, você deve declarar invocation como o último parâmetro em sua função personalizada.
Observação
O invocation parâmetro não aparece como um argumento de função personalizado para usuários no Excel.
O exemplo a seguir mostra como usar o invocation parâmetro para retornar o endereço da célula que invocou sua função personalizada. Este exemplo usa a propriedade de endereço do Invocation objeto. Para acessar o Invocation objeto, primeiro declare CustomFunctions.Invocation como um parâmetro em seu JSDoc. Em seguida, declare @requiresAddress em seu JSDoc para acessar a address propriedade do Invocation objeto. Por fim, dentro da função, recupere e, em seguida, retorne 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 retornará 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 em uma planilha chamada Preços na célula F6, o valor do endereço do parâmetro retornado será Prices!F6.
Observação
Se um espaço em branco ou qualquer um dos seguintes caracteres estiver em um nome de planilha: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >, então o nome da planilha no endereço retornado está incluído em aspas individuais, portanto o formato é 'SheetName'!RelativeCellAddress; por exemplo, 'Latest Prices'!F6. Se o caractere de marca de cotação única (apóstrofo) estiver no nome, o endereço retornado terá dois desses caracteres em uma linha; por exemplo, 'Bob''s Region'!F6.
O invocation parâmetro também pode ser usado para enviar informações ao Excel. Consulte Fazer uma função de streaming para saber mais.
Detectar o endereço de um parâmetro
Em combinação com o parâmetro de invocação, você pode usar o objeto Invocation para recuperar 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 retorne os endereços de todos os parâmetros de entrada.
Isso é ú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 usado para marcar o formato de número do valor de entrada. 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 usado para detectar se o valor de entrada tem propriedades relacionadas que possam ser relevantes para cálculos subsequentes.
Observação
Se você estiver trabalhando com metadados JSON criados manualmente para retornar endereços de parâmetro em vez do gerador Yeoman para Suplementos do Office, o options objeto deve ter a requiresParameterAddresses propriedade definida como true, e o result objeto deve ter a dimensionality propriedade definida como matrix.
A função personalizada a seguir usa três parâmetros de entrada, recupera a parameterAddresses propriedade do Invocation objeto para cada parâmetro e retorna 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 é retornado seguindo o formato SheetName!RelativeCellAddress na célula que invocou a função. Por exemplo, se o parâmetro de entrada estiver localizado em uma planilha chamada Custos na célula D8, o valor do endereço do parâmetro retornado será Costs!D8. Se a função personalizada tiver vários parâmetros e mais de um endereço de parâmetro for retornado, os endereços retornados serão espalhados 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 caracteres estiver em um nome de planilha: ~ ' ! @ # $ % ^ & ( ) - _ = + { } | ; : , ' < . >, então o nome da planilha no endereço retornado está incluído em aspas individuais, portanto o formato é 'SheetName'!RelativeCellAddress; por exemplo, 'Latest Prices'!F6. Se o caractere de marca de cotação única (apóstrofo) estiver no nome, o endereço retornado terá dois desses caracteres em uma linha; por exemplo, 'Bob''s Region'!F6.
Próximas etapas
Saiba como usar valores voláteis em suas funções personalizadas.