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

Este artigo fornece diretrizes e práticas recomendadas para nomear funções personalizadas e explica como localizá-las.

Diretrizes de nomenclatura de funções personalizadas

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

• id: identificador exclusivo usado no código.
• name: nome de exibição mostrado aos usuários. Pode ser localizado.

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

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

• Ambos devem começar com uma letra e ter pelo menos três caracteres.
• id: somente os caracteres de A a Z, 0 a 9, sublinhado e ponto final são permitidos.
• name: quaisquer caracteres alfabéticos Unicode, sublinhado e ponto final são permitidos.

O Excel exibe nomes de funções internas em letras maiúsculas (por exemplo, SUM). Use letras maiúsculas para suas funções personalizadas para ajudá-las a se misturar naturalmente.

Evite nomes que correspondam:

• Uma referência de célula (A1 a XFD1048576 ou R1C1 a R1048576C16384).
• Uma função de macro do Excel 4.0 (como RUN, ECHO). Para obter uma lista completa dessas funções, consulte este documento de Referência de Funções de Macro do Excel.

Conflitos de nomenclatura

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

Corrija conflitos renomeando sua função ou desinstalando o outro suplemento. Para testes em vários ambientes, use um prefixo de namespace curto (como ADDINNAME_FUNCTIONNAME).

Práticas recomendadas

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

Configuração de namespace

O namespace para suas funções personalizadas é configurado no arquivo de manifesto. A abordagem de configuração depende do tipo de manifesto que você está usando.

"customFunctions": {
  "namespace": {
    "id": "CONTOSO",
    "name": "CONTOSO"
  }
}

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

Localizar funções personalizadas

Você pode localizar os nomes de suplemento e de função personalizada. Adicione nomes de função localizados em seu arquivo JSON e defina substituições de localidade no manifesto somente do suplemento.

Localizar nomes de função

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

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

O JSON a seguir mostra como definir uma função com a id propriedade "MULTIPLY". A name propriedade and description da função é traduzida 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 seguinte 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 seu suplemento

Depois de criar um JSON para cada idioma, adicione uma substituição ao manifesto somente do suplemento que aponte para o arquivo correto. O XML de manifesto a seguir mostra uma localidade padrão en-us , além de uma URL de substituição do arquivo JSON 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 de Suplementos do Office.

Próximas etapas

Saiba mais sobre as práticas recomendadas de tratamento de erros.

Confira também

• Criar manualmente metadados JSON para funções personalizadas
• Tutorial de funções personalizadas do Excel