Создание пользовательских перечислений для пользовательских функций

Пользовательские перечисления предоставляют пользователям параметры автозаполнения Excel для пользовательских функций. Члены в перечислении отображаются в строке формул в виде предложений. Планеты на предыдущем снимке экрана являются примером пользовательского перечисления, которое предоставляет список наборов. В этой статье описывается создание пользовательских перечислений и их использование в качестве параметров в пользовательских функциях.

Определение пользовательского перечисления

Определите перечисление с помощью тега @customenumJSDoc . Затем соответствующие свойства JSON автоматически создаются в метаданных пользовательской функции. Дополнительные сведения о тегах JSDoc и пользовательских функциях см. в разделе Основные сведения о тегах JSDoc.

Примечание.

Пользовательские перечисления, созданные с помощью тега @customenum JSDoc, поддерживаются только в TypeScript. Они не поддерживаются в JavaScript. Чтобы использовать пользовательские перечисления с функциями JavaScript, необходимо вручную создать собственные метаданные JSON. Дополнительные сведения см . в статье Создание метаданных JSON вручную: перечисления.

В следующем фрагменте кода показано, как определить и использовать простое пользовательское перечисление в качестве параметра.

/** 
 * 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; 
} 

Использование настраиваемого перечисления несколько раз

Настраиваемое перечисление можно повторно использовать в нескольких функциях, и его можно использовать в качестве нескольких параметров одной функции. Функция также может иметь несколько перечислений в качестве параметров одновременно. Параметр перечисления может быть повторяющимся или необязательным.

В следующем примере кода показаны перечисление NUMBERS и пользовательская функция, которая использует перечисление несколько раз в качестве входного значения.

/**
* 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; 
}

Локализация пользовательских перечислений

Локализация пользовательских перечислений аналогична локализации пользовательских функций. Необходимо вручную создать метаданные JSON , а затем создать новый файл метаданных JSON для каждого языка.

Обратите внимание, что только name свойства и tooltip в перечислении должны быть локализованы на целевом языке. Свойство value должно оставаться неизменным, чтобы избежать необходимости обработки нескольких языков в теле функции.

В следующем фрагменте JSON показан локализованный values объект на китайском языке для планеты Mercury.

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

Обратная совместимость

Пользовательские перечисления обеспечивают обратную совместимость. В более старых версиях Excel параметры, использующие пользовательское перечисление, работают как стандартные параметры без отображения в списке автозаполнения Excel.

См. также

• Создание метаданных JSON вручную для пользовательских функций
• Автоматическое генерирование метаданных JSON для пользовательских функций