Creación de enumeraciones personalizadas para las funciones personalizadas

Las enumeraciones personalizadas proporcionan a los usuarios opciones de Autocompletar de Excel para las funciones personalizadas. Los miembros de la enumeración se muestran en la barra de fórmulas como sugerencias. Los planetas de la captura de pantalla anterior son un ejemplo de una enumeración personalizada que proporciona una lista de conjuntos. En este artículo se describe cómo crear enumeraciones personalizadas y usarlas como parámetros en las funciones personalizadas.

Definición de la enumeración personalizada

Defina la enumeración con la etiqueta @customenumJSDoc . A continuación, las propiedades JSON correspondientes se generan automáticamente en los metadatos de la función personalizada. Para obtener más información sobre las etiquetas JSDoc y las funciones personalizadas, consulte Conceptos básicos de las etiquetas JSDoc.

Nota:

Las enumeraciones personalizadas creadas con la @customenum etiqueta JSDoc solo se admiten en TypeScript. No se admiten en JavaScript. Para usar enumeraciones personalizadas con funciones de JavaScript, debe crear manualmente sus propios metadatos JSON. Para más información, consulte Creación manual de metadatos JSON: enumeraciones.

El siguiente fragmento de código muestra cómo definir y usar una enumeración personalizada simple como parámetro.

/** 
 * A custom enum with descriptions and tooltips. 
 * @customenum {string} 
 */
enum PLANETS { 
  /** Mercury is the first planet from the sun. */ 
  mercury = "Mercury", 

  /** Venus is the second planet from the sun. */ 
  venus = "Venus", 

  /** Earth is the third planet from the sun. */ 
  earth = "Earth", 
} 

/** 
 * A sample function that uses the custom enum as a parameter.
 * @customfunction 
 */ 
function getPlanets(value: PLANETS): any { 
  return value; 
} 

Uso de una enumeración personalizada varias veces

Una enumeración personalizada se puede reutilizar en varias funciones y se puede usar como varios parámetros de una sola función. Una función también puede tener varias enumeraciones como parámetros al mismo tiempo. Un parámetro de enumeración puede ser repetitivo u opcional.

En el ejemplo de código siguiente se muestra una NUMBERS enumeración y una función personalizada que usa la enumeración varias veces como valor de entrada.

/**
* Enum of numbers with descriptions and tooltips.
* @customenum {number}
*/ 
enum NUMBERS {
  /** One */
  One = 1,

  /** Two */
  Two = 2,

  /** Three */
  Three = 3, 

  /** Four */
  Four = 4,

  /** Five */
  Five = 5
} 

/**
* Enter multiple numbers from the NUMBERS enum and get the sum.
* @customfunction
* @param input Enter enum numbers.
* @returns
*/
function addNumbers(input: NUMBERS[]): any {
  const sum = input.reduce((acc, num) => acc + num, 0); 
  return "Sum: " + sum; 
}

Localización de las enumeraciones personalizadas

La localización de enumeraciones personalizadas es similar a la localización de funciones personalizadas. Debe crear manualmente los metadatos JSON y, a continuación, crear un nuevo archivo de metadatos JSON para cada idioma.

Tenga en cuenta que solo las name propiedades y tooltip dentro de una enumeración deben localizarse en el idioma de destino. La value propiedad debe permanecer sin cambios para evitar la necesidad de controlar varios idiomas dentro del cuerpo de la función.

El siguiente fragmento de código JSON muestra el objeto localizado values en chino para el planeta Mercury.

"enums": [
    {
        "id": "PLANETS",
        "type": "string",
        "values": [
            {
                "name": "水星", 
                "value": "mercury",
                "tooltip": "水星是距离太阳最近的行星"
            }
        ]
    }
],

Compatibilidad con versiones anteriores

Las enumeraciones personalizadas ofrecen compatibilidad con versiones anteriores. En versiones anteriores de Excel, los parámetros que usan una enumeración personalizada funcionan como parámetros estándar sin mostrarse en la lista Autocompletar de Excel.

Vea también

• Creación manual de metadatos JSON para funciones personalizadas
• Generar automáticamente metadatos JSON de funciones personalizadas