Partilhar via

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

  • Artigo

Este artigo descreve as diretrizes e as melhores práticas para atribuir nomes a funções personalizadas. Também mostra como localizar nomes de funções personalizadas para idiomas que não o inglês.

Diretrizes de nomenclatura de funções personalizadas

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

  • A função id é utilizada para identificar exclusivamente funções personalizadas no código JavaScript.
  • A função name é utilizada como o nome a apresentar que aparece a um utilizador 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
    • revenda perpétua do Office 2016 e posterior
    • Office 2021 perpétuo 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 2019 ou anterior no Windows

Uma função name pode ser diferente da função id, como para fins de localização. Em geral, as funções de uma função name devem permanecer iguais às id de se não existirem motivos para que sejam diferentes.

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

  • Uma função só id pode utilizar carateres A a Z, números de zero a nove, carateres de sublinhado e períodos.

  • Uma função name pode utilizar carateres alfabéticos Unicode, carateres de sublinhado e períodos.

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

O Excel utiliza letras maiúsculas para nomes de funções incorporados (como SUM). Utilize letras maiúsculas para as funções name personalizadas e id como melhor prática.

As funções de name uma função não devem ser as mesmas que:

Conflitos de nomenclatura

Se a função name for a mesma que uma função name num suplemento que já existe, o erro #REF! será apresentado no seu livro.

Para corrigir um conflito de nomenclatura, altere o name no suplemento e tente a função novamente. Também pode desinstalar o suplemento com o nome em conflito. Em alternativa, se estiver a testar o suplemento em ambientes diferentes, experimente utilizar um espaço de nomes diferente para diferenciar a 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 abreviaturas ambíguas em nomes de funções. A clareza é mais importante do que a brevidade. Escolha um nome como =INCREASETIME em vez de =INC.
  • Os nomes das funções devem indicar a ação da função, como =GETZIPCODE em vez de CÓDIGO POSTAL.
  • Utilize consistentemente os mesmos verbos para funções que executam ações semelhantes. Por exemplo, utilize =DELETEZIPCODE e =DELETEADDRESS, em vez de =DELETEZIPCODE e =REMOVEADDRESS.
  • Ao atribuir um nome a uma função de transmissão em fluxo, 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 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 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

Pode localizar o suplemento e os nomes das funções personalizadas. Para tal, forneça nomes de funções localizadas no ficheiro JSON das funções e informações de região no ficheiro de 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 novo ficheiro de metadados JSON para cada idioma. Em cada ficheiro JSON de idioma, adicione name e description propriedades no idioma de destino. O ficheiro predefinido para inglês tem o nome functions.json. Utilize a região no nome do ficheiro para cada ficheiro 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 é a forma como o Excel identifica a sua função como exclusiva e não deve ser alterada depois de ser definida.

Importante

Evite atribuir às suas funções um id ou name que seja uma função incorporada do Excel noutra linguagem, uma vez que esta situação entra em conflito com as funções localizadas.

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 ficheiro JSON para cada idioma, atualize o ficheiro de manifesto apenas do suplemento com um valor de substituição para cada região que especifique o URL de cada ficheiro de metadados JSON. O XML de manifesto seguinte mostra uma região predefinida en-us com um URL de ficheiro JSON de substituição para de-de (Alemanha). O ficheiro functions-de.json contém os nomes e IDs das funções alemãs localizadas.

<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