Gerar metadados JSON automaticamente para funções personalizadas

  • Artigo

Quando uma função personalizada do Excel é gravada em JavaScript ou em TypeScript, as marcações JSDoc são usadas para fornecer informações adicionais sobre a função personalizada. Fornecemos um plug-in Webpack que usa essas marcas JSDoc para criar automaticamente o arquivo de metadados JSON no momento do build. O uso do plug-in salva você do esforço de editar manualmente o arquivo de metadados JSON.

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

CustomFunctionsMetadataPlugin

O plug-in é CustomFunctionsMetadataPlugin. Para instalá-lo e configurá-lo, use as etapas a seguir.

Observação

  1. Abra um Prompt de Comando ou um shell bash e, na raiz do projeto, execute npm install custom-functions-metadata-plugin.

  2. Abra o arquivo webpack.config.js e adicione a seguinte linha na parte superior: const CustomFunctionsMetadataPlugin = require("custom-functions-metadata-plugin");.

  3. Role para baixo até a plugins matriz e adicione o seguinte à parte superior da matriz. Altere o caminho e o input nome do arquivo conforme necessário para corresponder ao seu projeto, mas o output valor deve ser "functions.json". Se você estiver usando TypeScript, use o nome do arquivo de origem *.ts, não o arquivo *.js transpilado.

    new CustomFunctionsMetadataPlugin({
   output: "functions.json",
   input: "./src/functions/functions.js", 
}),

Vários arquivos de origem de função personalizados

Se e somente se você tiver organizado suas funções personalizadas em vários arquivos de origem, haverá etapas adicionais.

  1. No arquivo webpack.config.js, substitua o valor da cadeia de input caracteres por uma matriz de URLs de cadeia de caracteres que apontam para cada um dos arquivos. O que se segue é um exemplo:

    new CustomFunctionsMetadataPlugin({
   output: "functions.json",
   input: [
            "./src/functions/someFunctions.js", 
            "./src/functions/otherFunctions.js"
          ], 
}),

  2. Role até a entry.functions propriedade e substitua seu valor pela mesma matriz usada na etapa anterior. O que se segue é um exemplo:

    entry: {
   polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
   taskpane: ["./src/taskpane/taskpane.js", "./src/taskpane/taskpane.html"],
   functions: [
            "./src/functions/someFunctions.js", 
            "./src/functions/otherFunctions.js"
          ],
 },

Executar a ferramenta

Você não precisa fazer nada para executar a ferramenta. Quando o Webpack é executado, ele cria o arquivo functions.json e o coloca na memória no modo de desenvolvimento ou na pasta /dist no modo de produção.

Noções básicas de marcas JSDoc

Adicione a marcação @customfunction nos comentários de código de uma função JavaScript ou TypeScript para marcá-la como uma função personalizada.

Os tipos de parâmetros da função podem ser fornecidos usando a marcação @param em JavaScript ou do Tipo de função em TypeScript. Para saber mais, confira a marcação @param e as seções Tipos.

Adicionar uma descrição a uma função

A descrição é exibida para o usuário como texto de ajuda quando eles precisam de ajuda para entender o que a função personalizada executa. A descrição não requer nenhuma tag específica. Basta digitar uma breve descrição de texto no comentário JSDoc. Em geral, a descrição é colocada no início da seção de comentários do JSDoc, mas funcionará independentemente de onde seja colocada.

Para ver exemplos das descrições de funções internas, abra o Excel, vá para a guia Fórmulas e escolha Inserir função. Você pode navegar por todas as descrições de funções e também ver suas próprias funções personalizadas listadas.

No exemplo a seguir, a frase "Calcula o volume de uma esfera" é a descrição da função personalizada.

/**
/* Calculates the volume of a sphere.
/* @customfunction VOLUME
...
 */

Marcas JSDoc com suporte

As marcas JSDoc a seguir têm suporte em funções personalizadas do Excel.

@cancelable

Indica que uma função personalizada executa uma ação quando a função é cancelada.

O último parâmetro da função deve ser do tipo CustomFunctions.CancelableInvocation. A função pode atribuir uma função à oncanceled propriedade para denotar o resultado quando a função é cancelada.

Se o último parâmetro da função for do tipo CustomFunctions.CancelableInvocation, ela será considerada @cancelable, mesmo se a tag não estiver presente.

Uma função não pode ter as tags @cancelable e @streaming ao mesmo tempo.

@customfunction

Sintaxe: @customfunctionnome da id

Essa marca indica que a função JavaScript/TypeScript é uma função personalizada do Excel. É necessário criar metadados para a função personalizada.

O seguinte mostra um exemplo dessa marca.

/**
 * Increments a value once a second.
 * @customfunction
 * ...
 */

id

A id identifica uma função personalizada.

  • Se id não for fornecido, o nome da função JavaScript/TypeScript será convertido em maiúsculas e os caracteres não permitidos serão removidos.
  • O id deve ser exclusivo para todas as funções personalizadas.
  • Os caracteres permitidos são limitados a: A-Z, a-z, 0-9, sublinha (_) e período (.).

No exemplo a seguir, incremento é o id e o name da função.

/**
 * Increments a value once a second.
 * @customfunction INCREMENT
 * ...
 */

nome

Fornece a exibição name da função personalizada.

  • Se o nome não for fornecido, o id também será usado como nome.
  • Caracteres permitidos: Letras Caractere alfabético Unicode, números, período (.) e sublinhado (_).
  • Deve começar com uma letra.
  • O comprimento máximo é de 128 caracteres.

No exemplo a seguir, Inc é a idda função e increment é o name.

/**
 * Increments a value once a second.
 * @customfunction INC INCREMENT
 * ...
 */

descrição

Uma descrição aparece para os usuários no Excel, pois eles estão inserindo a função e especifica o que a função faz. Uma descrição não exige nenhuma tag específica. Adicione uma descrição a uma função personalizada acrescentando uma frase para descrever o que a função realiza dentro do comentário JSDoc. Por padrão, qualquer texto sem tags na seção de comentários JSDoc será a descrição da função.

No exemplo a seguir, a frase "Uma função que soma dois números" é a descrição da função personalizada com a propriedade id de ADD.

/**
 * A function that adds two numbers.
 * @customfunction ADD
 * ...
 */

@helpurl

Sintaxe: @helpurlurl

A url fornecida é exibida no Excel.

No exemplo a seguir, o helpurl é http://www.contoso.com/weatherhelp.

/**
 * A function which streams the temperature in a town you specify.
 * @customfunction getTemperature
 * @helpurl http://www.contoso.com/weatherhelp
 * ...
 */

@param

JavaScript

Sintaxe javaScript: @param {type} descrição do nome

  • {type} especifica as informações de tipo em chaves encaracoladas. Confira a seção Tipos para mais informações sobre os tipos que podem ser usados. Se nenhum tipo for especificado, o tipo any padrão será usado.
  • name especifica o parâmetro ao qual a @param marca se aplica. Ela é necessária.
  • description fornece a descrição que aparece no Excel para o parâmetro de função. É opcional.

Para denotar um parâmetro de função personalizado como opcional, coloque colchetes em torno do nome do parâmetro. Por exemplo, @param {string} [text] Optional text.

Observação

O valor padrão para parâmetros opcionais é null.

O exemplo a seguir mostra uma função ADD que adiciona dois ou três números, com o terceiro número como um parâmetro opcional.

/**
 * A function which sums two, or optionally three, numbers.
 * @customfunction ADDNUMBERS
 * @param firstNumber {number} First number to add.
 * @param secondNumber {number} Second number to add.
 * @param [thirdNumber] {number} Optional third number you wish to add.
 * ...
 */

TypeScript

Sintaxe TypeScript: @paramdescrição do nome

  • name especifica o parâmetro ao qual a @param marca se aplica. Ela é necessária.
  • description fornece a descrição que aparece no Excel para o parâmetro de função. É opcional.

Confira a seção Tipos para mais informações sobre os tipos de parâmetros de função que podem ser usados.

Para denotar um parâmetro de função personalizado como opcional, siga um destes procedimentos:

  • Use um parâmetro opcional. Por exemplo: function f(text?: string)
  • Dê ao parâmetro um valor padrão. Por exemplo: function f(text: string = "abc")

Para uma descrição detalhada do @param, confira: JSDoc

Observação

O valor padrão para parâmetros opcionais é null.

O exemplo a seguir mostra add a função que adiciona dois números.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number
 * @param second Second number
 * @returns The sum of the two numbers.
 */
function add(first: number, second: number): number {
  return first + second;
}

@requiresAddress

Indica que o endereço da célula onde a função está sendo avaliada deve ser fornecido.

O último parâmetro de função deve ser do tipo CustomFunctions.Invocation ou de um tipo derivado para usar @requiresAddress. Quando a função é chamada, a propriedade address conterá o endereço.

O exemplo a seguir mostra como usar o invocation parâmetro em combinação com @requiresAddress para retornar o endereço da célula que invocou sua função personalizada. Consulte Parâmetro invocação para obter mais informações.

/**
 * 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;
}

@requiresParameterAddresses

Indica que a função deve retornar os endereços dos parâmetros de entrada.

O último parâmetro de função deve ser do tipo CustomFunctions.Invocation ou de um tipo derivado para usar @requiresParameterAddresses. O comentário JSDoc também deve incluir uma @returns marca especificando que o valor retornado seja uma matriz, como @returns {string[][]} ou @returns {number[][]}. Consulte Tipos de matriz para obter informações adicionais.

Quando a função for chamada, a parameterAddresses propriedade conterá os endereços dos parâmetros de entrada.

O exemplo a seguir mostra como usar o invocation parâmetro em combinação com @requiresParameterAddresses para retornar os endereços de três parâmetros de entrada. Consulte Detectar o endereço de um parâmetro para obter mais informações.

/**
 * 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;
}

@returns

Sintaxe: @returns {tipo}

Fornece o tipo para o valor de retorno.

Se {type} for omitido, as informações do tipo TypeScript serão usadas. Se não houver informações de tipo, o tipo será any.

O exemplo a seguir mostra a add função que usa @returns marca.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number
 * @param second Second number
 * @returns The sum of the two numbers.
 */
function add(first: number, second: number): number {
  return first + second;
}

@streaming

Usado para indicar que uma função personalizada é uma função de streaming.

O último parâmetro é do tipo CustomFunctions.StreamingInvocation<ResultType>. A função retorna void.

As funções de streaming não retornam valores diretamente, em vez disso, elas chamam setResult(result: ResultType) usando o último parâmetro.

Exceções lançadas por uma função de streaming são ignoradas. setResult() pode ser chamado com Erro para indicar um resultado de erro. Para obter um exemplo de uma função de streaming e mais informações, confira , criar uma função de streaming.

As funções de streaming não podem ser marcadas como @volatile.

@volatile

Uma função volátil é aquela cujo resultado não é o mesmo de um momento para o outro, mesmo que não receba argumentos ou os argumentos não mudem. O Excel reavalia células que contenham funções voláteis, juntamente com todos os dependentes, sempre que um cálculo é feito. Por esse motivo, confiar demais em funções voláteis pode retardar o tempo de recálculo; portanto, use-as com moderação.

Funções de streaming não podem ser voláteis.

A função a seguir é volátil e usa @volatile a marca.

/**
 * Simulates rolling a 6-sided die.
 * @customfunction
 * @volatile
 */
function roll6sided(): number {
  return Math.floor(Math.random() * 6) + 1;
}

Tipos

Especificando um tipo de parâmetro, o Excel converterá valores nesse tipo antes de chamar a função. Se o tipo for any, nenhuma conversão será executada.

Tipos de valor

Um valor pode ser representado usando um dos seguintes tipos: booleannumberstring.

Tipo de matriz

Use um tipo de matriz bidimensional para que o parâmetro ou valor de retorno seja uma matriz de valores. Por exemplo, o tipo number[][] indica uma matriz de números e string[][] indica uma matriz de cadeias de caracteres.

Tipo de erro

Uma função que não seja de streaming pode indicar um erro retornando um tipo de Erro.

Uma função de streaming pode indicar um erro chamando setResult() com um tipo de erro.

Promessa

Uma função personalizada pode retornar uma promessa que fornece o valor quando a promessa é resolvida. Se a promessa for rejeitada, a função personalizada gerará um erro.

Outros tipos

Qualquer outro tipo será tratado como um erro.

Próximas etapas

Saiba mais sobre nomenclatura e localização para funções personalizadas.

Confira também