Criar manualmente metadados JSON para funções personalizadas

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/LTSC 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 2021 ou anterior no Windows

Observação

O manifesto unificado do Microsoft 365 não suporta atualmente projetos de funções personalizadas. Tem de utilizar o manifesto apenas de suplemento para projetos de funções personalizadas. Para obter mais informações, veja Manifesto de Suplementos do Office.

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.

Observação

Lembre-se de ligar o seu manifesto ao ficheiro JSON que criar, através da <Resources> secção 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 <Resources> seu ficheiro JSON na secção, 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": "GETPLANETS", 
      "name": "GETPLANETS", 
      "description": "A function that uses the custom enum as a parameter.", 
      "parameters": [ 
        { 
          "name": "value", 
          "type": "string", 
          "customEnumType": "PLANETS" 
        }
      ]
    }
  ],
  "enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
          "name": "Mercury", 
          "value": "mercury", 
          "tooltip": "Mercury is the first planet from the sun." 
        }, 
        { 
          "name": "Venus", 
          "value": "venus", 
          "tooltip": "Venus is the second planet from the sun." 
        }
      ] 
    }
  ]
}

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.

Se a função personalizada utilizar o cellValueTypeparâmetro , a definição allowCustomDataForDataTypeAny não é necessária para aceitar tipos de dados como parâmetros e valores devolvidos.

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. 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.

enumerações

A enums propriedade é uma matriz de objetos de enumeração . A tabela a seguir lista as propriedades de cada objeto.

Dica

Para saber mais sobre como criar enumerações personalizadas para as suas funções personalizadas, consulte Criar enumerações personalizadas para as suas funções personalizadas. Para saber mais sobre a edição de metadados para enumerações personalizadas, veja Editar enumerações personalizadas em metadados JSON.

Propriedade	Tipo de dados	Obrigatório	Descrição
name	string	Sim	Uma breve descrição da constante.
tooltip	string	Não	Informações adicionais sobre a constante que podem ser mostradas como uma descrição nas interfaces de utilizador.
value	string	Sim	O valor da constante.

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 .
capturesCallingObject	Booliano	Não O valor padrão é false.	Se true, o tipo de dados que está a ser referenciado pela função personalizada é transmitido como o primeiro argumento para a função personalizada. Para obter mais informações, veja Referenciar o valor da entidade como um objeto de chamada.
excludeFromAutoComplete	Booliano	Não O valor padrão é false.	Se true, a função personalizada não aparecerá no menu conclusão automática de fórmulas no Excel. Para obter mais informações, veja Excluir funções personalizadas da IU do Excel. Uma função não pode ter as excludeFromAutoComplete propriedades e linkedEntityLoadService definidas como true.
linkedEntityLoadService	Booliano	Não O valor padrão é false.	Se true, a função personalizada fornece um serviço de carga que devolve valores de células de entidade ligadas atualizados para quaisquer IDs de entidade ligados pedidos pelo Excel. Uma função não pode ter as excludeFromAutoComplete propriedades e linkedEntityLoadService definidas como true. Para obter mais informações, veja Função do serviço de carregamento de entidades ligadas.
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.
requiresStreamAddress	Booliano	Não O valor padrão é false.	Se true, a função pode aceder ao endereço da célula que chama a função de transmissão em fluxo. A address propriedade do parâmetro de invocação contém o endereço da célula que invocou a função de transmissão em fluxo. A função também tem de ter stream definido como true.
requiresStreamParameterAddresses	Booliano	Não O valor padrão é false.	Se true, a função pode aceder aos endereços dos parâmetros da célula que chama a função de transmissão em fluxo. A parameterAddresses propriedade do parâmetro de invocação contém os endereços de parâmetro para a função de transmissão em fluxo. A função também tem de ter stream definido como true.
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.
cellValueType	string	Não	Um subcampo da type propriedade. Especifica os tipos de dados do Excel aceites pela função personalizada. Aceita os valores não sensíveis a maiúsculas e minúsculas cellvalue, booleancellvalue, doublecellvalue, entitycellvalue, errorcellvaluelinkedentitycellvalue, localimagecellvaluee stringcellvalue.webimagecellvalue O type campo tem de ter o valor any para utilizar o subcampo cellValueType .
customEnumType	string	Não	O id da enumeração na enums matriz. Isto associa a enumeração personalizada à função e permite que o Excel apresente os membros da enumeração no menu conclusão automática de fórmulas.
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 todos os parâmetros de repetição são considerados parâmetros opcionais por definição.

Dica

Veja o fragmento de código seguinte para obter um exemplo de como formatar o cellValueType parâmetro nos metadados JSON.

"parameters": [
    {
        "name": "range",
        "description": "the input range",
        "type": "any",
            "cellValueType": "webimagecellvalue"
    }
]

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 nomes de funções a 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",
      ...
    }
  ]
}

Editar enumerações personalizadas em metadados JSON

Crie ou edite metadados de enumeração diretamente com a enums propriedade . Cada enumeração personalizada tem de ter um valor de ID exclusivo e um valor de tipo de string ou number. As enumerações de tipo misto não são suportadas.

Se criar manualmente os metadados JSON para a sua enumeração personalizada, pode associar essas enumerações a funções personalizadas TypeScript ou JavaScript. Para saber mais sobre como criar enumerações personalizadas, veja Criar enumerações personalizadas para as suas funções personalizadas.

O fragmento JSON seguinte mostra os metadados de duas enumerações: uma PLANETS enumeração que contém os planetas Mercúrio e Vénus, e uma DAYS enumeração que inclui os dias de segunda e terça-feira.

"enums": [ 
  { 
    "id": "PLANETS", 
    "type": "string", 
    "values": [ 
      { 
        "name": "Mercury", 
        "value": "mercury", 
        "tooltip": "Mercury is the first planet from the sun." 
      }, 
      { 
        "name": "Venus", 
        "value": "venus", 
        "tooltip": "Venus is the second planet from the sun." 
      }
    ] 
  },
  {
    "id": "DAYS", 
    "type": "number", 
    "values": [ 
      { 
        "name": "Monday",
        "value": 1,
        "tooltip": "Monday is the first working day of a week."
      },
      { 
        "name": "Tuesday",
        "value": 2,
        "tooltip": "Tuesday is the second working day of a week."
      }
    ] 
  }
]

Cada constante na values matriz da enumeração é um objeto com as seguintes propriedades.

• valor: o valor da constante.
• name: uma breve descrição da constante.
• descrição (Opcional): informações adicionais sobre a constante que podem ser mostradas como uma descrição nas interfaces de utilizador.

Para associar a enumeração personalizada a uma função, adicione a propriedade customEnumType ao parameters objeto. O customEnumType valor deve corresponder ao id da enumeração. Tenha em atenção que o customEnumType valor não é sensível a maiúsculas e minúsculas. O fragmento JSON seguinte mostra um functions objeto associado à enumeração PLANETS .

"functions": [ 
  {
    "description": "A function that uses the custom enum as a parameter.", 
    "id": "GETPLANETS", 
    "name": "GETPLANETS", 
    "parameters": [ 
      { 
        "name": "value", 
        "type": "string", 
        "customEnumType": "PLANETS" 
      }
    ], 
    "result": {} 
  } 
]

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

• Gerar metadados JSON automaticamente para funções personalizadas
• Opções de parâmetros de funções personalizadas
• Criar funções personalizadas no Excel