Compartir a través de

Nomenclatura y localización de funciones personalizadas

  • Artículo

En este artículo se describen las directrices y los procedimientos recomendados para asignar nombres a funciones personalizadas. También se muestra cómo localizar nombres de función personalizados en idiomas distintos del inglés.

Directrices de nomenclatura de funciones personalizadas

Una función personalizada se identifica mediante una id propiedad y name en el archivo de metadatos JSON.

  • La función id se usa para identificar de forma única funciones personalizadas en el código JavaScript.
  • La función name se usa como el nombre para mostrar que aparece a un usuario en Excel.

Importante

Tenga en cuenta que las funciones personalizadas están disponibles en Excel en las siguientes plataformas.

  • Office en la web
  • Office en Windows
    • Suscripción a Microsoft 365
    • Retail perpetual Office 2016 y versiones posteriores
    • Licencia por volumen perpetua de Office 2021 y versiones posteriores
  • Office en Mac

Las funciones personalizadas de Excel no se admiten actualmente en lo siguiente:

  • Office en iPad
  • versiones perpetuas con licencia por volumen de Office 2019 o versiones anteriores en Windows

Una función name puede diferir de la función id, como con fines de localización. En general, las funciones name deben permanecer igual id que si no hay ninguna razón para que se diferencien.

Una función y nameid comparten algunos requisitos comunes.

  • Los de id una función solo pueden usar caracteres de A a Z, números de cero a nueve, caracteres de subrayado y puntos.

  • Las funciones name pueden usar caracteres alfabéticos Unicode, caracteres de subrayado y puntos.

  • Tanto la función name como id deben empezar con una letra y tener un límite mínimo de tres caracteres.

Excel usa letras mayúsculas para nombres de función integrados (como SUM). Use letras mayúsculas para la función name personalizada y id como procedimiento recomendado.

Una función no name debe ser la misma que la siguiente:

Conflictos de nomenclatura

Si la función name es la misma que una función name de un complemento que ya existe, aparecerá el error #REF! en el libro.

Para corregir un conflicto de nomenclatura, cambie en el name complemento e inténtelo de nuevo. También puede desinstalar el complemento con el nombre en conflicto. O bien, si va a probar el complemento en entornos diferentes, intente usar un espacio de nombres diferente para diferenciar la función (como NAMESPACE_NAMEOFFUNCTION).

Procedimientos recomendados

  • Considere la posibilidad de agregar varios argumentos a una función en lugar de crear varias funciones con los mismos nombres o similares.
  • Evite abreviaturas ambiguas en los nombres de función. La claridad es más importante que la brevedad. Elija un nombre como =INCREASETIME en lugar de =INC.
  • Los nombres de función deben indicar la acción de la función, como =GETZIPCODE en lugar de ZIPCODE.
  • Use constantemente los mismos verbos para las funciones que realizan acciones similares. Por ejemplo, use =DELETEZIPCODE y , =DELETEADDRESSen lugar de =DELETEZIPCODE y =REMOVEADDRESS.
  • Al asignar un nombre a una función de streaming, considere la posibilidad de agregar una nota a ese efecto en la descripción de la función o agregar STREAM al final del nombre de la función.

Sugerencia

Si va a probar el complemento en varios entornos (por ejemplo, en desarrollo, ensayo, demostración, etcetera). Se recomienda mantener un archivo de manifiesto diferente para cada entorno. En cada archivo de manifiesto, puede:

  • Especificar las direcciones URL que corresponden al entorno.
  • Personalizar valores de metadatos como DisplayName y etiquetas dentro de Resources para indicar el entorno, de modo que los usuarios finales puedan identificar el entorno correspondiente a un complemento de instalación de prueba.
  • Personalizar las funciones personalizadas namespace para indicar el entorno, si el complemento define funciones personalizadas.

Siguiendo esta guía simplificará el proceso de prueba y evitará problemas que, de lo contrario, se producirían cuando un complemento de instalación de prueba se transfiere simultáneamente a múltiples entornos.

Localización de funciones personalizadas

Puede localizar el complemento y los nombres de función personalizados. Para ello, proporcione nombres de función localizados en el archivo JSON de las funciones y la información de configuración regional en el archivo de manifiesto de solo complemento.

Importante

Los metadatos generados automáticamente no funcionan para la localización, por lo que debe actualizar el archivo JSON manualmente. Para obtener información sobre cómo hacerlo, consulte Creación manual de metadatos JSON para funciones personalizadas.

Localizar nombres de función

Para localizar las funciones personalizadas, cree un nuevo archivo de metadatos JSON para cada idioma. En cada archivo JSON de idioma, agregue name y description propiedades en el idioma de destino. El archivo predeterminado para inglés se denomina functions.json. Use la configuración regional del nombre de archivo para cada archivo JSON adicional, como functions-de.json para ayudar a identificarlos.

y namedescription aparecen en Excel y se localizan. Sin embargo, el id de cada función no está localizado. La id propiedad es cómo Excel identifica la función como única y no se debe cambiar una vez establecida.

Importante

Evite proporcionar a las funciones un id objeto o name que sea una función de Excel integrada en otro lenguaje, ya que esto entra en conflicto con las funciones localizadas.

En el siguiente JSON se muestra cómo definir una función con la id propiedad "MULTIPLY". La name propiedad y description de la función está localizada para alemán. Cada parámetro name y description también se localiza para alemán.

{
    "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 el JSON anterior con el siguiente 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"
        },
    ],
}

Localización del complemento

Después de crear un archivo JSON para cada idioma, actualice el archivo de manifiesto de solo complemento con un valor de invalidación para cada configuración regional que especifique la dirección URL de cada archivo de metadatos JSON. El siguiente XML de manifiesto muestra una configuración regional predeterminada en-us con una dirección URL del archivo JSON de invalidación para de-de (Alemania). El archivo functions-de.json contiene los nombres e identificadores de las funciones alemanas 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 obtener más información sobre el proceso de localización de un complemento, vea Localización para complementos de Office.

Siguientes pasos

Obtenga información sobre los procedimientos recomendados de control de errores.

Vea también