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

As enumerações personalizadas dão aos utilizadores opções de Conclusão Automática do Excel para as suas funções personalizadas. Os membros na sua enumeração são apresentados na barra de fórmulas como sugestões. Os planetas na captura de ecrã anterior são um exemplo de uma enumeração personalizada que fornece uma lista definida. Este artigo descreve como criar enumerações personalizadas e utilizá-las como parâmetros nas suas funções personalizadas.

Definir a enumeração personalizada

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

Observação

As enumerações personalizadas criadas com a @customenum etiqueta JSDoc só são suportadas no TypeScript. Não são suportados no JavaScript. Para utilizar enumerações personalizadas com funções JavaScript, tem de criar manualmente os seus próprios metadados JSON. Para saber mais, veja Criar metadados JSON manualmente: enumerações.

O fragmento de código seguinte mostra como definir e utilizar uma enumeração personalizada simples como um 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; 
} 

Utilizar uma enumeração personalizada múltiplas vezes

Uma enumeração personalizada pode ser reutilizada em múltiplas funções e pode ser utilizada como múltiplos parâmetros de uma única função. Uma função também pode ter múltiplas enumerações como parâmetros ao mesmo tempo. Um parâmetro de enumeração pode ser repetido ou opcional.

O seguinte exemplo de código mostra uma NUMBERS enumeração e uma função personalizada que utiliza a enumeração múltiplas 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 as suas enumerações personalizadas

Localizar enumerações personalizadas é semelhante à localização de funções personalizadas. Tem de criar manualmente os metadados JSON e, em seguida, criar um novo ficheiro de metadados JSON para cada idioma.

Tenha em atenção que apenas as name propriedades e tooltip numa enumeração devem ser localizadas no idioma de destino. A value propriedade deve permanecer inalterada para evitar a necessidade de processar vários idiomas no corpo da função.

O fragmento JSON seguinte mostra o objeto localizado values da língua chinesa para o planeta Mercúrio.

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

Compatibilidade com versões anteriores

As enumerações personalizadas oferecem retrocompatibilidade. Em versões mais antigas do Excel, os parâmetros que utilizam uma enumeração personalizada funcionam como parâmetros padrão sem ser apresentados 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