Share via

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

  • Artigo

Este artigo descreve diretrizes e práticas recomendadas para nomear funções personalizadas. Ele também mostra como localizar nomes de funções personalizadas em idiomas diferentes do inglês.

Diretrizes de nomenclatura de funções personalizadas

Uma função personalizada é identificada por uma id propriedade e name no arquivo de metadados JSON.

  • A função id é usada para identificar exclusivamente funções personalizadas em seu código JavaScript.
  • A função name é usada como o nome de exibição que aparece para um usuário no Excel.

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
    • varejo perpétuo Office 2016 e posterior
    • Office 2021 perpétuo licenciado por volume e posterior
  • Office no Mac

No momento, as funções personalizadas do Excel não têm suporte no seguinte:

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

Uma função name pode ser diferente da função id, como para fins de localização. Em geral, uma função name deve permanecer a mesma que a id se não houver motivo para que elas diferem.

Uma função é name e id compartilha alguns requisitos comuns.

  • Uma função só id pode usar caracteres A a Z, números zero a nove, sublinhados e períodos.

  • Uma função name pode usar caracteres alfabéticos Unicode, sublinhados e períodos.

  • Ambas as funções name e id devem começar com uma letra e ter um limite mínimo de três caracteres.

O Excel usa letras maiúsculas para nomes de função internos (como SUM). Use letras maiúsculas para suas funções name personalizadas e id como uma prática recomendada.

Uma função não name deve ser a mesma que:

Conflitos de nomenclatura

Se sua função name for a mesma que uma função name em um suplemento que já existe, o erro #REF! aparecerá em sua pasta de trabalho.

Para corrigir um conflito de nomenclatura, altere o name no suplemento e tente a função novamente. Você também pode desinstalar o suplemento com o nome conflitante. Ou, se você estiver testando seu suplemento em diferentes ambientes, tente usar um namespace diferente para diferenciar sua função (como NAMESPACE_NAMEOFFUNCTION).

Práticas recomendadas

  • Considere adicionar vários argumentos a uma função em vez de criar várias funções com os mesmos nomes ou nomes semelhantes.
  • Evite abreviações ambíguas em nomes de função. Clarity é mais importante do que a brevidade. Escolha um nome como =INCREASETIME em vez de =INC.
  • Os nomes de função devem indicar a ação da função, como =GETZIPCODE em vez de ZIPCODE.
  • Use consistentemente os mesmos verbos para funções que executam ações semelhantes. Por exemplo, use =DELETEZIPCODE e =DELETEADDRESS, em vez de =DELETEZIPCODE e =REMOVEADDRESS.
  • Ao nomear uma função de streaming, considere adicionar uma nota a esse efeito na descrição da função ou adicionar STREAM ao final do nome da função.

Dica

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

  • Especificar as URLs que correspondem ao ambiente.
  • Personalize valores de metadados como DisplayName e rótulos em Resources para indicar o ambiente, assim os usuários finais poderão identificar o ambiente correspondente de um suplemento por sideloaded.
  • 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.

Localizar funções personalizadas

Você pode localizar seu suplemento e seus nomes de função personalizados. Para fazer isso, forneça nomes de função localizados no arquivo JSON das funções e informações de localização no arquivo de manifesto XML.

Importante

Os metadados gerados automaticamente não funcionam para localização, portanto, você precisa atualizar o arquivo JSON manualmente. Para saber como fazer isso, consulte Criar metadados JSON manualmente para funções personalizadas.

Localizar nomes de funções

Para localizar suas funções personalizadas, crie um novo arquivo de metadados JSON para cada idioma. Em cada arquivo JSON de idioma, adicione name e description propriedades no idioma de destino. O arquivo padrão para inglês é nomeado functions.json. Use a localidade no nome do arquivo para cada arquivo JSON adicional, como functions-de.json para ajudar a identificá-los.

O name e description aparecem no Excel e são localizados. No entanto, a id de cada função não é localizada. A id propriedade é como o Excel identifica sua função como exclusiva e não deve ser alterada depois de definida.

Importante

Evite dar a suas funções uma id ou name que seja uma função interna do Excel em outro idioma, pois isso entra em conflito com funções localizadas.

O JSON a seguir mostra como definir uma função com a id propriedade "MULTIPLY". 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 JSON a seguir 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"
        },
    ],
}

Localize seu suplemento

Depois de criar um arquivo JSON para cada idioma, atualize seu arquivo de manifesto XML com um valor de substituição para cada localidade que especifica a URL de cada arquivo de metadados JSON. O XML do manifesto a seguir mostra uma localidade padrão en-us com uma URL de arquivo JSON de substituição para de-de (Alemanha). O arquivo functions-de.json contém os nomes e IDs de funções alemãs localizados.

<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 práticas recomendadas de tratamento de erros.

Confira também