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.

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 add pode, opcionalmente, adicionar um terceiro número. Esta 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;
}

/**
 * Calculates the sum of the specified numbers
 * @customfunction
 * @param first First number.
 * @param second Second number.
 * @param [third] Third number to add. If omitted, third = 0.
 * @returns The sum of the numbers.
 */
function add(first: number, second: number, third?: number): number {
  if (third === null) {
    third = 0;
  }
  return first + second + third;
}

Ao definir 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.
  // ...
}

/**
 * Gets a weather report for a specified zipCode and dayOfWeek
 * @customfunction
 * @param zipCode Zip code. If omitted, zipCode = 98052.
 * @param [dayOfWeek] Day of the week. If omitted, dayOfWeek = Wednesday.
 * @returns Weather report for the day of the week in that zip code.
 */
function getWeatherReport(zipCode?: number, dayOfWeek?: string): string {
  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 parâmetro de entrada. Uma função também pode retornar um intervalo de dados. O Excel transmitirá 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 dessa 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 = -Infinity,
    secondHighest = -Infinity;
  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 repetidos

Um parâmetro de repetição permite que um usuário insira uma série de argumentos opcionais para 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;
}

Esta função é exibida =CONTOSO.ADD([operands], [operands]...) na pasta de trabalho do Excel.

Parâmetro de valor único repetido

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 único parâmetro de intervalo não é tecnicamente um parâmetro repetido, mas é incluído aqui porque a declaração é muito semelhante aos parâmetros repetidos. Ele apareceria para o usuário como ADD(A2:B3), onde 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). Os intervalos repetidos geralmente são especificados com o tipo number[][][] , pois são matrizes tridimensionais. Para um exemplo, consulte o exemplo principal listado para repetir parâmetros.

Declarar parâmetros repetidos

Para declarar um parâmetro repetido, indique que o parâmetro é multidimensional. Por exemplo, em TypeScript, ADD(values: number[]) indicaria uma matriz unidimensional, ADD(values:number[][]) indicaria uma matriz bidimensional e assim por diante. Em JavaScript, use @param values {number[]} para matrizes unidimensionais, @param <name> {number[][]} para matrizes bidimensionais e assim por diante para mais dimensões.

Para metadados JSON criados manualmente, verifique se o parâmetro é especificado como "repeating": true e "dimensionality": "matrix" em seu arquivo JSON.

Parâmetro de invocação

Cada função personalizada recebe automaticamente um invocation argumento como o último parâmetro de entrada, mesmo que ele não seja declarado explicitamente. Esse invocation parâmetro corresponde ao objeto Invocation . 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.

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 address 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 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 de parâmetro retornado será Prices!F6.

O invocation parâmetro também pode ser usado para enviar informações ao Excel. Consulte Criar 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 personalizado. 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 do 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 alguma propriedade relacionada que possa ser relevante para cálculos subsequentes.

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, em seguida, 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 chamando 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 despejados em várias células, descendo verticalmente da célula que invocou a função.

Próximas etapas

Saiba como usar valores voláteis em suas funções personalizadas.

Confira também

• Receber e tratar dados com funções personalizadas
• Gerar metadados JSON automaticamente para funções personalizadas
• Criar manualmente metadados JSON para funções personalizadas
• Criar funções personalizadas no Excel
• Tutorial de funções personalizadas do Excel