Partilhar via

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 utiliza estas etiquetas JSDoc para criar automaticamente o ficheiro de metadados JSON no momento da criação. Utilizar o plug-in poupa-lhe o esforço de editar manualmente o ficheiro 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
    • revenda perpétua do Office 2016 e posterior
    • Office 2021 perpétuo licenciado em volume e posterior
  • 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

CustomFunctionsMetadataPlugin

O plug-in é CustomFunctionsMetadataPlugin. Para instalá-lo e configurá-lo, utilize os seguintes passos.

Observação

  1. Abra uma Linha de Comandos ou shell de bash e, na raiz do projeto, execute npm install custom-functions-metadata-plugin.

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

  3. Desloque-se para baixo até à plugins matriz e adicione o seguinte à parte superior da matriz. Altere o caminho e o input nome do ficheiro conforme necessário para corresponder ao projeto, mas o output valor tem de ser "functions.json". Se estiver a utilizar o TypeScript, utilize o *.ts nome do ficheiro de origem e não o ficheiro *.js transpiado.

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

Vários ficheiros de origem de função personalizada

Se, e apenas se tiver organizado as suas funções personalizadas em múltiplos ficheiros de origem, existem passos adicionais.

  1. No ficheiro webpack.config.js, substitua o valor da cadeia de carateres de input por uma matriz de URLs de cadeia que apontem para cada um dos ficheiros. O que se segue é um exemplo:

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

  2. Desloque-se para a entry.functions propriedade e substitua o respetivo valor pela mesma matriz que utilizou no passo 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

Não tem de fazer nada para executar a ferramenta. Quando o Webpack é executado, cria o ficheiro functions.json e coloca-o na memória no modo de desenvolvimento ou na pasta /dist no modo de produção.

Noções básicas das etiquetas 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 seguinte, a expressão "Calcula o volume de uma esfera" é a descrição da função personalizada.

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

Etiquetas JSDoc suportadas

As seguintes etiquetas JSDoc são suportadas 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: @customfunctionnomedo ID

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

Segue-se um exemplo desta etiqueta.

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

id

O 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 carateres permitidos estão limitados a: A-Z, a-z, 0-9, carateres de sublinhado (_) e ponto final (.).

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.
  • Carateres permitidos: Letras Carateres alfabéticos Unicode, números, ponto final (.) e caráter de 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

É apresentada uma descrição aos utilizadores no Excel à medida que entram na 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 seguinte, 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: @paramdescrição do nome {type}

  • {type} especifica as informações de tipo dentro de chavetas. Confira a seção Tipos para mais informações sobre os tipos que podem ser usados. Se não for especificado nenhum tipo, será utilizado o tipo any predefinido.
  • name especifica o parâmetro a que a @param etiqueta se aplica. É necessário.
  • 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 personalizada como opcional, coloque parênteses retos à volta 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 seguinte 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 a que a @param etiqueta se aplica. É necessário.
  • 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 da função tem de ser do tipo CustomFunctions.Invocation ou de um tipo derivado para utilizar @requiresAddress. Quando a função é chamada, a propriedade address conterá o endereço.

O exemplo seguinte mostra como utilizar o invocation parâmetro em combinação com @requiresAddress para devolver o endereço da célula que invocou a função personalizada. Veja Parâmetro de 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 devolver os endereços dos parâmetros de entrada.

O último parâmetro da função tem de ser do tipo CustomFunctions.Invocation ou de um tipo derivado para utilizar @requiresParameterAddresses. O comentário JSDoc também tem de incluir uma @returns etiqueta que especifique que o valor devolvido é uma matriz, como @returns {string[][]} ou @returns {number[][]}. Veja Tipos de matriz para obter informações adicionais.

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

O exemplo seguinte mostra como utilizar o invocation parâmetro em combinação com @requiresParameterAddresses para devolver os endereços de três parâmetros de entrada. Veja Detetar 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 devolve void.

As funções de transmissão em fluxo não devolvem valores diretamente, pelo que chamam setResult(result: ResultType) com 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.

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 devolver uma promessa que fornece o valor quando a promessa é resolvida. Se a promessa for rejeitada, a função personalizada emitirá 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