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

Если пользовательская функция Excel написана в JavaScript или TypeScript, теги JSDoc используются для предоставления дополнительной информации о пользовательской функции. Мы предоставляем подключаемый модуль Webpack , который использует эти теги JSDoc для автоматического создания файла метаданных JSON во время сборки. Использование подключаемого модуля избавляет вас от редактирования файла метаданных JSON вручную.

Важно!

Обратите внимание, что настраиваемые функции доступны в Excel на следующих платформах.

• Office в Интернете
• Office для Windows
  • Подписка на Microsoft 365
  • Розничный бессрочный Office 2016 и более поздних версий
  • Корпоративный бессрочный Office 2021 и более поздних версий
• Office для Mac

Пользовательские функции Excel в настоящее время не поддерживаются в следующих приложениях:

• Office для iPad
• корпоративные бессрочные версии Office 2019 или более ранних версий в Windows

CustomFunctionsMetadataPlugin

Подключаемый модуль — CustomFunctionsMetadataPlugin. Чтобы установить и настроить его, выполните следующие действия.

Примечание.

• Средство можно использовать только в проекте на основе NodeJS.
• В этих инструкциях предполагается, что проект использует Webpack и что он установлен и настроен.
• Если проект пользовательской надстройки-функции создается с помощью генератора Yeoman для надстроек Office, webpack устанавливается и все эти действия выполняются автоматически, но при необходимости необходимо вручную выполнить действия, описанные в разделе Несколько исходных файлов пользовательских функций .

1. Откройте командную строку или оболочку bash и в корневом каталоге проекта выполните команду npm install custom-functions-metadata-plugin.

2. Откройте файл webpack.config.js и добавьте следующую строку вверху: const CustomFunctionsMetadataPlugin = require("custom-functions-metadata-plugin");.

3. Прокрутите вниз до массива plugins и добавьте следующий код в начало массива. При необходимости измените input путь и имя файла в соответствии с проектом output , но значение должно быть "functions.json". Если вы используете TypeScript, используйте *.ts имя исходного файла, а не преобразованный файл *.js.

   new CustomFunctionsMetadataPlugin({
      output: "functions.json",
      input: "./src/functions/functions.js", 
   }),
   

Несколько исходных файлов пользовательских функций

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

1. В файле webpack.config.js замените строковое значение input массивом строковых URL-адресов, указывающих на каждый из файлов. Ниже приведен пример.

   new CustomFunctionsMetadataPlugin({
      output: "functions.json",
      input: [
               "./src/functions/someFunctions.js", 
               "./src/functions/otherFunctions.js"
             ], 
   }),
   

2. Прокрутите entry.functions до свойства и замените его значение тем же массивом, который использовался на предыдущем шаге. Ниже приведен пример.

   entry: {
      polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
      taskpane: ["./src/taskpane/taskpane.js", "./src/taskpane/taskpane.html"],
      functions: [
               "./src/functions/someFunctions.js", 
               "./src/functions/otherFunctions.js"
             ],
    },
   

Запуск средства

Вам не нужно ничего делать, чтобы запустить средство. При запуске Webpack создает файл functions.json и помещает его в память в режиме разработки или в папку /dist в рабочем режиме.

Основные сведения о тегах JSDoc

Добавьте тег @customfunction в примечаниях к коду для функции JavaScript или TypeScript, чтобы пометить ее как пользовательскую.

Типы параметров функции можно получить с помощью тега @param в JavaScript или из раздела Тип функции в TypeScript. Дополнительные сведения см. в разделах, посвященных тегу @param и типам.

Добавление описания в функцию

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

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

В следующем примере фраза "Вычисляет объем сферы" является описанием пользовательской функции.

/**
/* Calculates the volume of a sphere.
/* @customfunction VOLUME
...
 */

Поддерживаемые теги JSDoc

Следующие теги JSDoc поддерживаются в пользовательских функциях Excel.

• @cancelable
• имяидентификатора @customfunction
• URL-адрес @helpurl
• @param{type}namedescription
• @requiresAddress
• @requiresParameterAddresses
• @returns{type}
• @streaming
• @volatile

---

@cancelable

Указывает, что пользовательская функция выполняет действие при отмене функции.

В качестве типа последнего параметра функции должно быть указано CustomFunctions.CancelableInvocation. Функция может назначить функцию свойству oncanceled для обозначения результата при отмене функции.

Если тип последнего параметра функции CustomFunctions.CancelableInvocation, он будет рассматриваться как @cancelable, даже если тег отсутствует.

Функция не может содержать одновременно теги @cancelable и @streaming.

@customfunction

Синтаксис: @customfunctionимя идентификатора

Этот тег указывает, что функция JavaScript/TypeScript является пользовательской функцией Excel. Он требуется для создания метаданных для пользовательской функции.

Ниже показан пример этого тега.

/**
 * Increments a value once a second.
 * @customfunction
 * ...
 */

id

Идентифицирует id пользовательскую функцию.

• Если id не указан, название функции JavaScript или TypeScript преобразуется в верхний регистр, а недопустимые символы удаляются.
• id должен быть уникальным для всех пользовательских функций.
• Допустимые символы ограничены: A–Z, a–z, 0–9, символы подчеркивания (_) и точка (.).

В следующем примере increment — это параметр id и name функции.

/**
 * Increments a value once a second.
 * @customfunction INCREMENT
 * ...
 */

name

Предоставляет отображаемый параметр name для пользовательской функции.

• Если имя не указано, идентификатор также используется как имя.
• Допустимые символы: буквы в кодировке Юникод алфавита, цифры, точка (.) и символ подчеркивания (_).
• Имя должно начинаться с буквы.
• Максимальная длина: 128 символов.

В следующем примере INC — это параметр id функции, а increment — параметр name.

/**
 * Increments a value once a second.
 * @customfunction INC INCREMENT
 * ...
 */

description

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

В следующем примере фраза "A function that adds two numbers" (Функция, складывающая два числа) — это описание пользовательской функции со свойством id, имеющим значение ADD.

/**
 * A function that adds two numbers.
 * @customfunction ADD
 * ...
 */

@helpurl

Синтаксис: @helpurlurl-адрес

Предоставленный url-адрес отображается в Excel.

В следующем примере helpurl имеет значение http://www.contoso.com/weatherhelp.

/**
 * A function which streams the temperature in a town you specify.
 * @customfunction getTemperature
 * @helpurl http://www.contoso.com/weatherhelp
 * ...
 */

@param

JavaScript

Синтаксис JavaScript: @param {type} namedescription

• {type} указывает сведения о типе в фигурных скобках. Дополнительную информацию о типах, которые могут использоваться, см. в разделе Типы. Если тип не указан, будет использоваться тип any по умолчанию.
• name указывает параметр, к которому @param применяется тег. Это обязательно.
• description предоставляет описание, которое отображается в Excel для параметра функции. Это необязательно.

Чтобы указать параметр пользовательской функции как необязательный, поместите в квадратные скобки вокруг имени параметра. Например, @param {string} [text] Optional text.

Примечание.

Значение по умолчанию для дополнительных параметров — null.

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

/**
 * A function which sums two, or optionally three, numbers.
 * @customfunction ADDNUMBERS
 * @param firstNumber {number} First number to add.
 * @param secondNumber {number} Second number to add.
 * @param [thirdNumber] {number} Optional third number you wish to add.
 * ...
 */

TypeScript

Синтаксис TypeScript: @paramописание имени

• name указывает параметр, к которому @param применяется тег. Это обязательно.
• description предоставляет описание, которое отображается в Excel для параметра функции. Это необязательно.

Дополнительные сведения о типах параметров функций, которые могут использоваться, см. в разделе Типы.

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

• Используйте необязательный параметр. Пример: function f(text?: string)
• Задайте для параметра значение по умолчанию. Пример: function f(text: string = "abc")

Подробное описание @param см. в JSDoc

Примечание.

Значение по умолчанию для дополнительных параметров — null.

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

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number
 * @param second Second number
 * @returns The sum of the two numbers.
 */
function add(first: number, second: number): number {
  return first + second;
}

@requiresAddress

Указывает, что следует предоставлять адрес ячейки, в которой вычисляется функция.

Последний параметр функции должен иметь тип CustomFunctions.Invocation или производный тип для использования @requiresAddress. При вызове функции свойство address будет содержать адрес.

В следующем примере показано, как использовать invocation параметр в сочетании с для @requiresAddress возврата адреса ячейки, которая вызвала пользовательскую функцию. Дополнительные сведения см. в разделе Параметр вызова .

/**
 * Return the address of the cell that invoked the custom function. 
 * @customfunction
 * @param {number} first First parameter.
 * @param {number} second Second parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @requiresAddress 
 */
function getAddress(first, second, invocation) {
  const address = invocation.address;
  return address;
}

@requiresParameterAddresses

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

Последний параметр функции должен иметь тип CustomFunctions.Invocation или производный тип для использования @requiresParameterAddresses. Комментарий JSDoc также должен содержать тег, указывающий @returns , что возвращаемое значение является матрицей, например @returns {string[][]} или @returns {number[][]}. Дополнительные сведения см. в разделе Типы матриц .

При вызове parameterAddresses функции свойство будет содержать адреса входных параметров.

В следующем примере показано, как использовать invocation параметр в сочетании с для @requiresParameterAddresses возврата адресов трех входных параметров. Дополнительные сведения см. в разделе Определение адреса параметра .

/**
 * Return the addresses of three parameters. 
 * @customfunction
 * @param {string} firstParameter First parameter.
 * @param {string} secondParameter Second parameter.
 * @param {string} thirdParameter Third parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @returns {string[][]} The addresses of the parameters, as a 2-dimensional array.
 * @requiresParameterAddresses
 */
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
  const addresses = [
    [invocation.parameterAddresses[0]],
    [invocation.parameterAddresses[1]],
    [invocation.parameterAddresses[2]]
  ];
  return addresses;
}

@returns

Синтаксис: @returns {type}

Предоставляет тип для возвращаемого значения.

Если {type} не указан, будет использоваться информация о типе TypeScript. Если информация о типе отсутствует, будет использоваться тип any.

В следующем примере показана функция add, использующая тег @returns.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number
 * @param second Second number
 * @returns The sum of the two numbers.
 */
function add(first: number, second: number): number {
  return first + second;
}

@streaming

Используется для обозначения того, что пользовательская функция является потоковой передачей функции.

Последний параметр имеет тип CustomFunctions.StreamingInvocation<ResultType>. Функция возвращает void.

Функции потоковой передачи не возвращают значения напрямую, вместо этого они вызывают setResult(result: ResultType) с помощью последнего параметра.

Исключения, которые возникают при потоковой передаче функций, игнорируются. setResult() при вызове может вернуть ошибку в качестве результата. Пример функции потоковой передачи и дополнительные сведения см. в разделе Создание функции потоковой передачи.

Потоковые передачи функций невозможно пометить как @volatile.

@volatile

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

Потоковые передачи функций не могут быть переменными.

Следующая функция является переменной и использует тег @volatile.

/**
 * Simulates rolling a 6-sided die.
 * @customfunction
 * @volatile
 */
function roll6sided(): number {
  return Math.floor(Math.random() * 6) + 1;
}

---

Типы

Указывая тип параметра, Excel преобразует значения в этот тип, прежде чем вызывать функцию. Если указан тип any, преобразование выполняться не будет.

Типы значений

Одно значение может быть представлено с помощью одного из приведенных ниже типов: boolean, number, string.

Тип "матрица"

Используйте тип двумерного массива, чтобы параметр или возвращаемое значение представляли собой матрицу значений. Например, тип number[][] обозначает матрицу чисел и string[][] матрицу строк.

Тип "ошибка"

Функция непотоковой передачи может указывать на ошибку, возвращая тип "Ошибка".

Функция потоковой передачи может указывать на ошибку, вызывая метод setResult() типа "Ошибка".

Обещание

Пользовательская функция может возвращать обещание, которое предоставляет значение при разрешении обещания. Если обещание отклонено, пользовательская функция вызовет ошибку.

Другие типы

Любой другой тип будет рассматриваться как ошибка.

Дальнейшие действия

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

См. также

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