Поделиться через

Вызов API JavaScript для Excel из пользовательской функции

  • Статья

Вызовите API JavaScript для Excel из пользовательских функций, чтобы получить данные диапазона и получить дополнительный контекст для вычислений. Вызов API JavaScript для Excel с помощью пользовательской функции может быть полезен, если:

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

Важно!

Чтобы вызвать API JavaScript для Excel из пользовательской функции, необходимо использовать общую среду выполнения. Используйте генератор Yeoman для надстроек Office, чтобы установить пользовательские функции Excel с помощью проекта общей среды выполнения . Дополнительные сведения см. в статье Настройка надстройки Office для использования общей среды выполнения .

Пример кода

Чтобы вызвать API JavaScript для Excel из пользовательской функции, сначала потребуется контекст. Используйте объект Excel.RequestContext для получения контекста. Затем используйте контекст для вызова API, необходимых в книге.

В следующем примере кода показано, как получить Excel.RequestContext значение из ячейки в книге. В этом примере address параметр передается в метод Worksheet.getRange API JavaScript для Excel и должен быть введен в виде строки. Например, пользовательская функция, введенная в пользовательский интерфейс Excel, должна соответствовать шаблону =CONTOSO.GETRANGEVALUE("A1"), где "A1" — это адрес ячейки, из которой извлекается значение.

/**
 * @customfunction
 * @param {string} address The address of the cell from which to retrieve the value.
 * @returns The value of the cell at the input address.
 **/
async function getRangeValue(address) {
 // Retrieve the context object. 
 const context = new Excel.RequestContext();
 
 // Use the context object to access the cell at the input address. 
 const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
 range.load("values");
 await context.sync();
 
 // Return the value of the cell at the input address.
 return range.values[0][0];
}

Ограничения вызова API JavaScript для Excel с помощью пользовательской функции

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

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

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

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

См. также