Criar manualmente metadados JSON para funções personalizadas

Conforme descrito no artigo de visão geral de funções personalizadas , um projeto de funções personalizadas deve incluir um arquivo de metadados JSON e um arquivo de script (JavaScript ou TypeScript) para registrar uma função, disponibilizando-a para uso. As funções personalizadas são registradas quando o usuário executa o suplemento pela primeira vez e, posteriormente, estão disponíveis para o mesmo usuário em todas as pastas de trabalho.

É recomendável usar a geração automática JSON quando possível, em vez de criar seu próprio arquivo JSON. A geração automática é menos propensa a erros do usuário e os yo office arquivos scaffolded já incluem isso. Para obter mais informações sobre tags JSDoc e o processo de geração automática de JSON, consulte Gerar metadados JSON automaticamente para funções personalizadas.

No entanto, você pode criar um projeto de funções personalizadas do zero. Esse processo exige que você:

  • Grave o arquivo JSON.
  • Verifique se o arquivo de manifesto está conectado ao arquivo JSON.
  • Associe suas funções id e name propriedades no arquivo de script para registrar suas funções.

A imagem a seguir explica as diferenças entre o uso yo office de arquivos scaffold e a gravação JSON do zero.

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

Observação

Lembre-se de conectar seu manifesto ao arquivo JSON que você criar. No manifesto unificado, use a customFunctions.metadataUrl propriedade. No manifesto somente do suplemento, use a <Resources> seção. Se você usar o gerador Yeoman para Suplementos do Office, essa conexão será configurada automaticamente.

Criação de metadados e conexão com o manifesto

Crie um arquivo JSON em seu projeto e forneça todos os detalhes sobre suas funções nele, como os parâmetros da função. Consulte o exemplo de metadados a seguir e a referência de metadados para obter uma lista completa de propriedades de função.

A maneira como você conecta o arquivo de manifesto ao arquivo de metadados JSON depende do tipo de manifesto que você está usando.

No manifesto unificado, faça referência ao arquivo de metadados JSON usando a customFunctions.metadataUrl propriedade dentro da extensions matriz:

{
  "extensions": [
    {
      "requirements": {
        "scopes": ["workbook"],
        "capabilities": [
          {
            "name": "CustomFunctionsRuntime",
            "minVersion": "1.1"
          }
        ]
      },
      "customFunctions": {
        "namespace": {
          "id": "CONTOSO",
          "name": "CONTOSO"
        },
        "metadataUrl": "https://subdomain.contoso.com/config/customfunctions.json"
      }
    }
  ]
}

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": "planetName", 
          "type": "string", 
          "customEnumId": "PLANETS" 
        }
      ]
    }
  ],
  "enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
          "name": "Mercury", 
          "stringValue": "mercury", 
          "tooltip": "Mercury is the first planet from the sun." 
        }, 
        { 
          "name": "Venus", 
          "stringValue": "venus", 
          "tooltip": "Venus is the second planet from the sun." 
        }
      ] 
    }
  ]
}

Observação

Um arquivo JSON de exemplo completo está disponível no OfficeDev/Excel-Custom-Functions histórico de confirmações do repositório GitHub. Como o projeto foi ajustado para gerar JSON automaticamente, uma amostra completa de JSON manuscrito só está disponível em versões anteriores do projeto.

Referência de metadados

allowCustomDataForDataTypeAny

A allowCustomDataForDataTypeAny propriedade é um tipo de dados booliano. Definir esse valor como true permite que uma função personalizada aceite tipos de dados como parâmetros e retorne valores. Para saber mais, consulte Funções e tipos de dados personalizados.

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. Consulte o exemplo de código de metadados JSON anterior para obter um exemplo de como formatar essa propriedade.

Se a função personalizada usar o cellValueTypeparâmetro, a configuração allowCustomDataForDataTypeAny do não será necessária para aceitar tipos de dados como parâmetros e retornar valores.

allowErrorForDataTypeAny

A allowErrorForDataTypeAny propriedade é um tipo de dados booliano. 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 é definido como true. O valor padrão 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. Consulte o exemplo de código de metadados JSON anterior para obter um exemplo de como formatar essa 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, esse nome de função é prefixado pelo namespace de funções personalizadas especificado no arquivo de manifesto somente 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. Consulte 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 suas funções personalizadas, consulte Criar enumerações personalizadas para suas funções personalizadas. Para saber mais sobre a edição de metadados para enumerações personalizadas, consulte 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 dica de ferramenta nas interfaces do usuário.
numberValue number Condicional O valor número da constante. Se a enumeração type for number, esse campo será obrigatório.
stringValue string Condicional O valor da cadeia de caracteres da constante. Se a enumeração type for string, esse campo será obrigatório.

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. As funções canceláveis normalmente são usadas apenas para funções assíncronas que retornam um único resultado e precisam lidar com o cancelamento de uma solicitação de dados. Uma função não pode usar as stream propriedades and cancelable .
capturesCallingObject Booliano Não

O valor padrão é false.		 Se true, o tipo de dados que está sendo referenciado pela função personalizada será passado como o primeiro argumento para a função personalizada. Para obter mais informações, consulte 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 Preenchimento Automático de fórmulas no Excel. Para obter mais informações, consulte Excluir funções personalizadas da interface do usuário do Excel. Uma função não pode ter as excludeFromAutoComplete propriedades and linkedEntityLoadService definidas como true.
linkedEntityLoadService Booliano Não

O valor padrão é false.		 Se true, a função personalizada fornece um serviço de carregamento que retorna valores atualizados de células de entidades vinculadas para quaisquer IDs de entidades vinculadas solicitadas pelo Excel. Uma função não pode ter as excludeFromAutoComplete propriedades and linkedEntityLoadService definidas como true. Para obter mais informações, consulte Função de serviço de carregamento de entidade vinculada.
requiresAddress Booliano Não

O valor padrão é false.		 Se true, sua função personalizada poderá acessar o 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 sua função personalizada. Uma função não pode usar as stream propriedades and requiresAddress .
requiresParameterAddresses Booliano Não

O valor padrão é false.		 Se true, a função personalizada poderá acessar os endereços dos parâmetros de entrada da função. Essa propriedade deve ser usada em combinação com a dimensionality propriedade do objeto de resultado e dimensionality deve ser definida como matrix. Consulte Detectar 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 acessar o endereço da célula que está chamando a função de streaming. A address propriedade do parâmetro de invocação contém o endereço da célula que invocou sua função de streaming. A função também deve ter stream sido definida como true.
requiresStreamParameterAddresses Booliano Não

O valor padrão é false.		 Se true, a função poderá acessar os endereços de parâmetro da célula que chama a função de streaming. A parameterAddresses propriedade do parâmetro de invocação contém os endereços de parâmetro para sua função de streaming. A função também deve ter stream sido definida 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 é passado como o argumento da função de retorno de StreamingInvocation.setResult chamada. Para obter mais informações, consulte Criar uma função de streaming.
supportSync (visualização) Booliano Não

O valor padrão é false.		 Se true, a função dá suporte a processos síncronos no Excel. Uma função só pode usar uma das três seguintes propriedades: stream, supportSync ou volatile. If supportSync é combinado com stream ou volatile, supportSync é ignorado. Para obter mais informações, consulte Funções personalizadas síncronas. Observação: essa propriedade está em versão prévia e não deve ser usada em um suplemento de produção.
volatile Booliano Não

O valor padrão é false.		 Se true, a função será recalculada sempre que o Excel for recalculado, em vez de apenas quando os valores dependentes da fórmula forem alterados. Uma função volátil não pode usar a stream propriedade. Se as stream propriedades and volatile estiverem definidas como true, a propriedade volatile 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. Isso é exibido no IntelliSense do Excel.
dimensionality string Não Deve ser ( scalar um valor de não matriz) ou matrix (uma matriz bidimensional).
name string Sim O nome do parâmetro. Esse nome é exibido no IntelliSense do Excel.
type string Não O tipo de dados do parâmetro. Pode ser boolean, number, string, ou any, o que permite o uso de qualquer um dos três tipos anteriores. Se essa propriedade não for especificada, o tipo de dados será padronizado para any.
cellValueType string Não Um subcampo da type propriedade. Especifica os tipos de dados do Excel aceitos pela função personalizada. Aceita os valores que não diferenciam maiúsculas de minúsculas cellvalue, booleancellvalue, doublecellvalue, entitycellvalue, localimagecellvaluestringcellvalueerrorcellvaluelinkedentitycellvaluee .webimagecellvalue

O type campo deve ter o valor any para usar o cellValueType subcampo.
customEnumId string Não A id enumeração enums na matriz. Isso associa a enumeração personalizada à função e permite que o Excel exiba os membros de enumeração no menu de Preenchimento Automático 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 de uma matriz especificada. Observe que todos os parâmetros repetidos são considerados parâmetros opcionais por definição.

Dica

Consulte o snippet de código a seguir para obter um exemplo de como formatar o cellValueType parâmetro em 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 Deve ser ( scalar um valor de 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 permite o uso de qualquer um dos três tipos anteriores). Se essa propriedade não for especificada, o tipo de dados será padronizado para any.

Associar nomes de função a metadados JSON

Para que uma função funcione corretamente, você precisa associar a propriedade da id função à implementação do JavaScript. Verifique se há uma associação, caso contrário, a função não será registrada e não poderá ser usada no Excel. O exemplo de código a seguir mostra como fazer a associação usando 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 a seguir mostra os metadados JSON 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 arquivo JavaScript, especifique uma associação de função personalizada usando CustomFunctions.associate após cada função.

O exemplo a seguir mostra os metadados JSON que correspondem às funções definidas no exemplo de código JavaScript anterior. Os id valores de propriedade and name estão em maiúsculas, o que é uma prática recomendada ao descrever suas funções personalizadas. Você só precisará adicionar esse JSON se estiver preparando seu próprio arquivo JSON manualmente e não usando a geração automática. Para obter mais informações sobre a geração automática, consulte Gerar metadados JSON automaticamente 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 deve ter um valor de ID exclusivo e um valor de tipo de um string ou number. Não há suporte para enumerações de tipo misto.

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

O snippet JSON a seguir mostra os metadados para 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-feira e terça-feira.

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

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

  • stringValue ou numberValue: a cadeia de caracteres ou o valor numérico da constante. Se o tipo de enumeração for number, então numberValue é necessário. Se o tipo de enumeração for string, então stringValue é necessário.
  • name: Uma breve descrição da constante.
  • Dica de ferramenta (opcional): Informações adicionais sobre a constante que podem ser mostradas como uma dica de ferramenta nas interfaces do usuário.

Para associar a enumeração personalizada a uma função, adicione a propriedade customEnumId ao parameters objeto. O customEnumId valor deve corresponder ao id da enumeração. Observe que o valor não diferencia customEnumId maiúsculas de minúsculas. O snippet JSON a seguir mostra um functions objeto associado à PLANETS enumeração.

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

Próximas etapas

Conheça as práticas recomendadas para nomear sua função ou descubra como localizar sua função usando o método JSON manuscrito descrito anteriormente.

Confira também

  • Last updated on