Nomenclatura y localización de funciones personalizadas

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.

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:

• Cualquier celda entre A1 a XFD1048576 o cualquier celda entre R1C1 y R1048576C16384.

• Cualquier función de macro de Excel 4.0 (como RUN, ECHO). Para obtener una lista completa de estas funciones, consulte este documento referencia de funciones de macros de Excel.

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.

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.

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.

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

• Creación manual de metadatos JSON para funciones personalizadas
• Tutorial de las funciones personalizadas de Excel