Criar metadados JSON manualmente para funções personalizadas

Artigo
03/15/2023

Conforme descrito no artigo 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 depois que estão disponíveis para o mesmo usuário em todas as pastas de trabalho.

Importante

Observe que as funções personalizadas do Excel estão disponíveis nas plataformas a seguir.

Office no Windows
- Assinatura do Microsoft 365
- varejo perpétuo Office 2016 e posterior
Office no Mac
Office na Web

No momento, não há suporte para funções personalizadas do Excel no seguinte:

Office no iPad
versões perpétuas licenciadas por volume do Office 2019 ou anteriores

Recomendamos usar a regeneração automática JSON quando possível, em vez de criar seu próprio arquivo JSON. A regeneraçã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 marcas JSDoc e o processo de regeneração automática JSON, consulte Metadados JSON de autogeneração para funções personalizadas.

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

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

A imagem a seguir explica as diferenças entre usar yo office arquivos scaffold e escrever JSON do zero.

Imagem de 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ê cria, por meio da <seção Recursos> em seu arquivo de manifesto XML se você não usar o gerador Yeoman para suplementos do Office.

Criar metadados e conectar-se ao 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 da função.

Verifique se o arquivo de manifesto XML faz referência ao arquivo JSON na <seção Recursos> , semelhante ao exemplo a seguir.

<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

Um arquivo JSON de exemplo completo está disponível no histórico de confirmação do repositório GitHub do OfficeDev/Excel-Custom-Functions . Como o projeto foi ajustado para gerar JSON automaticamente, um exemplo completo 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 para true permitir que uma função personalizada aceite tipos de dados como parâmetros e retorne valores. Para saber mais, confira 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 sub-propriedades. Consulte o exemplo de código de metadados JSON anterior para obter um exemplo de como formatar essa propriedade.

allowErrorForDataTypeAny

A allowErrorForDataTypeAny propriedade é um tipo de dados booliano. Definir o valor para true permitir 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 são definidos 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 sub-propriedades. 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. (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, esse nome de função é prefixado pelo namespace de funções personalizadas especificado no arquivo de manifesto XML.
`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 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. 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 e `cancelable` .
`requiresAddress`	booliano	Não O valor padrão é `false`.	Se `true`, sua função personalizada pode 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 e `requiresAddress` .
`requiresParameterAddresses`	booliano	Não O valor padrão é `false`.	Se `true`, sua função personalizada pode 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 resultado e `dimensionality` deve ser definida como `matrix`. Consulte Detectar 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 é passado como o argumento da função de retorno de `StreamingInvocation.setResult` chamada. Para obter mais informações, consulte Fazer uma função de streaming.
`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 somente quando os valores dependentes da fórmula forem alterados. Uma função não pode usar as `stream` propriedades e `volatile` . Se as `stream` propriedades e `volatile` estiverem 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. Isso é exibido no IntelliSense do Excel.
`dimensionality`	string	Não	Deve ser `scalar` (um valor 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 que você use qualquer um dos três tipos anteriores. Se essa propriedade não for especificada, o tipo de dados será padrão para `any`.
`optional`	booliano	Não	Se for `true`, o parâmetro será opcional.
`repeating`	booliano	Não	Se `true`, os parâmetros forem preenchidos de uma matriz especificada. Observe 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	Deve 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`, `string`ou `any` (o que permite que você use qualquer um dos três tipos anteriores). Se essa propriedade não for especificada, o tipo de dados será padrão para `any`.

Associar os nomes de função com metadados JSON

Para que uma função funcione corretamente, você precisa associar a propriedade da id função à implementação 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ções 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 e name estão em maiúsculas, o que é uma prática recomendada ao descrever suas funções personalizadas. Você só precisa adicionar esse JSON se estiver preparando seu próprio arquivo JSON manualmente e não usar a regeneração automática. Para obter mais informações sobre a regeneração automática, consulte Metadados JSON de autogeneração 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 nomear sua função ou descobrir como localizar sua função usando o método JSON escrito à mão anteriormente.

Criar metadados JSON manualmente para funções personalizadas

Criar metadados e conectar-se ao manifesto

Exemplo de metadados JSON

Referência de metadados

allowCustomDataForDataTypeAny

allowErrorForDataTypeAny

funções

options

parâmetros

resultado

Associar os nomes de função com metadados JSON

Próximas etapas

Confira também

Comentários

Recursos adicionais