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.

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.

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"
        }
      ]
    }
  ]
}

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.

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.

funções

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

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.

parâmetros

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

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.

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

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