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

Проверка доступности API во время выполнения

  • Статья

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

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

Примечание.

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

Проверка поддержки набора требований

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

if (Office.context.requirements.isSetSupported("WordApi", "1.2")) {
   // Code that uses API members from the WordApi 1.2 requirement set.
} else {
   // Provide diminished experience here.
   // For example, run alternate code when the user's Word is
   // volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2).
}

Вот что нужно знать об этом коде:

  • Первый параметр является обязательным. Это строка, представляющая имя набора требований. Дополнительные сведения о доступных наборах обязательных элементов см. в статье Наборы обязательных элементов для надстроек Office.
  • Второй параметр является необязательным. Это строка, указывающая минимальную версию набора требований, которую приложение Office должно поддерживать для выполнения кода в if инструкции (например, "1.9"). Если не используется, предполагается версия "1.1".

Предупреждение

При вызове isSetSupported метода значение второго параметра (если указано) должно быть строкой, а не числом. Средство синтаксического анализа JavaScript не может различать числовые значения, такие как 1.1 и 1.10, тогда как он может использовать для строковых значений, таких как "1.1" и "1.10".

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

Приложение Office RequirementSetName
Excel ExcelApi
OneNote OneNoteApi
Outlook Mailbox
PowerPoint PowerPointApi
Word WordApi

Ниже приведен пример использования метода с одним из наборов требований модели Common API.

if (Office.context.requirements.isSetSupported('CustomXmlParts')) {
    // Run code that uses API members from the CustomXmlParts requirement set.
} else {
    // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set.
}

Примечание.

Метод isSetSupported и наборы требований для этих приложений доступны в последнем файле Office.js в CDN. Если вы не используете Office.js из СЕТИ CDN, надстройка может создать исключения, если используется старая версия библиотеки, в которой isSetSupported не определен. Дополнительные сведения см. в статье Использование последней библиотеки API JavaScript для Office.

Проверка поддержки бесзаписного API

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

Примечание.

Рекомендуем ограничить использование этого типа проверки в среде выполнения в коде надстройки.

В следующем примере кода проверяется, поддерживает document.setSelectedDataAsyncли приложение Office .

if (Office.context.document.setSelectedDataAsync) {
    // Run code that uses `document.setSelectedDataAsync`.
}

См. также