Criar enumerações personalizadas para suas funções personalizadas

As enumerações personalizadas fornecem aos usuários opções de Preenchimento Automático do Excel para suas funções personalizadas. Os membros em sua enumeração aparecem na barra de fórmulas como sugestões. Os planetas na captura de tela anterior são um exemplo de uma enumeração personalizada que fornece uma lista definida. Este artigo descreve como criar enumerações personalizadas e usá-las como parâmetros em suas funções personalizadas.

Definir a enumeração personalizada

Defina sua enumeração com a tag @customenumJSDoc . As propriedades JSON correspondentes são geradas automaticamente nos metadados da função personalizada. Para obter mais informações sobre tags JSDoc e funções customizadas, consulte Noções básicas de tags JSDoc.

O trecho de código a seguir mostra como definir e usar uma enumeração personalizada simples 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(planetName: PLANETS): any { 
  return planetName; 
} 

Usar uma enumeração personalizada várias vezes

Uma enumeração personalizada pode ser reutilizada em várias funções e pode ser usada como vários parâmetros de uma única função. Uma função também pode ter várias enumerações como parâmetros ao mesmo tempo. Um parâmetro de enumeração pode ser repetitivo ou opcional.

O exemplo de código a seguir mostra uma enumeração NUMBERS e uma função personalizada que usa a enumeração várias vezes como um 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; 
}

Localizar suas enumerações personalizadas

A localização de enumerações personalizadas é semelhante à localização de funções personalizadas. Você deve criar manualmente seus metadados JSON e, em seguida, criar um novo arquivo de metadados JSON para cada idioma.

Observe que somente as name propriedades and tooltip em uma enumeração devem ser localizadas no idioma de destino. A stringValue propriedade ou numberValue deve permanecer inalterada para evitar a necessidade de lidar com vários idiomas no corpo da função.

O trecho JSON a seguir mostra o objeto localizado values em chinês para o planeta Mercúrio.

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

Compatibilidade com versões anteriores

As enumerações personalizadas oferecem compatibilidade com versões anteriores. Em versões mais antigas do Excel, os parâmetros que usam uma enumeração personalizada funcionam como parâmetros padrão sem exibir na lista de Preenchimento Automático do Excel.

Confira também

• Criar manualmente metadados JSON para funções personalizadas
• Gerar metadados JSON automaticamente para funções personalizadas