Partilhar via

Criar manualmente metadados JSON para funções personalizadas

  • Artigo

Conforme descrito no artigo de descrição geral das funções personalizadas , um projeto de funções personalizadas tem de incluir um ficheiro de metadados JSON e um ficheiro de script (JavaScript ou TypeScript) para registar uma função, disponibilizando-a para utilização. As funções personalizadas são registadas quando o utilizador executa o suplemento pela primeira vez e depois estão disponíveis para o mesmo utilizador em todos os livros.

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

Recomendamos que utilize a autogeração JSON sempre que possível, em vez de criar o seu próprio ficheiro JSON. A autogeneração é menos propensa a erros do utilizador e os yo office ficheiros estruturados já o incluem. Para obter mais informações sobre as etiquetas JSDoc e o processo de autogeração JSON, veja Autogenerate JSON metadata for custom functions (Gerar automaticamente metadados JSON para funções personalizadas).

No entanto, pode criar um projeto de funções personalizadas do zero. Este processo requer que:

  • Escreva o seu ficheiro JSON.
  • Verifique se o ficheiro de manifesto está ligado ao ficheiro JSON.
  • Associe id as suas funções e name propriedades ao ficheiro de script para registar as suas funções.

A imagem seguinte explica as diferenças entre utilizar yo office ficheiros de estrutura e escrever JSON de raiz.

Imagem das diferenças entre utilizar o gerador Yeoman para Suplementos do Office e escrever o seu próprio JSON.

Observação

Lembre-se de ligar o seu manifesto ao ficheiro JSON que criar, através da <secção Recursos> no seu ficheiro de manifesto apenas de suplemento se não utilizar o gerador Yeoman para Suplementos do Office.

Criar metadados e ligar ao manifesto

Crie um ficheiro JSON no seu projeto e forneça todos os detalhes sobre as suas funções no mesmo, como os parâmetros da função. Veja o seguinte exemplo de metadados e a referência de metadados para obter uma lista completa das propriedades da função.

Certifique-se de que o ficheiro de manifesto apenas do suplemento referencia o <seu ficheiro JSON na secção Recursos> , semelhante ao exemplo seguinte.

<Resources>
    <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
            <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/index.html"/>
    </bt:Urls>
    <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
    </bt:ShortStrings>
</Resources>

Exemplo de metadados JSON

O exemplo a seguir mostra o conteúdo de um arquivo de metadados JSON para um suplemento que define funções personalizadas. As seções que seguem este exemplo fornecem informações detalhadas sobre as propriedades individuais neste exemplo de JSON.

{
  "allowCustomDataForDataTypeAny": true,
  "allowErrorForDataTypeAny": true,
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "type": "number",
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "first",
          "description": "first number to add",
          "type": "number",
          "dimensionality": "scalar"
        },
        {
          "name": "second",
          "description": "second number to add",
          "type": "number",
          "dimensionality": "scalar"
        }
      ]
    },
    {
      "id": "GETDAY",
      "name": "GETDAY",
      "description": "Get the day of the week",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": []
    },
    {
      "id": "INCREMENTVALUE",
      "name": "INCREMENTVALUE",
      "description": "Count up from zero",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "increment",
          "description": "the number to be added each time",
          "type": "number",
          "dimensionality": "scalar"
        }
      ],
      "options": {
        "stream": true,
        "cancelable": true
      }
    },
    {
      "id": "SECONDHIGHEST",
      "name": "SECONDHIGHEST",
      "description": "Get the second highest number from a range",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "range",
          "description": "the input range",
          "type": "number",
          "dimensionality": "matrix"
        }
      ]
    }
  ]
}

Observação

Está disponível um ficheiro JSON de exemplo completo no histórico de consolidações do repositório do GitHub OfficeDev/Excel-Custom-Functions . Uma vez que o projeto foi ajustado para gerar automaticamente JSON, uma amostra completa do JSON manuscrito só está disponível em versões anteriores do projeto.

Referência de metadados

allowCustomDataForDataTypeAny

A allowCustomDataForDataTypeAny propriedade é um tipo de dados booleano. Definir este valor como permite que true uma função personalizada aceite tipos de dados como parâmetros e valores devolvidos. Para saber mais, veja Funções personalizadas e tipos de dados.

Observação

Ao contrário da maioria das outras propriedades de metadados JSON, allowCustomDataForDataTypeAny é uma propriedade de nível superior e não contém subpropriedades. Veja o exemplo de código de metadados JSON anterior para obter um exemplo de como formatar esta propriedade.

allowErrorForDataTypeAny

A allowErrorForDataTypeAny propriedade é um tipo de dados booleano. Definir o valor como true permite que uma função personalizada processe erros como valores de entrada. Todos os parâmetros com o tipo any ou any[][] podem aceitar erros como valores de entrada quando allowErrorForDataTypeAny está definido como true. O valor predefinido allowErrorForDataTypeAny é false.

Observação

Ao contrário das outras propriedades de metadados JSON, allowErrorForDataTypeAny é uma propriedade de nível superior e não contém subpropriedades. Veja o exemplo de código de metadados JSON anterior para obter um exemplo de como formatar esta propriedade.

funções

A propriedade functions é um conjunto de objetos de funções personalizadas. A tabela a seguir lista as propriedades de cada objeto.

Propriedade Tipo de dados Obrigatório Descrição
description string Não Descrição da função que é exibida aos usuários finais no Excel. Por exemplo, Converte um valor em Celsius para Fahrenheit.
helpUrl string Não A URL que fornece informações sobre a função. (Ela é exibida em um painel de tarefas). Por exemplo, http://contoso.com/help/convertcelsiustofahrenheit.html.
id string Sim Identificação exclusiva para a função. Essa ID pode conter apenas caracteres alfanuméricos e pontos e não deve ser alterada depois de configurada.
name string Sim O nome da função que é exibida aos usuários finais no Excel. No Excel, este nome de função tem o prefixo do espaço de nomes das funções personalizadas especificado no ficheiro de manifesto apenas do suplemento.
options objeto Não Permite que você personalize alguns aspectos de como e quando o Excel executa a função. Confira opções para obter detalhes.
parameters array Sim Matriz que define os parâmetros de entrada para a função. Veja os parâmetros para obter detalhes.
result objeto Sim Objeto que define o tipo de informação que é retornada pela função do Excel. Confira resultado para obter detalhes.

options

O objeto options permite que você personalize alguns aspectos de como e quando o Excel executa a função. A tabela a seguir lista as propriedades do objeto options.

Propriedade Tipo de dados Obrigatório Descrição
cancelable booliano Não

O valor padrão é false.		 Se o valor for true, o Excel chamará o manipulador CancelableInvocation sempre que o usuário realizar uma ação que tenha o efeito de cancelar a função, por exemplo, manualmente acionar um recálculo ou editar uma célula referenciada pela função. Normalmente, as funções canceláveis são utilizadas apenas para funções assíncronas que devolvem um único resultado e precisam de processar o cancelamento de um pedido de dados. Uma função não pode utilizar as stream propriedades e cancelable .
requiresAddress booliano Não

O valor padrão é false.		 Se true, a função personalizada pode aceder ao endereço da célula que a invocou. A address propriedade do parâmetro de invocação contém o endereço da célula que invocou a função personalizada. Uma função não pode utilizar as stream propriedades e requiresAddress .
requiresParameterAddresses booliano Não

O valor padrão é false.		 Se true, a função personalizada pode aceder aos endereços dos parâmetros de entrada da função. Esta propriedade tem de ser utilizada em combinação com a dimensionality propriedade do objeto de resultado e dimensionality tem de ser definida como matrix. Veja Detetar o endereço de um parâmetro para obter mais informações.
stream booliano Não

O valor padrão é false.		 Se o valor for true, a função poderá gerar uma saída para a célula de forma repetida, mesmo quando invocada somente uma vez. Essa opção é útil para fontes de dados que mudam constantemente, como preços de ações. A função não deve ter instruções return. Em vez disso, o valor do resultado é transmitido como o argumento da função de chamada de StreamingInvocation.setResult retorno. Para obter mais informações, veja Criar uma função de transmissão em fluxo.
volatile booliano Não

O valor padrão é false.		 Se true, a função recalcula cada vez que o Excel volta a calcular, em vez de apenas quando os valores dependentes da fórmula forem alterados. Uma função não pode utilizar as stream propriedades e volatile . Se as stream propriedades e volatile estiverem ambas definidas como true, a propriedade volátil será ignorada.

parâmetros

A propriedade parameters é uma matriz de objetos de parâmetro. A tabela a seguir lista as propriedades de cada objeto.

Propriedade Tipo de dados Obrigatório Descrição
description string Não Uma descrição do parâmetro. Isto é apresentado no IntelliSense do Excel.
dimensionality string Não Tem de ser scalar (um valor não-matriz) ou matrix (uma matriz bidimensional).
name string Sim O nome do parâmetro. Este nome é apresentado no IntelliSense do Excel.
type string Não O tipo de dados do parâmetro. Pode ser boolean, number, stringou any, o que lhe permite utilizar qualquer um dos três tipos anteriores. Se esta propriedade não for especificada, o tipo de dados é predefinido como any.
optional booliano Não Se for true, o parâmetro será opcional.
repeating booliano Não Se true, os parâmetros são preenchidos a partir de uma matriz especificada. Tenha em atenção que todas as funções que repetem parâmetros são consideradas parâmetros opcionais por definição.

resultado

O objeto result que define o tipo de informação que é retornado pela função. A tabela a seguir lista as propriedades do objeto result.

Propriedade Tipo de dados Obrigatório Descrição
dimensionality string Não Tem de ser scalar (um valor não-matriz) ou matrix (uma matriz bidimensional).
type string Não O tipo de dados do resultado. Pode ser boolean, number, stringou any (o que lhe permite utilizar qualquer um dos três tipos anteriores). Se esta propriedade não for especificada, o tipo de dados é predefinido como any.

Associar os nomes de função com metadados JSON

Para que uma função funcione corretamente, tem de associar a propriedade da id função à implementação javaScript. Certifique-se de que existe uma associação. Caso contrário, a função não será registada e não será utilizável no Excel. O seguinte exemplo de código mostra como fazer a associação com a CustomFunctions.associate() função . A amostra define a função personalizada add e associa com o objeto no arquivo de metadados JSON onde o valor da id propriedade é adicionar.

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

CustomFunctions.associate("ADD", add);

O JSON seguinte mostra os metadados JSON que estão associados ao código JavaScript da função personalizada anterior.

{
  "functions": [
    {
      "description": "Add two numbers",
      "id": "ADD",
      "name": "ADD",
      "parameters": [
        {
          "description": "First number",
          "name": "first",
          "type": "number"
        },
        {
          "description": "Second number",
          "name": "second",
          "type": "number"
        }
      ],
      "result": {
        "type": "number"
      }
    }
  ]
}

Lembre-se das seguintes práticas recomendadas quando criar funções personalizadas no arquivo JavaScript e especificar as informações correspondentes no arquivo de metadados JSON.

  • No arquivo de metadados JSON, verifique se o valor de cada propriedade id contém apenas caracteres alfanuméricos e pontos.

  • No arquivo de metadados JSON, garanta que o valor de cada propriedade id seja exclusivo dentro do escopo do arquivo. Ou seja, nenhum objeto de duas funções no arquivo de metadados deve ter o mesmo valor id.

  • Não altere o valor de uma propriedade id no arquivo de metadados JSON, depois de mapeá-lo para um nome de função JavaScript correspondente. Para alterar o nome da função que os usuários finais visualizam no Excel, atualize a propriedade name no arquivo de metadados JSON. No entanto, nunca altere o valor de uma propriedade id depois de estabelecida.

  • No ficheiro JavaScript, especifique uma associação de função personalizada utilizando CustomFunctions.associate depois de cada função.

O exemplo seguinte mostra os metadados JSON que correspondem às funções definidas no exemplo de código JavaScript anterior. Os id valores de propriedade e name estão em maiúsculas, o que é uma melhor prática ao descrever as suas funções personalizadas. Só tem de adicionar este JSON se estiver a preparar manualmente o seu próprio ficheiro JSON e não estiver a utilizar agerição automática. Para obter mais informações sobre a autogeração, veja Autogenerate JSON metadata for custom functions (Gerar automaticamente metadados JSON para funções personalizadas).

{
  "$schema": "https://developer.microsoft.com/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      ...
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      ...
    }
  ]
}

Próximas etapas

Aprenda as melhores práticas para atribuir um nome à sua função ou descubra como localizar a função com o método JSON manuscrito descrito anteriormente.

Confira também