Compartir a través de

Nomenclatura y localización de funciones personalizadas

En este artículo se proporcionan directrices y procedimientos recomendados para asignar nombres a funciones personalizadas y se explica cómo localizarlas.

Directrices de nomenclatura de funciones personalizadas

Una función personalizada se identifica mediante y id en name los metadatos JSON.

  • id: identificador único usado en el código.
  • name: se muestra el nombre para mostrar a los usuarios. Se puede localizar.

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
    • Office 2021 perpetuo/LTSC con licencia por volumen 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 2021 o versiones anteriores en Windows

Nota:

El manifiesto unificado para Microsoft 365 no admite actualmente proyectos de funciones personalizadas. Debe usar el manifiesto de solo complemento para proyectos de funciones personalizadas. Para obtener más información, vea Manifiesto de complementos de Office.

Una función name puede diferir de para la id localización. Si no necesita localización, lo mejor es usar el mismo valor para ambos.

Una función y nameid comparten algunas reglas similares.

  • Ambos deben empezar con una letra y tener al menos tres caracteres.
  • id: solo se permiten los caracteres A–Z, 0–9, de subrayado y de punto.
  • name: se permiten caracteres alfabéticos Unicode, caracteres de subrayado y caracteres de punto.

Excel muestra nombres de función integrados en letras mayúsculas (por ejemplo, SUM). Use mayúsculas para las funciones personalizadas para ayudarles a mezclarse de forma natural.

Evite nombres que coincidan con:

Conflictos de nomenclatura

Si la función name entra en conflicto con uno de otro complemento, Excel muestra el error #REF!

Corrija los conflictos cambiando el nombre de la función o desinstalando el otro complemento. Para realizar pruebas en varios entornos, use un prefijo de espacio de nombres corto (como ADDINNAME_FUNCTIONNAME).

Procedimientos recomendados

  • Use argumentos de función adicionales en lugar de crear varios nombres de función similares. Por ejemplo, GETNAME(firstName, middleName, lastName) es más eficaz que tener funciones independientes como GETFIRSTNAME, GETMIDDLENAMEy GETLASTNAME.
  • Evite abreviaturas que no estén claras. Por ejemplo, INCREASETIME es más fácil de entender que INC.
  • Elija verbos de acción para los nombres de función. Use GETZIPCODE en lugar de solo ZIPCODE.
  • Sea coherente. Use el mismo verbo para acciones similares, como DELETEZIPCODE y DELETEADDRESS.
  • Para las funciones de streaming, agregue STREAM al nombre o incluya una nota en la descripción.
  • Use un prefijo de proveedor corto en los nombres de función para evitar conflictos con otros complementos. Por ejemplo, use CONTOSO_GETPRICE o CONTOSO_TAX_CALC.

Sugerencia

Si va a probar el complemento en varios entornos (por ejemplo, en desarrollo, ensayo, demostración, etc.), 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.

  • Personalice los valores de metadatos para que los usuarios finales puedan identificar el entorno correspondiente de un complemento cargado localmente. Por ejemplo:

    • En el manifiesto unificado para Microsoft 365, personalice la "name" propiedad del complemento y las "label" propiedades de varios controles de interfaz de usuario para indicar el entorno.
    • En el manifiesto de solo complemento, personalice el DisplayName elemento y las etiquetas dentro del Resources elemento para indicar el entorno.

  • 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.

Referencia rápida de restricciones de nomenclatura

Instrucciones id name Notas
Caracteres permitidos A–Z 0–9 _. Caracteres alfabéticos Unicode _. Mantenga id simple. Localización de name.
Debe empezar con una letra Sí Sí Evita la confusión de referencia de celda.
Longitud mínima 3 3 Los nombres cortos reducen la claridad.
Uso de mayúsculas Se recomiendan todas las mayúsculas Se recomiendan todas las mayúsculas Coincide con el estilo de Excel.
Localizable No Sí Manténgalo id estable. Localice name según sea necesario.
Puede imitar la dirección de celda No No Impedir errores de análisis de direcciones.
Nombres de macro reservados No permitido No permitido Algunos ejemplos: RUN, ECHO.

Localización de funciones personalizadas

Puede localizar el complemento y los nombres de función personalizados. Agregue nombres de función localizados en el archivo JSON y establezca invalidaciones de configuración regional en el 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 archivo de metadatos JSON independiente para cada idioma. En cada archivo, agregue las name propiedades y description en el idioma de destino. Use functions.json para inglés e incluya la configuración regional en el nombre de archivo para otros idiomas, como functions-de.json para alemán.

Excel solo localiza las name propiedades y description . No id está localizado y debe permanecer sin cambios después de su establecimiento.

Importante

Evite un id objeto o name que coincida con una función de Excel integrada en cualquier idioma.

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 JSON para cada idioma, agregue una invalidación al manifiesto de solo complemento que apunte al archivo correcto. El siguiente XML de manifiesto muestra una configuración regional predeterminada en-us más una dirección URL del archivo JSON de invalidación para de-de (Alemania).

<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.

Pasos siguientes

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

Vea también

  • Last updated on