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

Устранение проблем в пользовательских функциях

При разработке пользовательских функций могут возникать ошибки в продукте при создании и тестировании функций.

Важно!

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

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

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

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

Примечание.

В настоящее время унифицированный манифест для Microsoft 365 не поддерживает проекты пользовательских функций. Для проектов пользовательских функций необходимо использовать только манифест надстройки. Дополнительные сведения см. в разделе Манифест надстроек Office.

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

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

Сведения об отладке надстроек пользовательских функций, использующих общую среду выполнения, см. в статье Обзор отладки надстроек Office.

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

Включение ведения журнала в среде выполнения

Если вы тестируете надстройку в Office для Windows, следует включить ведение журнала среды выполнения. Ведение журнала в среде выполнения отправляет операторы console.log в отдельный файл журнала, созданный для выявления проблем. Инструкции охватывают различные ошибки, включая ошибки, связанные с файлом манифеста надстройки, условиями среды выполнения или установкой пользовательских функций. Дополнительные сведения о ведении журнала среды выполнения см. в статье Отладка надстройки с помощью журнала среды выполнения.

Проверка наличия сообщений об ошибках Excel

В Excel есть несколько встроенных сообщений об ошибках, возвращаемых в ячейку при возникновении ошибки вычислений. Для пользовательских функций используются только следующие сообщения об ошибках: #NULL!, #DIV/0!, #VALUE!, #REF!, #NAME?, #NUM!, #N/A и #BUSY!.

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

  • Ошибка #NAME? обычно означает проблему с регистрацией функции. Дополнительные сведения см. в разделе Пользовательские функции, отображающие ошибку #NAME?.
  • Ошибка #N/A может также указывать на то, что зарегистрированную функцию не удалось выполнить. Как правило, так происходит из-за отсутствия команды CustomFunctions.associate.
  • Ошибка #VALUE! обычно связана с файлом сценария функций.
  • Ошибка #REF! может указывать на то, что имя функции совпадает с именем другой функции, которая уже есть в надстройке.

Очистка кэша Office

Office помещает сведения о пользовательских функциях в кэш. Иногда при разработке и многократной повторной загрузке надстройки с пользовательскими функциями изменения могут не отображаться. Это можно исправить, очистив кэш Office. Дополнительные сведения см. в статье Очистка кэша Office.

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

Иногда может потребоваться очистить кэш пользовательских функций для надстройки, развернутой для конечных пользователей, чтобы одновременно включать обновления надстроек и изменения параметров настраиваемых функций. Без очистки кэша пользовательских функций изменения в functions.json и functions.js файлах могут занять до 24 часов, чтобы получить доступ к конечным пользователям, в то время как изменения вtaskpane.html быстрее доходят до конечных пользователей.

Примечание.

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

Чтобы обеспечить очистку кэша пользовательских функций надстройкой, добавьте следующий код в файлfunctions.js , а затем вызовите setForceRefreshOn метод в вызове Office.onReady или другой логике инициализации надстройки.

Важно!

Этот процесс очистки кэша пользовательских функций поддерживается только для надстроек пользовательских функций, использующих общую среду выполнения.

// To enable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOn` method in your `Office.onReady` call.
function setForceRefreshOn() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        true  
    );  
    Office.context.document.settings.saveAsync();  
}

Совет

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

Чтобы отключить очистку кэша пользовательских функций в надстройке, задайте для параметра Office.ForceRefreshCustomFunctionsCache значение false и вызовите метод в вызове Office.onReady . В следующем примере кода показан пример с методом setForceRefreshOff .

// To disable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOff` method in your `Office.onReady` call.
function setForceRefreshOff() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        false  
    );  
    Office.context.document.settings.saveAsync();  
}

Распространенные проблемы и решения

Пользовательские функции, отображающие #NAME? ошибка

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

Чтобы устранить эту проблему, попробуйте следующие подходы:

Не удается открыть надстройку из localhost: используйте исключение локального замыкания на себя

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

В журнале среды выполнения возникает сообщение об ошибке "TypeError: сетевой запрос не выполнен" в Excel для Windows

Если в вашем журнале среды выполнения отображается ошибка "TypeError: сетевой запрос не выполнен" при вызове сервера localhost, требуется включить исключение локального замыкания на себя. Дополнительные сведения о том, как это сделать, см. в разделе Вариант 2этой статьи от службы поддержки Майкрософт.

Проверка возвращения обещаний

Когда Excel ожидает завершения пользовательской функции, она отображается #BUSY! в ячейке. Если код пользовательской функции возвращает обещание, но это обещание не возвращает результат, Excel продолжит отображать сообщение #BUSY!. Проверьте свои функции, чтобы убедиться, что все обещания правильно возвращают результат в ячейку.

Ошибка: сервер разработки уже работает на порту 3000

Иногда во время работы npm start отображается ошибка с сообщением о том, что сервер разработки уже работает на порту 3000 (или на любом другом порту, который используется надстройкой). Можно остановить сервер разработки, выполнив npm stop или закрыв окно Node.js. В некоторых случаях для остановки работы сервера разработки может потребоваться несколько минут.

Мои функции не загружаются: свяжите функции

Если вы не зарегистрировали JSON и создали собственные метаданные JSON, может появиться сообщение об ошибке #VALUE! или уведомление о том, что надстройку не удается загрузить. Это обычно означает, что необходимо связать каждую пользовательскую функцию с ее свойством id, указанным в файле метаданных JSON. Для этого используется CustomFunctions.associate() функция . Как правило, этот вызов функции выполняется после каждой функции или в конце файла скрипта. Если пользовательская функция не связана, она не будет работать.

В примере ниже показана функция добавления, за которой следует имя функции add, связанное с соответствующим идентификатором JSON ADD.

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

CustomFunctions.associate("ADD", add);

Дополнительные сведения об этом процессе см. в статье Связывание имен функций с метаданными JSON.

Известные проблемы

Известные проблемы отслеживаются и сообщаются в репозитории GitHub пользовательских функций Excel.

Обратная связь

Если у вас возникают проблемы, не описанные в этой статье, сообщите нам. Сообщить о проблемах можно двумя способами.

В Excel в Windows или на Mac

Если вы используете Excel в Windows или Mac, вы можете сообщить об отзыве команде по расширению Office непосредственно из Excel. Для этого выберите Файл>Отзывы и предложения>Отправить нахмуренный смайлик. Отправка нахмуренного смайлика предоставит необходимые журналы для понимания проблемы, на которую вы указываете.

В GitHub

Вы можете сообщить о возникшей проблеме либо с помощью функции отзыва о содержимом внизу любой страницы с документацией или сообщить о новой проблеме непосредственно в репозитории пользовательских функций.

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

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

Дополнительные ресурсы

  • Last updated on