Compartilhar via

Nomenclatura e localização de funções personalizadas

Este artigo fornece diretrizes e melhores práticas para atribuir nomes a funções personalizadas e explica como localizá-las.

Diretrizes de nomenclatura de funções personalizadas

Uma função personalizada é identificada por um id e um name nos metadados JSON.

  • id: identificador exclusivo utilizado no código.
  • name: nome a apresentar apresentado aos utilizadores. Pode ser localizado.

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.

Uma função name pode ser diferente de id para localização. Se não precisar de localização, é melhor utilizar o mesmo valor para ambos.

Uma função é name e id partilha algumas regras semelhantes.

  • Ambos têm de começar com uma letra e ter, pelo menos, três carateres.
  • id: só são permitidos carateres A–Z, 0-9, caráter de sublinhado e ponto final.
  • name: todos os carateres alfabéticos Unicode, carateres de sublinhado e ponto final são permitidos.

O Excel apresenta nomes de funções incorporadas em letras maiúsculas (por exemplo, SUM). Utilize maiúsculas para as suas funções personalizadas para as ajudar a misturar-se naturalmente.

Evite nomes que correspondam:

Conflitos de nomenclatura

Se a sua função name entrar em conflito com uma de outro suplemento, o Excel mostra o erro #REF! .

Corrija conflitos ao mudar o nome da função ou ao desinstalar o outro suplemento. Para testar em vários ambientes, utilize um prefixo de espaço de nomes curto (como ADDINNAME_FUNCTIONNAME).

Práticas recomendadas

  • Utilize argumentos de função adicionais em vez de criar vários nomes de funções semelhantes. Por exemplo, GETNAME(firstName, middleName, lastName) é mais eficiente do que ter funções separadas como GETFIRSTNAME, GETMIDDLENAMEe GETLASTNAME.
  • Evite abreviaturas que não sejam claras. Por exemplo, INCREASETIME é mais fácil de compreender do que INC.
  • Selecione verbos de ação para nomes de funções. Utilize GETZIPCODE em vez de apenas ZIPCODE.
  • Seja consistente. Utilize o mesmo verbo para ações semelhantes, como DELETEZIPCODE e DELETEADDRESS.
  • Para funções de transmissão em fluxo, adicione STREAM ao nome ou inclua uma nota na descrição.
  • Utilize um prefixo de fornecedor curto nos nomes das funções para evitar conflitos com outros suplementos. Por exemplo, utilize CONTOSO_GETPRICE ou CONTOSO_TAX_CALC.

Dica

Se estiver a testar o suplemento em vários ambientes (por exemplo, em desenvolvimento, teste, demonstração, etc.), recomendamos que mantenha um ficheiro de manifesto diferente para cada ambiente. Em cada arquivo de manifesto, você pode:

  • Especificar as URLs que correspondem ao ambiente.

  • Personalize os valores de metadados para que os utilizadores finais consigam identificar o ambiente correspondente de um suplemento sideload. Por exemplo:

    • No manifesto unificado do Microsoft 365, personalize a "name" propriedade do suplemento e as "label" propriedades de vários controlos de IU para indicar o ambiente.
    • No manifesto apenas do suplemento, personalize o DisplayName elemento e as etiquetas no Resources elemento para indicar o ambiente.

  • Personalize o namespace de funções personalizadas para indicar o ambiente, se o suplemento definir funções personalizadas.

Seguindo essas diretrizes, você simplificará o processo de teste e evitará problemas que, de outra forma, ocorreriam quando um suplemento fosse carregado simultaneamente em vários ambientes.

Referência rápida das restrições de nomenclatura

Diretriz id name Observações
Caracteres permitidos A–Z 0-9 _. Carateres alfabéticos Unicode _. Mantenha-se id simples. Localize name.
Tem de começar com uma letra Sim Sim Evita confusões de referência de células.
Comprimento mínimo 3 3 Os nomes curtos reduzem a clareza.
Uso de maiúsculas Todas as maiúsculas recomendadas Todas as maiúsculas recomendadas Corresponde ao estilo do Excel.
Localizável Não Sim Mantenha-se id estável. Localize name conforme necessário.
Pode imitar o endereço da célula Não Não Impedir erros de análise de endereços.
Nomes de macros reservados Não permitido Não permitido Alguns exemplos: RUN, ECHO.

Localizar funções personalizadas

Pode localizar o suplemento e os nomes das funções personalizadas. Adicione nomes de funções localizadas no ficheiro JSON e defina substituições de região no manifesto apenas do suplemento.

Importante

Os metadados gerados automaticamente não funcionam para a localização, pelo que tem de atualizar o ficheiro JSON manualmente. Para saber como fazê-lo, veja Criar metadados JSON manualmente para funções personalizadas.

Localizar nomes de funções

Para localizar as suas funções personalizadas, crie um ficheiro de metadados JSON separado para cada idioma. Em cada ficheiro, adicione as name propriedades e description no idioma de destino. Utilize functions.json para inglês e inclua a região no nome do ficheiro para outros idiomas, como functions-de.json para alemão.

O Excel apenas localiza as name propriedades e description . O id não está localizado e deve permanecer inalterado depois de definido.

Importante

Evite um id ou name que corresponda a uma função incorporada do Excel em qualquer idioma.

O JSON seguinte mostra como definir uma função com a id propriedade "MULTIPLICAR". A name propriedade e description da função é localizada para alemão. Cada parâmetro name e description também é localizado para alemão.

{
    "id": "MULTIPLY",
    "name": "SUMME",
    "description": "Summe zwei Zahlen",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "eins",
            "description": "Erste Nummer",
            "dimensionality": "scalar"
        },
        {
            "name": "zwei",
            "description": "Zweite Nummer",
            "dimensionality": "scalar"
        }
    ]
}

Compare o JSON anterior com o seguinte JSON para inglês.

{
    "id": "MULTIPLY",
    "name": "MULTIPLY",
    "description": "Multiplies two numbers",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "one",
            "description": "first number",
            "dimensionality": "scalar"
        },
        {
            "name": "two",
            "description": "second number",
            "dimensionality": "scalar"
        }
    ]
}

Localizar o seu suplemento

Depois de criar um JSON para cada idioma, adicione uma substituição ao seu manifesto de suplemento apenas que aponte para o ficheiro correto. O XML do manifesto seguinte mostra uma região predefinida en-us e um URL de ficheiro JSON de substituição para de-de (Alemanha).

<DefaultLocale>en-us</DefaultLocale>
...
<Resources>
     <bt:Urls>
        <bt:Url id="Contoso.Functions.Metadata.Url" DefaultValue="https://localhost:3000/dist/functions.json"/>
          <bt:Override Locale="de-de" Value="https://localhost:3000/dist/functions-de.json" />
        </bt:url>
        
     </bt:Urls>
</Resources>

Para obter mais informações sobre o processo de localização de um suplemento, consulte Localização para Suplementos do Office.

Próximas etapas

Saiba mais sobre as melhores práticas de processamento de erros.

Confira também

  • Last updated on